[exo-jcr-commits] exo-jcr SVN: r2167 - in jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules: jcr and 1 other directories.
do-not-reply at jboss.org
do-not-reply at jboss.org
Fri Mar 26 09:04:09 EDT 2010
Author: sergiykarpenko
Date: 2010-03-26 09:04:08 -0400 (Fri, 26 Mar 2010)
New Revision: 2167
Added:
jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/logging.xml
Modified:
jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml
jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml
jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml
jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml
jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/configuration.xml
Log:
EXOJCR-605: doc about logging added; small changes in other docs
Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml
===================================================================
--- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml 2010-03-26 13:00:58 UTC (rev 2166)
+++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml 2010-03-26 13:04:08 UTC (rev 2167)
@@ -1,270 +1,270 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter>
- <?dbhtml filename="cluster-config.html"?>
-
- <title>Configuring JBoss AS with eXo JCR in cluster</title>
-
- <section>
- <title>Launching Cluster</title>
-
- <section>
- <title>Deploying eXo JCR to JBoss As</title>
-
- <para>To deploy eXo JCR to JBoss As follow next steps:</para>
-
- <orderedlist>
- <listitem>
- <para>Dowload the latest version of eXo JCR ear distribution.</para>
- </listitem>
-
- <listitem>
- <para>Copy <jcr.ear> into
- <%jboss_home%/server/default/deploy></para>
- </listitem>
-
- <listitem>
- <para>Put exo-configuration.xml to the root
- <%jboss_home%/exo-configuration.xml></para>
- </listitem>
-
- <listitem>
- <para>Configure JAAS by inserting XML fragment shown below into
- <%jboss_home%/server/default/conf/login-config.xml></para>
-
- <programlisting><application-policy name="exo-domain">
- <authentication>
- <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required"></login-module>
- </authentication>
-</application-policy></programlisting>
- </listitem>
-
- <listitem>
- <para>Ensure that you use JBossTS <link
- linkend="ch_transaction_service">Transaction Service</link> and
- JBossCache <link
- linkend="ch-jbossts-tranasction-service">Transaction Manager</link>.
- Your exo-configuration.xml must contain such parts:</para>
-
- <programlisting><component>
- <key>org.jboss.cache.transaction.TransactionManagerLookup</key>
- <type>org.jboss.cache.GenericTransactionManagerLookup</type>^
-</component>
-
-<component>
- <key>org.exoplatform.services.transaction.TransactionService</key>
- <type>org.exoplatform.services.transaction.jbosscache.JBossTransactionsService</type>
- <init-params>
- <value-param>
- <name>timeout</name>
- <value>300</value>
- </value-param>
- </init-params>
-</component></programlisting>
- </listitem>
-
- <listitem>
- <para>Start server:</para>
-
- <itemizedlist>
- <listitem>
- <para>bin/run.sh for Unix</para>
- </listitem>
-
- <listitem>
- <para>bin/run.bat for Windows</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Try accessing <ulink
- url="http://localhost:8080/browser">http://localhost:8080/browser</ulink>
- with root/exo as login/password if you have done everything right,
- you'll get access to repository browser.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section id="sect_conf_cluster_jcr">
- <title>Configuring JCR to use external configuration</title>
-
- <itemizedlist>
- <listitem>
- <para>To manually configure repository create a new configuration
- file (f.e. exo-jcr-configuration.xml). For details see <ulink
- url="http://wiki.exoplatform.org/xwiki/bin/view/JCR/#HConfiguration">JCR
- Configuration</ulink>. Your configuration must look like:</para>
-
- <programlisting><repository-service default-repository="repository1">
- <repositories>
- <repository name="repository1" system-workspace="ws1" default-workspace="ws1">
- <security-domain>exo-domain</security-domain>
- <access-control>optional</access-control>
- <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy>
- <workspaces>
- <workspace name="ws1">
- <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
- <properties>
- <property name="source-name" value="jdbcjcr" />
- <property name="dialect" value="oracle" />
- <property name="multi-db" value="false" />
- <property name="update-storage" value="false" />
- <property name="max-buffer-size" value="200k" />
- <property name="swap-directory" value="../temp/swap/production" />
- </properties>
- <value-storages>
- see "<link linkend="conf_value_storage">Value storage configuration</link>" part.
- </value-storages>
- </container>
- <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer">
- <properties>
- <property name="root-nodetype" value="nt:unstructured" />
- </properties>
- </initializer>
- <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache">
- see "<link linkend="conf_cache">Cache configuration</link>" part.
- </cache>
- <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
- see "<link linkend="conf_indexer">Indexer configuration</link>" part.
- </query-handler>
- <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
- see "<link linkend="conf_lock_manager">Lock Manager configuration</link>" part.
- </lock-manager>
- </workspace>
- <workspace name="ws2">
- ...
- </workspace>
- <workspace name="wsN">
- ...
- </workspace>
- </workspaces>
- </repository>
- </repositories>
-</repository-service> </programlisting>
- </listitem>
-
- <listitem>
- <para>and update RepositoryServiceConfiguration configuration in
- exo-configuration.xml to use this file:<programlisting><component>
- <key>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</key>
- <type>org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl</type>
- <init-params>
- <value-param>
- <name>conf-path</name>
- <description>JCR configuration file</description>
- <value>exo-jcr-configuration.xml</value>
- </value-param>
- </init-params>
-</component></programlisting></para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
- <section>
- <title>Requirements</title>
-
- <section>
- <title>Enviorenment requirements</title>
-
- <itemizedlist>
- <listitem>
- <para>Every node of cluster MUST have the same mounted Network File
- System with read and write permissions on it.</para>
-
- <para>"/mnt/tornado" - path to the mounted Network File System (all
- cluster nodes must use the same NFS)</para>
- </listitem>
-
- <listitem>
- <para>Every node of cluster MUST use the same database</para>
- </listitem>
-
- <listitem>
- <para>Same Clusters on different nodes MUST have the same cluster
- names (f.e if Indexer cluster in workspace production on the first
- node has name "production_indexer_cluster", then indexer clusters in
- workspace production on all other nodes MUST have the same name
- "production_indexer_cluster" )</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Enviorenment requirements</title>
-
- <para>Configuration of every workspace in repository must contains of
- such parts:</para>
-
- <itemizedlist>
- <listitem id="conf_value_storage">
- <para>Value Storage configuration:</para>
-
- <programlisting><value-storages>
- <value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
- <properties>
- <property name="path" value="/mnt/tornado/temp/values/production" /> <!--path within NFS where ValueStorage will hold it's data-->
- </properties>
- <filters>
- <filter property-type="Binary" />
- </filters>
- </value-storage>
-</value-storages></programlisting>
- </listitem>
-
- <listitem id="conf_cache">
- <para>Cache configuration:</para>
-
- <programlisting><cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache">
- <properties>
- <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-data.xml" /> <!-- path to JBoss Cache configuration for data storage -->
- <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> <!-- path to JGroups configuration -->
- <property name="jbosscache-cluster-name" value="JCR_Cluster_cache_production" /> <!-- JBoss Cache data storage cluster name -->
- <property name="jgroups-multiplexer-stack" value="true" />
- </properties>
-</cache> </programlisting>
- </listitem>
-
- <listitem id="conf_indexer">
- <para>Indexer configuration:</para>
-
- <programlisting><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
- <properties>
- <property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" />
- <property name="index-dir" value="/mnt/tornado/temp/jcrlucenedb/production" /> <!-- path within NFS where ValueStorage will hold it's data -->
- <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-indexer.xml" /> <!-- path to JBoss Cache configuration for indexer -->
- <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> <!-- path to JGroups configuration -->
- <property name="jbosscache-cluster-name" value="JCR_Cluster_indexer_production" /> <!-- JBoss Cache indexer cluster name -->
- <property name="jgroups-multiplexer-stack" value="true" />
- </properties>
-</query-handler> </programlisting>
- </listitem>
-
- <listitem id="conf_lock_manager">
- <para>Lock Manager configuration:</para>
-
- <programlisting><lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
- <properties>
- <property name="time-out" value="15m" />
- <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-lock.xml" /> <!-- path to JBoss Cache configuration for lock manager -->
- <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> <!-- path to JGroups configuration -->
- <property name="jgroups-multiplexer-stack" value="true" />
- <property name="jbosscache-cluster-name" value="JCR_Cluster_lock_production" /> <!-- JBoss Cache locks cluster name -->
-
- <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_production"/> <!-- the name of the DB table where lock's data will be stored -->
- <property name="jbosscache-cl-cache.jdbc.table.create" value="true"/>
- <property name="jbosscache-cl-cache.jdbc.table.drop" value="false"/>
- <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_production_pk"/>
- <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn"/>
- <property name="jbosscache-cl-cache.jdbc.node.column" value="node"/>
- <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent"/>
- <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr"/>
- </properties>
-</lock-manager></programlisting>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="ch_cluster_config">
+ <?dbhtml filename="ch-cluster-config.html"?>
+
+ <title>Configuring JBoss AS with eXo JCR in cluster</title>
+
+ <section>
+ <title>Launching Cluster</title>
+
+ <section>
+ <title>Deploying eXo JCR to JBoss As</title>
+
+ <para>To deploy eXo JCR to JBoss As follow next steps:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Dowload the latest version of eXo JCR ear distribution.</para>
+ </listitem>
+
+ <listitem>
+ <para>Copy <jcr.ear> into
+ <%jboss_home%/server/default/deploy></para>
+ </listitem>
+
+ <listitem>
+ <para>Put exo-configuration.xml to the root
+ <%jboss_home%/exo-configuration.xml></para>
+ </listitem>
+
+ <listitem>
+ <para>Configure JAAS by inserting XML fragment shown below into
+ <%jboss_home%/server/default/conf/login-config.xml></para>
+
+ <programlisting><application-policy name="exo-domain">
+ <authentication>
+ <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required"></login-module>
+ </authentication>
+</application-policy></programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Ensure that you use JBossTS <link
+ linkend="ch_transaction_service">Transaction Service</link> and
+ JBossCache <link
+ linkend="ch-jbossts-tranasction-service">Transaction Manager</link>.
+ Your exo-configuration.xml must contain such parts:</para>
+
+ <programlisting><component>
+ <key>org.jboss.cache.transaction.TransactionManagerLookup</key>
+ <type>org.jboss.cache.GenericTransactionManagerLookup</type>^
+</component>
+
+<component>
+ <key>org.exoplatform.services.transaction.TransactionService</key>
+ <type>org.exoplatform.services.transaction.jbosscache.JBossTransactionsService</type>
+ <init-params>
+ <value-param>
+ <name>timeout</name>
+ <value>300</value>
+ </value-param>
+ </init-params>
+</component></programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Start server:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>bin/run.sh for Unix</para>
+ </listitem>
+
+ <listitem>
+ <para>bin/run.bat for Windows</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Try accessing <ulink
+ url="http://localhost:8080/browser">http://localhost:8080/browser</ulink>
+ with root/exo as login/password if you have done everything right,
+ you'll get access to repository browser.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="sect_conf_cluster_jcr">
+ <title>Configuring JCR to use external configuration</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>To manually configure repository create a new configuration
+ file (f.e. exo-jcr-configuration.xml). For details see <ulink
+ url="http://wiki.exoplatform.org/xwiki/bin/view/JCR/#HConfiguration">JCR
+ Configuration</ulink>. Your configuration must look like:</para>
+
+ <programlisting><repository-service default-repository="repository1">
+ <repositories>
+ <repository name="repository1" system-workspace="ws1" default-workspace="ws1">
+ <security-domain>exo-domain</security-domain>
+ <access-control>optional</access-control>
+ <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy>
+ <workspaces>
+ <workspace name="ws1">
+ <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
+ <properties>
+ <property name="source-name" value="jdbcjcr" />
+ <property name="dialect" value="oracle" />
+ <property name="multi-db" value="false" />
+ <property name="update-storage" value="false" />
+ <property name="max-buffer-size" value="200k" />
+ <property name="swap-directory" value="../temp/swap/production" />
+ </properties>
+ <value-storages>
+ see "<link linkend="conf_value_storage">Value storage configuration</link>" part.
+ </value-storages>
+ </container>
+ <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer">
+ <properties>
+ <property name="root-nodetype" value="nt:unstructured" />
+ </properties>
+ </initializer>
+ <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache">
+ see "<link linkend="conf_cache">Cache configuration</link>" part.
+ </cache>
+ <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ see "<link linkend="conf_indexer">Indexer configuration</link>" part.
+ </query-handler>
+ <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
+ see "<link linkend="conf_lock_manager">Lock Manager configuration</link>" part.
+ </lock-manager>
+ </workspace>
+ <workspace name="ws2">
+ ...
+ </workspace>
+ <workspace name="wsN">
+ ...
+ </workspace>
+ </workspaces>
+ </repository>
+ </repositories>
+</repository-service> </programlisting>
+ </listitem>
+
+ <listitem>
+ <para>and update RepositoryServiceConfiguration configuration in
+ exo-configuration.xml to use this file:<programlisting><component>
+ <key>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</key>
+ <type>org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl</type>
+ <init-params>
+ <value-param>
+ <name>conf-path</name>
+ <description>JCR configuration file</description>
+ <value>exo-jcr-configuration.xml</value>
+ </value-param>
+ </init-params>
+</component></programlisting></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <section>
+ <title>Requirements</title>
+
+ <section>
+ <title>Enviorenment requirements</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Every node of cluster MUST have the same mounted Network File
+ System with read and write permissions on it.</para>
+
+ <para>"/mnt/tornado" - path to the mounted Network File System (all
+ cluster nodes must use the same NFS)</para>
+ </listitem>
+
+ <listitem>
+ <para>Every node of cluster MUST use the same database</para>
+ </listitem>
+
+ <listitem>
+ <para>Same Clusters on different nodes MUST have the same cluster
+ names (f.e if Indexer cluster in workspace production on the first
+ node has name "production_indexer_cluster", then indexer clusters in
+ workspace production on all other nodes MUST have the same name
+ "production_indexer_cluster" )</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Enviorenment requirements</title>
+
+ <para>Configuration of every workspace in repository must contains of
+ such parts:</para>
+
+ <itemizedlist>
+ <listitem id="conf_value_storage">
+ <para>Value Storage configuration:</para>
+
+ <programlisting><value-storages>
+ <value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">
+ <properties>
+ <property name="path" value="/mnt/tornado/temp/values/production" /> <!--path within NFS where ValueStorage will hold it's data-->
+ </properties>
+ <filters>
+ <filter property-type="Binary" />
+ </filters>
+ </value-storage>
+</value-storages></programlisting>
+ </listitem>
+
+ <listitem id="conf_cache">
+ <para>Cache configuration:</para>
+
+ <programlisting><cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache">
+ <properties>
+ <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-data.xml" /> <!-- path to JBoss Cache configuration for data storage -->
+ <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> <!-- path to JGroups configuration -->
+ <property name="jbosscache-cluster-name" value="JCR_Cluster_cache_production" /> <!-- JBoss Cache data storage cluster name -->
+ <property name="jgroups-multiplexer-stack" value="true" />
+ </properties>
+</cache> </programlisting>
+ </listitem>
+
+ <listitem id="conf_indexer">
+ <para>Indexer configuration:</para>
+
+ <programlisting><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ <property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" />
+ <property name="index-dir" value="/mnt/tornado/temp/jcrlucenedb/production" /> <!-- path within NFS where ValueStorage will hold it's data -->
+ <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-indexer.xml" /> <!-- path to JBoss Cache configuration for indexer -->
+ <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> <!-- path to JGroups configuration -->
+ <property name="jbosscache-cluster-name" value="JCR_Cluster_indexer_production" /> <!-- JBoss Cache indexer cluster name -->
+ <property name="jgroups-multiplexer-stack" value="true" />
+ </properties>
+</query-handler> </programlisting>
+ </listitem>
+
+ <listitem id="conf_lock_manager">
+ <para>Lock Manager configuration:</para>
+
+ <programlisting><lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
+ <properties>
+ <property name="time-out" value="15m" />
+ <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-lock.xml" /> <!-- path to JBoss Cache configuration for lock manager -->
+ <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> <!-- path to JGroups configuration -->
+ <property name="jgroups-multiplexer-stack" value="true" />
+ <property name="jbosscache-cluster-name" value="JCR_Cluster_lock_production" /> <!-- JBoss Cache locks cluster name -->
+
+ <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_production"/> <!-- the name of the DB table where lock's data will be stored -->
+ <property name="jbosscache-cl-cache.jdbc.table.create" value="true"/>
+ <property name="jbosscache-cl-cache.jdbc.table.drop" value="false"/>
+ <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_production_pk"/>
+ <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn"/>
+ <property name="jbosscache-cl-cache.jdbc.node.column" value="node"/>
+ <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent"/>
+ <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr"/>
+ </properties>
+</lock-manager></programlisting>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+</chapter>
Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml
===================================================================
--- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml 2010-03-26 13:00:58 UTC (rev 2166)
+++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml 2010-03-26 13:04:08 UTC (rev 2167)
@@ -1,251 +1,253 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter>
- <title>eXo JCR statistics</title>
-
- <section>
- <title>Statistics on the Database Access Layer</title>
-
- <para>In order to have a better idea of the time spent into the database
- access layer, it cans be interesting to get some statistics on that part
- of the code, knowing that most of the time spent into eXo JCR is mainly
- the database access. This statistics will then allow you to identify
- without using any profiler what is anormally slow in this layer, which
- could help to fix the problem quickly.</para>
-
- <para>In case you use
- <envar>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</envar>
- or
- <envar>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</envar>
- as <envar>WorkspaceDataContainer</envar>, you can get statistics on the
- time spent into the database access layer. The database access layer (in
- eXo JCR) is represented by the methods of the interface
- <envar>org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</envar>,
- so for all the methods defined in this interface, we can have the
- following figures: </para>
-
- <itemizedlist>
- <listitem>
- <para>The minimum time spent into the method.</para>
- </listitem>
-
- <listitem>
- <para>The maximum time spent into the method.</para>
- </listitem>
-
- <listitem>
- <para>The average time spent into the method.</para>
- </listitem>
-
- <listitem>
- <para>The total amount of time spent into the method.</para>
- </listitem>
-
- <listitem>
- <para>The total amount of times the method has been called.</para>
- </listitem>
- </itemizedlist>
-
- <para>Those figures are also available globaly for all the methods which
- gives us the global behavior of this layer.</para>
-
- <para>If you want to enable the statistics, you just need to set the JVM
- parameter called
- <emphasis>JDBCWorkspaceDataContainer.statistics.enabled</emphasis> to
- <emphasis>true</emphasis>. This will then create at startup a file called
- <emphasis>StatisticsJDBCStorageConnection-${creation-timestamp}.csv</emphasis>
- into the user directory if it is possible otherwise it will create it into
- the temporary directory. The format of this file is <envar>CSV</envar>
- (i.e. Comma-Seperated Values), one new line will be added every 5 seconds
- and one last line will be added at JVM exit. Each line, will be composed
- of the 5 figures described above for each method and globaly for all the
- methods.</para>
-
- <para>The format of each column header is
- ${method-alias}-${metric-alias}.</para>
-
- <table>
- <title>Method Alias</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>global</entry>
-
- <entry>This is the alias for all the methods.</entry>
- </row>
-
- <row>
- <entry>getItemDataById</entry>
-
- <entry>This is the alias for the method
- <emphasis>getItemData(String identifier).</emphasis></entry>
- </row>
-
- <row>
- <entry>getItemDataByNodeDataNQPathEntry</entry>
-
- <entry>This is the alias for the method
- <emphasis>getItemData(NodeData parentData, QPathEntry
- name).</emphasis></entry>
- </row>
-
- <row>
- <entry>getChildNodesData</entry>
-
- <entry>This is the alias for the method
- <emphasis>getChildNodesData(NodeData parent).</emphasis></entry>
- </row>
-
- <row>
- <entry>getChildNodesCount</entry>
-
- <entry>This is the alias for the method
- <emphasis>getChildNodesCount(NodeData parent).</emphasis></entry>
- </row>
-
- <row>
- <entry>getChildPropertiesData</entry>
-
- <entry>This is the alias for the method
- <emphasis>getChildPropertiesData(NodeData
- parent).</emphasis></entry>
- </row>
-
- <row>
- <entry>listChildPropertiesData</entry>
-
- <entry>This is the alias for the method
- <emphasis>listChildPropertiesData(NodeData
- parent).</emphasis></entry>
- </row>
-
- <row>
- <entry>getReferencesData</entry>
-
- <entry>This is the alias for the method
- <emphasis>getReferencesData(String
- nodeIdentifier).</emphasis></entry>
- </row>
-
- <row>
- <entry>commit</entry>
-
- <entry>This is the alias for the method
- <emphasis>commit().</emphasis></entry>
- </row>
-
- <row>
- <entry>addNodeData</entry>
-
- <entry>This is the alias for the method <emphasis>add(NodeData
- data).</emphasis></entry>
- </row>
-
- <row>
- <entry>addPropertyData</entry>
-
- <entry>This is the alias for the method <emphasis>add(PropertyData
- data).</emphasis></entry>
- </row>
-
- <row>
- <entry>updateNodeData</entry>
-
- <entry>This is the alias for the method <emphasis>update(NodeData
- data).</emphasis></entry>
- </row>
-
- <row>
- <entry>updatePropertyData</entry>
-
- <entry>This is the alias for the method
- <emphasis>update(PropertyData data).</emphasis></entry>
- </row>
-
- <row>
- <entry>deleteNodeData</entry>
-
- <entry>This is the alias for the method <emphasis>delete(NodeData
- data).</emphasis></entry>
- </row>
-
- <row>
- <entry>deletePropertyData</entry>
-
- <entry>This is the alias for the method
- <emphasis>delete(PropertyData data).</emphasis></entry>
- </row>
-
- <row>
- <entry>renameNodeData</entry>
-
- <entry>This is the alias for the method <emphasis>rename(NodeData
- data).</emphasis></entry>
- </row>
-
- <row>
- <entry>rollback</entry>
-
- <entry>This is the alias for the method
- <emphasis>rollback().</emphasis></entry>
- </row>
-
- <row>
- <entry>isOpened</entry>
-
- <entry>This is the alias for the method
- <emphasis>isOpened().</emphasis></entry>
- </row>
-
- <row>
- <entry>close</entry>
-
- <entry>This is the alias for the method
- <emphasis>close().</emphasis></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table>
- <title>Metric Alias</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>Min</entry>
-
- <entry>The minimum time spent into the method.</entry>
- </row>
-
- <row>
- <entry>Max</entry>
-
- <entry>The maximum time spent into the method.</entry>
- </row>
-
- <row>
- <entry>Total</entry>
-
- <entry>The total amount of time spent into the method.</entry>
- </row>
-
- <row>
- <entry>Avg</entry>
-
- <entry>The average time spent into the method.</entry>
- </row>
-
- <row>
- <entry>Times</entry>
-
- <entry>The total amount of times the method has been
- called.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="ch_statistics">
+ <?dbhtml filename="ch-statistics"?>
+
+ <title>eXo JCR statistics</title>
+
+ <section>
+ <title>Statistics on the Database Access Layer</title>
+
+ <para>In order to have a better idea of the time spent into the database
+ access layer, it cans be interesting to get some statistics on that part
+ of the code, knowing that most of the time spent into eXo JCR is mainly
+ the database access. This statistics will then allow you to identify
+ without using any profiler what is anormally slow in this layer, which
+ could help to fix the problem quickly.</para>
+
+ <para>In case you use
+ <envar>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</envar>
+ or
+ <envar>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</envar>
+ as <envar>WorkspaceDataContainer</envar>, you can get statistics on the
+ time spent into the database access layer. The database access layer (in
+ eXo JCR) is represented by the methods of the interface
+ <envar>org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</envar>,
+ so for all the methods defined in this interface, we can have the
+ following figures: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The minimum time spent into the method.</para>
+ </listitem>
+
+ <listitem>
+ <para>The maximum time spent into the method.</para>
+ </listitem>
+
+ <listitem>
+ <para>The average time spent into the method.</para>
+ </listitem>
+
+ <listitem>
+ <para>The total amount of time spent into the method.</para>
+ </listitem>
+
+ <listitem>
+ <para>The total amount of times the method has been called.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Those figures are also available globaly for all the methods which
+ gives us the global behavior of this layer.</para>
+
+ <para>If you want to enable the statistics, you just need to set the JVM
+ parameter called
+ <emphasis>JDBCWorkspaceDataContainer.statistics.enabled</emphasis> to
+ <emphasis>true</emphasis>. This will then create at startup a file called
+ <emphasis>StatisticsJDBCStorageConnection-${creation-timestamp}.csv</emphasis>
+ into the user directory if it is possible otherwise it will create it into
+ the temporary directory. The format of this file is <envar>CSV</envar>
+ (i.e. Comma-Seperated Values), one new line will be added every 5 seconds
+ and one last line will be added at JVM exit. Each line, will be composed
+ of the 5 figures described above for each method and globaly for all the
+ methods.</para>
+
+ <para>The format of each column header is
+ ${method-alias}-${metric-alias}.</para>
+
+ <table>
+ <title>Method Alias</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>global</entry>
+
+ <entry>This is the alias for all the methods.</entry>
+ </row>
+
+ <row>
+ <entry>getItemDataById</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>getItemData(String identifier).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>getItemDataByNodeDataNQPathEntry</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>getItemData(NodeData parentData, QPathEntry
+ name).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>getChildNodesData</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>getChildNodesData(NodeData parent).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>getChildNodesCount</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>getChildNodesCount(NodeData parent).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>getChildPropertiesData</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>getChildPropertiesData(NodeData
+ parent).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>listChildPropertiesData</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>listChildPropertiesData(NodeData
+ parent).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>getReferencesData</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>getReferencesData(String
+ nodeIdentifier).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>commit</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>commit().</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>addNodeData</entry>
+
+ <entry>This is the alias for the method <emphasis>add(NodeData
+ data).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>addPropertyData</entry>
+
+ <entry>This is the alias for the method <emphasis>add(PropertyData
+ data).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>updateNodeData</entry>
+
+ <entry>This is the alias for the method <emphasis>update(NodeData
+ data).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>updatePropertyData</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>update(PropertyData data).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>deleteNodeData</entry>
+
+ <entry>This is the alias for the method <emphasis>delete(NodeData
+ data).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>deletePropertyData</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>delete(PropertyData data).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>renameNodeData</entry>
+
+ <entry>This is the alias for the method <emphasis>rename(NodeData
+ data).</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>rollback</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>rollback().</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>isOpened</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>isOpened().</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>close</entry>
+
+ <entry>This is the alias for the method
+ <emphasis>close().</emphasis></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table>
+ <title>Metric Alias</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Min</entry>
+
+ <entry>The minimum time spent into the method.</entry>
+ </row>
+
+ <row>
+ <entry>Max</entry>
+
+ <entry>The maximum time spent into the method.</entry>
+ </row>
+
+ <row>
+ <entry>Total</entry>
+
+ <entry>The total amount of time spent into the method.</entry>
+ </row>
+
+ <row>
+ <entry>Avg</entry>
+
+ <entry>The average time spent into the method.</entry>
+ </row>
+
+ <row>
+ <entry>Times</entry>
+
+ <entry>The total amount of times the method has been
+ called.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+</chapter>
Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml
===================================================================
--- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml 2010-03-26 13:00:58 UTC (rev 2166)
+++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml 2010-03-26 13:04:08 UTC (rev 2167)
@@ -1,1088 +1,1089 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter>
- <title>eXo Cache</title>
-
- <section>
- <title>Basic concepts</title>
-
- <para>All applications on the top of eXo JCR that need a cache, can rely
- on an <envar>org.exoplatform.services.cache.ExoCache</envar> instance that
- is managed by the
- <envar>org.exoplatform.services.cache.CacheService</envar>. The main
- implementation of this service is
- <envar>org.exoplatform.services.cache.impl.CacheServiceImpl</envar> which
- depends on the
- <envar>org.exoplatform.services.cache.ExoCacheConfig</envar> in order to
- create new <envar>ExoCache</envar> instances. See below an example of
- <envar>org.exoplatform.services.cache.CacheService</envar>
- definition:<programlisting> <component>
- <key>org.exoplatform.services.cache.CacheService</key>
- <jmx-name>cache:type=CacheService</jmx-name>
- <type>org.exoplatform.services.cache.impl.CacheServiceImpl</type>
- <init-params>
- <object-param>
- <name>cache.config.default</name>
- <description>The default cache configuration</description>
- <object type="org.exoplatform.services.cache.ExoCacheConfig">
- <field name="name"><string>default</string></field>
- <field name="maxSize"><int>300</int></field>
- <field name="liveTime"><long>600</long></field>
- <field name="distributed"><boolean>false</boolean></field>
- <field name="implementation"><string>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</string></field>
- </object>
- </object-param>
- </init-params>
- </component></programlisting></para>
-
- <para><note>
- <para>The <envar>ExoCacheConfig</envar> which name is
- <envar>default</envar>, will be the default configuration of all the
- <envar>ExoCache</envar> instances that don't have dedicated
- configuration.</para>
- </note>See below an example of how to define a new
- <envar>ExoCacheConfig</envar> thanks to a
- <emphasis>external-component-plugin</emphasis>:<programlisting> <external-component-plugins>
- <target-component>org.exoplatform.services.cache.CacheService</target-component>
- <component-plugin>
- <name>addExoCacheConfig</name>
- <set-method>addExoCacheConfig</set-method>
- <type>org.exoplatform.services.cache.ExoCacheConfigPlugin</type>
- <description>Configures the cache for query service</description>
- <init-params>
- <object-param>
- <name>cache.config.wcm.composer</name>
- <description>The default cache configuration</description>
- <object type="org.exoplatform.services.cache.ExoCacheConfig">
- <field name="name"><string>wcm.composer</string></field>
- <field name="maxSize"><int>300</int></field>
- <field name="liveTime"><long>600</long></field>
- <field name="distributed"><boolean>false</boolean></field>
- <field name="implementation"><string>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</string></field>
- </object>
- </object-param>
- </init-params>
- </component-plugin>
- </external-component-plugins></programlisting></para>
-
- <table>
- <title>Descriptions of the fields of
- <envar>ExoCacheConfig</envar></title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>name</entry>
-
- <entry>The name of the cache. This field is mandatory since it
- will be used to retrieve the <envar>ExoCacheConfig</envar>
- corresponding to a given cache name.</entry>
- </row>
-
- <row>
- <entry>label</entry>
-
- <entry>The label of the cache. This field is optional. It is
- mainly used to indicate the purpose of the cache.</entry>
- </row>
-
- <row>
- <entry>maxSize</entry>
-
- <entry>The maximum numbers of elements in cache. This field is
- mandatory.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The amount of time (in seconds) an element is not written
- or read before it is evicted. This field is mandatory.</entry>
- </row>
-
- <row>
- <entry>implementation</entry>
-
- <entry>The full qualified name of the cache implementation to use.
- This field is optional. This field is only used for simple cache
- implementation. The default and main implementation is
- <envar>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</envar>,
- this implementation only works with local caches with FIFO as
- eviction policy. For more complex implementation see the next
- sections.</entry>
- </row>
-
- <row>
- <entry>distributed</entry>
-
- <entry>Indicates if the cache is distributed. This field is
- optional. This field is used for backward compatibility.</entry>
- </row>
-
- <row>
- <entry>replicated</entry>
-
- <entry>Indicates if the cache is replicated. This field is
- optional. This field is deprecated.</entry>
- </row>
-
- <row>
- <entry>logEnabled</entry>
-
- <entry>Indicates if the log is enabled. This field is optional.
- This field is used for backward compatibility.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para></para>
- </section>
-
- <section>
- <title>eXo Cache extension</title>
-
- <para>In the previous versions of eXo kernel, it was quite complex to
- implement your own ExoCache because it was not open enough. Since kernel
- 2.0.8, it is possible to easily integrate your favorite cache provider in
- eXo Products.</para>
-
- <para>You just need to implement your own <envar>ExoCacheFactory</envar>
- and register it in an eXo container, as described below:<programlisting>package org.exoplatform.services.cache;
-...
-public interface ExoCacheFactory {
-
- /**
- * Creates a new instance of {@link org.exoplatform.services.cache.ExoCache}
- * @param config the cache to create
- * @return the new instance of {@link org.exoplatform.services.cache.ExoCache}
- * @exception ExoCacheInitException if an exception happens while initializing the cache
- */
- public ExoCache createCache(ExoCacheConfig config) throws ExoCacheInitException;
-}</programlisting></para>
-
- <para>As you can see, there is only one method to implement which cans be
- seen as a converter of an <envar>ExoCacheConfig</envar> to get an instance
- of <envar>ExoCache</envar>. Once, you created your own implementation you
- can simply register your factory by adding a file
- <emphasis>conf/portal/configuration.xml</emphasis> with a content of the
- following type:<programlisting><configuration>
- <component>
- <key>org.exoplatform.services.cache.ExoCacheFactory</key>
- <type>org.exoplatform.tutorial.MyExoCacheFactoryImpl</type>
- ...
- </component>
-</configuration></programlisting></para>
- </section>
-
- <section>
- <title>eXo Cache based on JBoss Cache</title>
-
- <section>
- <title>Configure the ExoCacheFactory</title>
-
- <para>When you add, the eXo library in your classpath, the eXo service
- container will use the default configuration provided in the library
- itself but of course you can still redefined the configuration if you
- wish as you can do with any components.</para>
-
- <para>The default configuration of the factory is:<programlisting><configuration>
- <component>
- <key>org.exoplatform.services.cache.ExoCacheFactory</key>
- <type>org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryImpl</type>
- <init-params>
- <value-param>
- <name>cache.config.template</name>
- <value>jar:/conf/portal/cache-configuration-template.xml</value>
- </value-param>
- </init-params>
- </component>
-</configuration></programlisting></para>
-
- <para>As you can see the factory requires one single parameter which is
- <emphasis>cache.config.template</emphasis>, this parameter allows you to
- define the location of the default configuration template of your jboss
- cache. In the default configuration, we ask the eXo container to get the
- file shipped into the jar at
- <emphasis>/conf/portal/cache-configuration-template.xml</emphasis>.</para>
-
- <para>The default configuration template aims to be the skeleton from
- which we will create any type of jboss cache instance, thus it must be
- very generic.<note>
- <para>The default configuration template provided with the jar aims
- to work with any application servers, but if you intend to use JBoss
- AS, you should redefine it in your custom configuration to fit
- better with your AS.</para>
- </note></para>
- </section>
-
- <section>
- <title>Add specific configuration for a cache</title>
-
- <para>If for a given reason, you need to use a specific configuration
- for a cache, you can register one thanks to an "<emphasis>external
- plugin</emphasis>", see an example below:<programlisting><configuration>
- ...
- <external-component-plugins>
- <target-component>org.exoplatform.services.cache.ExoCacheFactory</target-component>
- <component-plugin>
- <name>addConfig</name>
- <set-method>addConfig</set-method>
- <type>org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryConfigPlugin</type>
- <description>add Custom Configurations</description>
- <init-params>
- <value-param>
- <name>myCustomCache</name>
- <value>jar:/conf/portal/custom-cache-configuration.xml</value>
- </value-param>
- </init-params>
- </component-plugin>
- </external-component-plugins>
- ...
-</configuration></programlisting></para>
-
- <para>In the example above, I call the method
- <emphasis>addConfig(ExoCacheFactoryConfigPlugin plugin)</emphasis> on
- the current implementation of <envar>ExoCacheFactory</envar> which is
- actually the jboss cache implementation.</para>
-
- <para>In the <emphasis>init-params</emphasis> block, you can define a
- set of <emphasis>value-param</emphasis> blocks and for each
- <emphasis>value-param</emphasis>, we expect the name of cache that needs
- a specific configuration as name and the location of your custom
- configuration as <emphasis>value</emphasis>.</para>
-
- <para>In this example, we indicates to the factory that we would like
- that the cache <emphasis>myCustomCache</emphasis> use the configuration
- available at
- <emphasis>jar:/conf/portal/custom-cache-configuration.xml</emphasis>.</para>
- </section>
-
- <section>
- <title>Add a cache creator</title>
-
- <section>
- <title>Understanding a cache creator</title>
-
- <para>The factory for jboss cache, delegates the cache creation to
- <envar>ExoCacheCreator</envar> that is defines as
- below:<programlisting>package org.exoplatform.services.cache.impl.jboss;
-...
-public interface ExoCacheCreator {
-
- /**
- * Creates an eXo cache according to the given configuration {@link org.exoplatform.services.cache.ExoCacheConfig}
- * @param config the configuration of the cache to apply
- * @param cache the cache to initialize
- * @exception ExoCacheInitException if an exception happens while initializing the cache
- */
- public ExoCache create(ExoCacheConfig config, Cache<Serializable, Object> cache) throws ExoCacheInitException;
-
- /**
- * Returns the type of {@link org.exoplatform.services.cache.ExoCacheConfig} expected by the creator
- * @return the expected type
- */
- public Class<? extends ExoCacheConfig> getExpectedConfigType();
-
- /**
- * Returns the name of the implementation expected by the creator. This is mainly used to be backward compatible
- * @return the expected by the creator
- */
- public String getExpectedImplementation();
-}</programlisting></para>
-
- <para>The <envar>ExoCacheCreator</envar> allows you to define any kind
- of jboss cache instance that you would like to have. It has been
- designed to give you the ability to have your own type of
- configuration and to always be backward compatible.</para>
-
- <para>In an <envar>ExoCacheCreator</envar>, you need to implement 3
- methods which are:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>create</emphasis> - this method is used to create
- a new <envar>ExoCache</envar> from the
- <envar>ExoCacheConfig</envar> and a jboss cache instance.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>getExpectedConfigType</emphasis> - this method is
- used to indicate the factory the subtype of
- <envar>ExoCacheConfig</envar> supported by the creator.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>getExpectedImplementation</emphasis> - this method
- is used to indicate the factory the value of field implementation
- of <envar>ExoCacheConfig</envar> that is supported by the creator.
- This is used for backward compatibility, in other words you can
- still configure your cache with a super class
- <envar>ExoCacheConfig</envar>.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Register a cache creator</title>
-
- <para>You can register any cache creator you want thanks to an
- <emphasis>"external plugin"</emphasis>, see an example
- below:<programlisting> <external-component-plugins>
- <target-component>org.exoplatform.services.cache.ExoCacheFactory</target-component>
- <component-plugin>
- <name>addCreator</name>
- <set-method>addCreator</set-method>
- <type>org.exoplatform.services.cache.impl.jboss.ExoCacheCreatorPlugin</type>
- <description>add Exo Cache Creator</description>
- <init-params>
- <object-param>
- <name>LRU</name>
- <description>The lru cache creator</description>
- <object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator">
- <field name="defaultTimeToLive"><long>1500</long></field>
- <field name="defaultMaxAge"><long>2000</long></field>
- </object>
- </object-param>
- </init-params>
- </component-plugin>
- </external-component-plugins></programlisting></para>
-
- <para>In the example above, I call the method
- <emphasis>addCreator(ExoCacheCreatorPlugin plugin)</emphasis> on the
- current implementation of <envar>ExoCacheFactory</envar> which is
- actually the jboss cache implementation.</para>
-
- <para>In the <emphasis>init-params</emphasis> block, you can define a
- set of <emphasis>object-param</emphasis> blocks and for each
- <emphasis>object-param</emphasis>, we expect any object definition of
- type <envar>ExoCacheCreator</envar>.</para>
-
- <para>In this example, we register the action creator related to the
- eviction policy <emphasis>LRU</emphasis>.</para>
- </section>
-
- <section>
- <title>The cache creators available</title>
-
- <para>By default, no cache creator are defined, so you need to define
- them yourself by adding them in your configuration files.</para>
-
- <section>
- <title>LRU Cache Creator - Least Recently Used</title>
-
- <programlisting>..
-<object-param>
- <name>LRU</name>
- <description>The lru cache creator</description>
- <object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator">
- <field name="defaultTimeToLive"><long>${my-value}</long></field>
- <field name="defaultMaxAge"><long>${my-value}</long></field>
- </object>
-</object-param>
-...</programlisting>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>defaultTimeToLive</entry>
-
- <entry>This is the default value of the field
- <emphasis>timeToLive</emphasis> described in the section
- dedicated to this cache type. This value is only use when we
- define a cache of this type with the old
- configuration.</entry>
- </row>
-
- <row>
- <entry>defaultMaxAge</entry>
-
- <entry>his is the default value of the field
- <emphasis>maxAge</emphasis> described in the section
- dedicated to this cache type. This value is only use when we
- define a cache of this type with the old
- configuration.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>FIFO Cache Creator - First In, First Out</title>
-
- <programlisting>...
-<object-param>
- <name>FIFO</name>
- <description>The fifo cache creator</description>
- <object type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheCreator"></object>
-</object-param>
-...</programlisting>
- </section>
-
- <section>
- <title>MRU Cache Creator - Most Recently Used</title>
-
- <programlisting>...
-<object-param>
- <name>MRU</name>
- <description>The mru cache creator</description>
- <object type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheCreator"></object>
-</object-param>
-...</programlisting>
- </section>
-
- <section>
- <title>LFU Cache Creator - Least Frequently Used</title>
-
- <programlisting>...
-<object-param>
- <name>LFU</name>
- <description>The lfu cache creator</description>
- <object type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheCreator">
- <field name="defaultMinNodes"><int>${my-value}</int></field>
- </object>
-</object-param>
-...</programlisting>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>defaultMinNodes</entry>
-
- <entry>This is the default value of the field
- <emphasis>minNodes</emphasis> described in the section
- dedicated to this cache type. This value is only use when we
- define a cache of this type with the old
- configuration.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>EA Cache Creator - Expiration Algorithm</title>
-
- <programlisting>...
-<object-param>
- <name>EA</name>
- <description>The ea cache creator</description>
- <object type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheCreator">
- <field name="defaultExpirationTimeout"><long>2000</long></field>
- </object>
-</object-param>
-...</programlisting>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>defaultExpirationTimeout</entry>
-
- <entry>This is the default value of the field
- <emphasis>minNodes</emphasis> described in the section
- dedicated to this cache type. This value is only use when we
- define a cache of this type with the old
- configuration.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
- </section>
-
- <section>
- <title>Define a cache</title>
-
- <section>
- <title>How to define a cache?</title>
-
- <para>You have 2 ways to define a cache which are:</para>
-
- <itemizedlist>
- <listitem>
- <para>At <envar>CacheService</envar> initialization</para>
- </listitem>
-
- <listitem>
- <para>With an <emphasis>"external plugin"</emphasis></para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>At <envar>CacheService</envar> initialization</title>
-
- <programlisting>...
- <component>
- <key>org.exoplatform.services.cache.CacheService</key>
- <type>org.exoplatform.services.cache.impl.CacheServiceImpl</type>
- <init-params>
- ...
- <object-param>
- <name>fifocache</name>
- <description>The default cache configuration</description>
- <object type="org.exoplatform.services.cache.ExoCacheConfig">
- <field name="name"><string>fifocache</string></field>
- <field name="maxSize"><int>${my-value}</int></field>
- <field name="liveTime"><long>${my-value}</long></field>
- <field name="distributed"><boolean>false</boolean></field>
- <field name="implementation"><string>org.exoplatform.services.cache.FIFOExoCache</string></field>
- </object>
- </object-param>
- ...
- </init-params>
- </component>
-...</programlisting>
-
- <para>In this example, we define a new cache called
- <emphasis>fifocache</emphasis>.</para>
- </section>
-
- <section>
- <title>With an <emphasis>"external plugin"</emphasis></title>
-
- <programlisting>...
- <external-component-plugins>
- <target-component>org.exoplatform.services.cache.CacheService</target-component>
- <component-plugin>
- <name>addExoCacheConfig</name>
- <set-method>addExoCacheConfig</set-method>
- <type>org.exoplatform.services.cache.ExoCacheConfigPlugin</type>
- <description>add ExoCache configuration component plugin </description>
- <init-params>
- ...
- <object-param>
- <name>fifoCache</name>
- <description>The fifo cache configuration</description>
- <object type="org.exoplatform.services.cache.ExoCacheConfig">
- <field name="name"><string>fifocache</string></field>
- <field name="maxSize"><int>${my-value}</int></field>
- <field name="liveTime"><long>${my-value}</long></field>
- <field name="distributed"><boolean>false</boolean></field>
- <field name="implementation"><string>org.exoplatform.services.cache.FIFOExoCache</string></field>
- </object>
- </object-param>
-...
- </init-params>
- </component-plugin>
- </external-component-plugins>
-...</programlisting>
-
- <para>In this example, we define a new cache called
- <emphasis>fifocache</emphasis> which is in fact the same cache as in
- previous example but defined in a different manner.</para>
- </section>
- </section>
-
- <section>
- <title>How to define a distributed or a local cache?</title>
-
- <para>Actually, if you use a custom configuration for your cache as
- described in a previous section, we will use the cache mode define in
- your configuration file.</para>
-
- <para>In case, you decide to use the default configuration template,
- we use the field <emphasis>distributed</emphasis> of your
- <envar>ExoCacheConfig</envar> to decide. In other words, if the value
- of this field is false (the default value), the cache will be a local
- cache otherwise it will be the cache mode defined in your default
- configuration template that should be distributed.</para>
- </section>
-
- <section>
- <title>LRU Cache - Least Recently Used</title>
-
- <itemizedlist>
- <listitem>
- <para>New configuration</para>
-
- <para><programlisting>...
- <object-param>
- <name>lru</name>
- <description>The lru cache configuration</description>
- <object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheConfig">
- <field name="name"><string>lru</string></field>
- <field name="maxNodes"><int>${my-value}</int></field>
- <field name="minTimeToLive"><long>${my-value}</long></field>
- <field name="maxAge"><long>${my-value}</long></field>
- <field name="timeToLive"><long>${my-value}</long></field>
- </object>
- </object-param>
-...</programlisting><table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxNodes</entry>
-
- <entry>This is the maximum number of nodes allowed in
- this region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>minTimeToLive</entry>
-
- <entry>The minimum amount of time (in milliseconds) a
- node must be allowed to live after being accessed before
- it is allowed to be considered for eviction. 0 denotes
- that this feature is disabled, which is the default
- value.</entry>
- </row>
-
- <row>
- <entry>maxAge</entry>
-
- <entry>Lifespan of a node (in milliseconds) regardless
- of idle time before the node is swept away. 0 denotes
- immediate expiry, -1 denotes no limit.</entry>
- </row>
-
- <row>
- <entry>timeToLive</entry>
-
- <entry>The amount of time a node is not written to or
- read (in milliseconds) before the node is swept away. 0
- denotes immediate expiry, -1 denotes no limit.</entry>
- </row>
- </tbody>
- </tgroup>
- </table></para>
- </listitem>
-
- <listitem>
- <para>Old configuration</para>
-
- <programlisting>...
- <object-param>
- <name>lru-with-old-config</name>
- <description>The lru cache configuration</description>
- <object type="org.exoplatform.services.cache.ExoCacheConfig">
- <field name="name"><string>lru-with-old-config</string></field>
- <field name="maxSize"><int>${my-value}</int></field>
- <field name="liveTime"><long>${my-value}</long></field>
- <field name="implementation"><string>LRU</string></field>
- </object>
- </object-param>
-...</programlisting>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxSize</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The minimum amount of time (in seconds) a node must
- be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para><note>
- <para>For the fields <emphasis>maxAge</emphasis> and
- <emphasis>timeToLive</emphasis> needed by JBoss cache, we will
- use the default values provided by the creator.</para>
- </note></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>FIFO Cache - First In, First Out</title>
-
- <itemizedlist>
- <listitem>
- <para>New configuration<programlisting>...
- <object-param>
- <name>fifo</name>
- <description>The fifo cache configuration</description>
- <object type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheConfig">
- <field name="name"><string>fifo</string></field>
- <field name="maxNodes"><int>${my-value}</int></field>
- <field name="minTimeToLive"><long>${my-value}</long></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxNodes</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>minTimeToLive</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
-
- <listitem>
- <para>Old configuration<programlisting>...
- <object-param>
- <name>fifo-with-old-config</name>
- <description>The fifo cache configuration</description>
- <object type="org.exoplatform.services.cache.ExoCacheConfig">
- <field name="name"><string>fifo-with-old-config</string></field>
- <field name="maxSize"><int>${my-value}</int></field>
- <field name="liveTime"><long>${my-value}</long></field>
- <field name="implementation"><string>FIFO</string></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxSize</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The minimum amount of time (in seconds) a node must
- be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>MRU Cache - Most Recently Used</title>
-
- <itemizedlist>
- <listitem>
- <para>New configuration<programlisting>...
- <object-param>
- <name>mru</name>
- <description>The mru cache configuration</description>
- <object type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheConfig">
- <field name="name"><string>mru</string></field>
- <field name="maxNodes"><int>${my-value}</int></field>
- <field name="minTimeToLive"><long>${my-value}</long></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxNodes</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>minTimeToLive</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
-
- <listitem>
- <para>Old configuration<programlisting>...
- <object-param>
- <name>mru-with-old-config</name>
- <description>The mru cache configuration</description>
- <object type="org.exoplatform.services.cache.ExoCacheConfig">
- <field name="name"><string>mru-with-old-config</string></field>
- <field name="maxSize"><int>${my-value}</int></field>
- <field name="liveTime"><long>${my-value}</long></field>
- <field name="implementation"><string>MRU</string></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxSize</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The minimum amount of time (in seconds) a node must
- be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>LFU Cache - Least Frequently Used</title>
-
- <itemizedlist>
- <listitem>
- <para>New configuration<programlisting>...
- <object-param>
- <name>lfu</name>
- <description>The lfu cache configuration</description>
- <object type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheConfig">
- <field name="name"><string>lfu</string></field>
- <field name="maxNodes"><int>${my-value}</int></field>
- <field name="minNodes"><int>${my-value}</int></field>
- <field name="minTimeToLive"><long>${my-value}</long></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxNodes</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>minNodes</entry>
-
- <entry>This is the minimum number of nodes allowed in this
- region. This value determines what the eviction queue
- should prune down to per pass. e.g. If minNodes is 10 and
- the cache grows to 100 nodes, the cache is pruned down to
- the 10 most frequently used nodes when the eviction timer
- makes a pass through the eviction algorithm.</entry>
- </row>
-
- <row>
- <entry>minTimeToLive</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
-
- <listitem>
- <para>Old configuration<programlisting>...
- <object-param>
- <name>lfu-with-old-config</name>
- <description>The lfu cache configuration</description>
- <object type="org.exoplatform.services.cache.ExoCacheConfig">
- <field name="name"><string>lfu-with-old-config</string></field>
- <field name="maxSize"><int>${my-value}</int></field>
- <field name="liveTime"><long>${my-value}</long></field>
- <field name="implementation"><string>LFU</string></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxSize</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para><note>
- <para>For the fields <emphasis>minNodes</emphasis> and
- <emphasis>timeToLive</emphasis> needed by JBoss cache, we will
- use the default values provided by the creator.</para>
- </note></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>EA Cache - Expiration Algorithm</title>
-
- <itemizedlist>
- <listitem>
- <para>New configuration<programlisting>...
- <object-param>
- <name>ea</name>
- <description>The ea cache configuration</description>
- <object type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheConfig">
- <field name="name"><string>ea</string></field>
- <field name="maxNodes"><int>${my-value}</int></field>
- <field name="minTimeToLive"><long>${my-value}</long></field>
- <field name="expirationTimeout"><long>${my-value}</long></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxNodes</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>minTimeToLive</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
-
- <row>
- <entry>expirationTimeout</entry>
-
- <entry>This is the timeout after which the cache entry
- must be evicted.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
-
- <listitem>
- <para>Old configuration<programlisting>...
- <object-param>
- <name>ea-with-old-config</name>
- <description>The ea cache configuration</description>
- <object type="org.exoplatform.services.cache.ExoCacheConfig">
- <field name="name"><string>lfu-with-old-config</string></field>
- <field name="maxSize"><int>${my-value}</int></field>
- <field name="liveTime"><long>${my-value}</long></field>
- <field name="implementation"><string>EA</string></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxSize</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para><note>
- <para>For the fields <emphasis>expirationTimeout</emphasis>
- needed by JBoss cache, we will use the default values provided
- by the creator.</para>
- </note></para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter>
+ <?dbhtml filename="ch-cache.html"?>
+ <title>eXo Cache</title>
+
+ <section>
+ <title>Basic concepts</title>
+
+ <para>All applications on the top of eXo JCR that need a cache, can rely
+ on an <envar>org.exoplatform.services.cache.ExoCache</envar> instance that
+ is managed by the
+ <envar>org.exoplatform.services.cache.CacheService</envar>. The main
+ implementation of this service is
+ <envar>org.exoplatform.services.cache.impl.CacheServiceImpl</envar> which
+ depends on the
+ <envar>org.exoplatform.services.cache.ExoCacheConfig</envar> in order to
+ create new <envar>ExoCache</envar> instances. See below an example of
+ <envar>org.exoplatform.services.cache.CacheService</envar>
+ definition:<programlisting> <component>
+ <key>org.exoplatform.services.cache.CacheService</key>
+ <jmx-name>cache:type=CacheService</jmx-name>
+ <type>org.exoplatform.services.cache.impl.CacheServiceImpl</type>
+ <init-params>
+ <object-param>
+ <name>cache.config.default</name>
+ <description>The default cache configuration</description>
+ <object type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field name="name"><string>default</string></field>
+ <field name="maxSize"><int>300</int></field>
+ <field name="liveTime"><long>600</long></field>
+ <field name="distributed"><boolean>false</boolean></field>
+ <field name="implementation"><string>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</string></field>
+ </object>
+ </object-param>
+ </init-params>
+ </component></programlisting></para>
+
+ <para><note>
+ <para>The <envar>ExoCacheConfig</envar> which name is
+ <envar>default</envar>, will be the default configuration of all the
+ <envar>ExoCache</envar> instances that don't have dedicated
+ configuration.</para>
+ </note>See below an example of how to define a new
+ <envar>ExoCacheConfig</envar> thanks to a
+ <emphasis>external-component-plugin</emphasis>:<programlisting> <external-component-plugins>
+ <target-component>org.exoplatform.services.cache.CacheService</target-component>
+ <component-plugin>
+ <name>addExoCacheConfig</name>
+ <set-method>addExoCacheConfig</set-method>
+ <type>org.exoplatform.services.cache.ExoCacheConfigPlugin</type>
+ <description>Configures the cache for query service</description>
+ <init-params>
+ <object-param>
+ <name>cache.config.wcm.composer</name>
+ <description>The default cache configuration</description>
+ <object type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field name="name"><string>wcm.composer</string></field>
+ <field name="maxSize"><int>300</int></field>
+ <field name="liveTime"><long>600</long></field>
+ <field name="distributed"><boolean>false</boolean></field>
+ <field name="implementation"><string>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</string></field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+ </external-component-plugins></programlisting></para>
+
+ <table>
+ <title>Descriptions of the fields of
+ <envar>ExoCacheConfig</envar></title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>name</entry>
+
+ <entry>The name of the cache. This field is mandatory since it
+ will be used to retrieve the <envar>ExoCacheConfig</envar>
+ corresponding to a given cache name.</entry>
+ </row>
+
+ <row>
+ <entry>label</entry>
+
+ <entry>The label of the cache. This field is optional. It is
+ mainly used to indicate the purpose of the cache.</entry>
+ </row>
+
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>The maximum numbers of elements in cache. This field is
+ mandatory.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The amount of time (in seconds) an element is not written
+ or read before it is evicted. This field is mandatory.</entry>
+ </row>
+
+ <row>
+ <entry>implementation</entry>
+
+ <entry>The full qualified name of the cache implementation to use.
+ This field is optional. This field is only used for simple cache
+ implementation. The default and main implementation is
+ <envar>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</envar>,
+ this implementation only works with local caches with FIFO as
+ eviction policy. For more complex implementation see the next
+ sections.</entry>
+ </row>
+
+ <row>
+ <entry>distributed</entry>
+
+ <entry>Indicates if the cache is distributed. This field is
+ optional. This field is used for backward compatibility.</entry>
+ </row>
+
+ <row>
+ <entry>replicated</entry>
+
+ <entry>Indicates if the cache is replicated. This field is
+ optional. This field is deprecated.</entry>
+ </row>
+
+ <row>
+ <entry>logEnabled</entry>
+
+ <entry>Indicates if the log is enabled. This field is optional.
+ This field is used for backward compatibility.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para></para>
+ </section>
+
+ <section>
+ <title>eXo Cache extension</title>
+
+ <para>In the previous versions of eXo kernel, it was quite complex to
+ implement your own ExoCache because it was not open enough. Since kernel
+ 2.0.8, it is possible to easily integrate your favorite cache provider in
+ eXo Products.</para>
+
+ <para>You just need to implement your own <envar>ExoCacheFactory</envar>
+ and register it in an eXo container, as described below:<programlisting>package org.exoplatform.services.cache;
+...
+public interface ExoCacheFactory {
+
+ /**
+ * Creates a new instance of {@link org.exoplatform.services.cache.ExoCache}
+ * @param config the cache to create
+ * @return the new instance of {@link org.exoplatform.services.cache.ExoCache}
+ * @exception ExoCacheInitException if an exception happens while initializing the cache
+ */
+ public ExoCache createCache(ExoCacheConfig config) throws ExoCacheInitException;
+}</programlisting></para>
+
+ <para>As you can see, there is only one method to implement which cans be
+ seen as a converter of an <envar>ExoCacheConfig</envar> to get an instance
+ of <envar>ExoCache</envar>. Once, you created your own implementation you
+ can simply register your factory by adding a file
+ <emphasis>conf/portal/configuration.xml</emphasis> with a content of the
+ following type:<programlisting><configuration>
+ <component>
+ <key>org.exoplatform.services.cache.ExoCacheFactory</key>
+ <type>org.exoplatform.tutorial.MyExoCacheFactoryImpl</type>
+ ...
+ </component>
+</configuration></programlisting></para>
+ </section>
+
+ <section>
+ <title>eXo Cache based on JBoss Cache</title>
+
+ <section>
+ <title>Configure the ExoCacheFactory</title>
+
+ <para>When you add, the eXo library in your classpath, the eXo service
+ container will use the default configuration provided in the library
+ itself but of course you can still redefined the configuration if you
+ wish as you can do with any components.</para>
+
+ <para>The default configuration of the factory is:<programlisting><configuration>
+ <component>
+ <key>org.exoplatform.services.cache.ExoCacheFactory</key>
+ <type>org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryImpl</type>
+ <init-params>
+ <value-param>
+ <name>cache.config.template</name>
+ <value>jar:/conf/portal/cache-configuration-template.xml</value>
+ </value-param>
+ </init-params>
+ </component>
+</configuration></programlisting></para>
+
+ <para>As you can see the factory requires one single parameter which is
+ <emphasis>cache.config.template</emphasis>, this parameter allows you to
+ define the location of the default configuration template of your jboss
+ cache. In the default configuration, we ask the eXo container to get the
+ file shipped into the jar at
+ <emphasis>/conf/portal/cache-configuration-template.xml</emphasis>.</para>
+
+ <para>The default configuration template aims to be the skeleton from
+ which we will create any type of jboss cache instance, thus it must be
+ very generic.<note>
+ <para>The default configuration template provided with the jar aims
+ to work with any application servers, but if you intend to use JBoss
+ AS, you should redefine it in your custom configuration to fit
+ better with your AS.</para>
+ </note></para>
+ </section>
+
+ <section>
+ <title>Add specific configuration for a cache</title>
+
+ <para>If for a given reason, you need to use a specific configuration
+ for a cache, you can register one thanks to an "<emphasis>external
+ plugin</emphasis>", see an example below:<programlisting><configuration>
+ ...
+ <external-component-plugins>
+ <target-component>org.exoplatform.services.cache.ExoCacheFactory</target-component>
+ <component-plugin>
+ <name>addConfig</name>
+ <set-method>addConfig</set-method>
+ <type>org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryConfigPlugin</type>
+ <description>add Custom Configurations</description>
+ <init-params>
+ <value-param>
+ <name>myCustomCache</name>
+ <value>jar:/conf/portal/custom-cache-configuration.xml</value>
+ </value-param>
+ </init-params>
+ </component-plugin>
+ </external-component-plugins>
+ ...
+</configuration></programlisting></para>
+
+ <para>In the example above, I call the method
+ <emphasis>addConfig(ExoCacheFactoryConfigPlugin plugin)</emphasis> on
+ the current implementation of <envar>ExoCacheFactory</envar> which is
+ actually the jboss cache implementation.</para>
+
+ <para>In the <emphasis>init-params</emphasis> block, you can define a
+ set of <emphasis>value-param</emphasis> blocks and for each
+ <emphasis>value-param</emphasis>, we expect the name of cache that needs
+ a specific configuration as name and the location of your custom
+ configuration as <emphasis>value</emphasis>.</para>
+
+ <para>In this example, we indicates to the factory that we would like
+ that the cache <emphasis>myCustomCache</emphasis> use the configuration
+ available at
+ <emphasis>jar:/conf/portal/custom-cache-configuration.xml</emphasis>.</para>
+ </section>
+
+ <section>
+ <title>Add a cache creator</title>
+
+ <section>
+ <title>Understanding a cache creator</title>
+
+ <para>The factory for jboss cache, delegates the cache creation to
+ <envar>ExoCacheCreator</envar> that is defines as
+ below:<programlisting>package org.exoplatform.services.cache.impl.jboss;
+...
+public interface ExoCacheCreator {
+
+ /**
+ * Creates an eXo cache according to the given configuration {@link org.exoplatform.services.cache.ExoCacheConfig}
+ * @param config the configuration of the cache to apply
+ * @param cache the cache to initialize
+ * @exception ExoCacheInitException if an exception happens while initializing the cache
+ */
+ public ExoCache create(ExoCacheConfig config, Cache<Serializable, Object> cache) throws ExoCacheInitException;
+
+ /**
+ * Returns the type of {@link org.exoplatform.services.cache.ExoCacheConfig} expected by the creator
+ * @return the expected type
+ */
+ public Class<? extends ExoCacheConfig> getExpectedConfigType();
+
+ /**
+ * Returns the name of the implementation expected by the creator. This is mainly used to be backward compatible
+ * @return the expected by the creator
+ */
+ public String getExpectedImplementation();
+}</programlisting></para>
+
+ <para>The <envar>ExoCacheCreator</envar> allows you to define any kind
+ of jboss cache instance that you would like to have. It has been
+ designed to give you the ability to have your own type of
+ configuration and to always be backward compatible.</para>
+
+ <para>In an <envar>ExoCacheCreator</envar>, you need to implement 3
+ methods which are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>create</emphasis> - this method is used to create
+ a new <envar>ExoCache</envar> from the
+ <envar>ExoCacheConfig</envar> and a jboss cache instance.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>getExpectedConfigType</emphasis> - this method is
+ used to indicate the factory the subtype of
+ <envar>ExoCacheConfig</envar> supported by the creator.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>getExpectedImplementation</emphasis> - this method
+ is used to indicate the factory the value of field implementation
+ of <envar>ExoCacheConfig</envar> that is supported by the creator.
+ This is used for backward compatibility, in other words you can
+ still configure your cache with a super class
+ <envar>ExoCacheConfig</envar>.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Register a cache creator</title>
+
+ <para>You can register any cache creator you want thanks to an
+ <emphasis>"external plugin"</emphasis>, see an example
+ below:<programlisting> <external-component-plugins>
+ <target-component>org.exoplatform.services.cache.ExoCacheFactory</target-component>
+ <component-plugin>
+ <name>addCreator</name>
+ <set-method>addCreator</set-method>
+ <type>org.exoplatform.services.cache.impl.jboss.ExoCacheCreatorPlugin</type>
+ <description>add Exo Cache Creator</description>
+ <init-params>
+ <object-param>
+ <name>LRU</name>
+ <description>The lru cache creator</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator">
+ <field name="defaultTimeToLive"><long>1500</long></field>
+ <field name="defaultMaxAge"><long>2000</long></field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+ </external-component-plugins></programlisting></para>
+
+ <para>In the example above, I call the method
+ <emphasis>addCreator(ExoCacheCreatorPlugin plugin)</emphasis> on the
+ current implementation of <envar>ExoCacheFactory</envar> which is
+ actually the jboss cache implementation.</para>
+
+ <para>In the <emphasis>init-params</emphasis> block, you can define a
+ set of <emphasis>object-param</emphasis> blocks and for each
+ <emphasis>object-param</emphasis>, we expect any object definition of
+ type <envar>ExoCacheCreator</envar>.</para>
+
+ <para>In this example, we register the action creator related to the
+ eviction policy <emphasis>LRU</emphasis>.</para>
+ </section>
+
+ <section>
+ <title>The cache creators available</title>
+
+ <para>By default, no cache creator are defined, so you need to define
+ them yourself by adding them in your configuration files.</para>
+
+ <section>
+ <title>LRU Cache Creator - Least Recently Used</title>
+
+ <programlisting>..
+<object-param>
+ <name>LRU</name>
+ <description>The lru cache creator</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator">
+ <field name="defaultTimeToLive"><long>${my-value}</long></field>
+ <field name="defaultMaxAge"><long>${my-value}</long></field>
+ </object>
+</object-param>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>defaultTimeToLive</entry>
+
+ <entry>This is the default value of the field
+ <emphasis>timeToLive</emphasis> described in the section
+ dedicated to this cache type. This value is only use when we
+ define a cache of this type with the old
+ configuration.</entry>
+ </row>
+
+ <row>
+ <entry>defaultMaxAge</entry>
+
+ <entry>his is the default value of the field
+ <emphasis>maxAge</emphasis> described in the section
+ dedicated to this cache type. This value is only use when we
+ define a cache of this type with the old
+ configuration.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>FIFO Cache Creator - First In, First Out</title>
+
+ <programlisting>...
+<object-param>
+ <name>FIFO</name>
+ <description>The fifo cache creator</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheCreator"></object>
+</object-param>
+...</programlisting>
+ </section>
+
+ <section>
+ <title>MRU Cache Creator - Most Recently Used</title>
+
+ <programlisting>...
+<object-param>
+ <name>MRU</name>
+ <description>The mru cache creator</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheCreator"></object>
+</object-param>
+...</programlisting>
+ </section>
+
+ <section>
+ <title>LFU Cache Creator - Least Frequently Used</title>
+
+ <programlisting>...
+<object-param>
+ <name>LFU</name>
+ <description>The lfu cache creator</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheCreator">
+ <field name="defaultMinNodes"><int>${my-value}</int></field>
+ </object>
+</object-param>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>defaultMinNodes</entry>
+
+ <entry>This is the default value of the field
+ <emphasis>minNodes</emphasis> described in the section
+ dedicated to this cache type. This value is only use when we
+ define a cache of this type with the old
+ configuration.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>EA Cache Creator - Expiration Algorithm</title>
+
+ <programlisting>...
+<object-param>
+ <name>EA</name>
+ <description>The ea cache creator</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheCreator">
+ <field name="defaultExpirationTimeout"><long>2000</long></field>
+ </object>
+</object-param>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>defaultExpirationTimeout</entry>
+
+ <entry>This is the default value of the field
+ <emphasis>minNodes</emphasis> described in the section
+ dedicated to this cache type. This value is only use when we
+ define a cache of this type with the old
+ configuration.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Define a cache</title>
+
+ <section>
+ <title>How to define a cache?</title>
+
+ <para>You have 2 ways to define a cache which are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>At <envar>CacheService</envar> initialization</para>
+ </listitem>
+
+ <listitem>
+ <para>With an <emphasis>"external plugin"</emphasis></para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <title>At <envar>CacheService</envar> initialization</title>
+
+ <programlisting>...
+ <component>
+ <key>org.exoplatform.services.cache.CacheService</key>
+ <type>org.exoplatform.services.cache.impl.CacheServiceImpl</type>
+ <init-params>
+ ...
+ <object-param>
+ <name>fifocache</name>
+ <description>The default cache configuration</description>
+ <object type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field name="name"><string>fifocache</string></field>
+ <field name="maxSize"><int>${my-value}</int></field>
+ <field name="liveTime"><long>${my-value}</long></field>
+ <field name="distributed"><boolean>false</boolean></field>
+ <field name="implementation"><string>org.exoplatform.services.cache.FIFOExoCache</string></field>
+ </object>
+ </object-param>
+ ...
+ </init-params>
+ </component>
+...</programlisting>
+
+ <para>In this example, we define a new cache called
+ <emphasis>fifocache</emphasis>.</para>
+ </section>
+
+ <section>
+ <title>With an <emphasis>"external plugin"</emphasis></title>
+
+ <programlisting>...
+ <external-component-plugins>
+ <target-component>org.exoplatform.services.cache.CacheService</target-component>
+ <component-plugin>
+ <name>addExoCacheConfig</name>
+ <set-method>addExoCacheConfig</set-method>
+ <type>org.exoplatform.services.cache.ExoCacheConfigPlugin</type>
+ <description>add ExoCache configuration component plugin </description>
+ <init-params>
+ ...
+ <object-param>
+ <name>fifoCache</name>
+ <description>The fifo cache configuration</description>
+ <object type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field name="name"><string>fifocache</string></field>
+ <field name="maxSize"><int>${my-value}</int></field>
+ <field name="liveTime"><long>${my-value}</long></field>
+ <field name="distributed"><boolean>false</boolean></field>
+ <field name="implementation"><string>org.exoplatform.services.cache.FIFOExoCache</string></field>
+ </object>
+ </object-param>
+...
+ </init-params>
+ </component-plugin>
+ </external-component-plugins>
+...</programlisting>
+
+ <para>In this example, we define a new cache called
+ <emphasis>fifocache</emphasis> which is in fact the same cache as in
+ previous example but defined in a different manner.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>How to define a distributed or a local cache?</title>
+
+ <para>Actually, if you use a custom configuration for your cache as
+ described in a previous section, we will use the cache mode define in
+ your configuration file.</para>
+
+ <para>In case, you decide to use the default configuration template,
+ we use the field <emphasis>distributed</emphasis> of your
+ <envar>ExoCacheConfig</envar> to decide. In other words, if the value
+ of this field is false (the default value), the cache will be a local
+ cache otherwise it will be the cache mode defined in your default
+ configuration template that should be distributed.</para>
+ </section>
+
+ <section>
+ <title>LRU Cache - Least Recently Used</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration</para>
+
+ <para><programlisting>...
+ <object-param>
+ <name>lru</name>
+ <description>The lru cache configuration</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheConfig">
+ <field name="name"><string>lru</string></field>
+ <field name="maxNodes"><int>${my-value}</int></field>
+ <field name="minTimeToLive"><long>${my-value}</long></field>
+ <field name="maxAge"><long>${my-value}</long></field>
+ <field name="timeToLive"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting><table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxNodes</entry>
+
+ <entry>This is the maximum number of nodes allowed in
+ this region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>minTimeToLive</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a
+ node must be allowed to live after being accessed before
+ it is allowed to be considered for eviction. 0 denotes
+ that this feature is disabled, which is the default
+ value.</entry>
+ </row>
+
+ <row>
+ <entry>maxAge</entry>
+
+ <entry>Lifespan of a node (in milliseconds) regardless
+ of idle time before the node is swept away. 0 denotes
+ immediate expiry, -1 denotes no limit.</entry>
+ </row>
+
+ <row>
+ <entry>timeToLive</entry>
+
+ <entry>The amount of time a node is not written to or
+ read (in milliseconds) before the node is swept away. 0
+ denotes immediate expiry, -1 denotes no limit.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration</para>
+
+ <programlisting>...
+ <object-param>
+ <name>lru-with-old-config</name>
+ <description>The lru cache configuration</description>
+ <object type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field name="name"><string>lru-with-old-config</string></field>
+ <field name="maxSize"><int>${my-value}</int></field>
+ <field name="liveTime"><long>${my-value}</long></field>
+ <field name="implementation"><string>LRU</string></field>
+ </object>
+ </object-param>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The minimum amount of time (in seconds) a node must
+ be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><note>
+ <para>For the fields <emphasis>maxAge</emphasis> and
+ <emphasis>timeToLive</emphasis> needed by JBoss cache, we will
+ use the default values provided by the creator.</para>
+ </note></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>FIFO Cache - First In, First Out</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration<programlisting>...
+ <object-param>
+ <name>fifo</name>
+ <description>The fifo cache configuration</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheConfig">
+ <field name="name"><string>fifo</string></field>
+ <field name="maxNodes"><int>${my-value}</int></field>
+ <field name="minTimeToLive"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxNodes</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>minTimeToLive</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration<programlisting>...
+ <object-param>
+ <name>fifo-with-old-config</name>
+ <description>The fifo cache configuration</description>
+ <object type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field name="name"><string>fifo-with-old-config</string></field>
+ <field name="maxSize"><int>${my-value}</int></field>
+ <field name="liveTime"><long>${my-value}</long></field>
+ <field name="implementation"><string>FIFO</string></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The minimum amount of time (in seconds) a node must
+ be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>MRU Cache - Most Recently Used</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration<programlisting>...
+ <object-param>
+ <name>mru</name>
+ <description>The mru cache configuration</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheConfig">
+ <field name="name"><string>mru</string></field>
+ <field name="maxNodes"><int>${my-value}</int></field>
+ <field name="minTimeToLive"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxNodes</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>minTimeToLive</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration<programlisting>...
+ <object-param>
+ <name>mru-with-old-config</name>
+ <description>The mru cache configuration</description>
+ <object type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field name="name"><string>mru-with-old-config</string></field>
+ <field name="maxSize"><int>${my-value}</int></field>
+ <field name="liveTime"><long>${my-value}</long></field>
+ <field name="implementation"><string>MRU</string></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The minimum amount of time (in seconds) a node must
+ be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>LFU Cache - Least Frequently Used</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration<programlisting>...
+ <object-param>
+ <name>lfu</name>
+ <description>The lfu cache configuration</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheConfig">
+ <field name="name"><string>lfu</string></field>
+ <field name="maxNodes"><int>${my-value}</int></field>
+ <field name="minNodes"><int>${my-value}</int></field>
+ <field name="minTimeToLive"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxNodes</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>minNodes</entry>
+
+ <entry>This is the minimum number of nodes allowed in this
+ region. This value determines what the eviction queue
+ should prune down to per pass. e.g. If minNodes is 10 and
+ the cache grows to 100 nodes, the cache is pruned down to
+ the 10 most frequently used nodes when the eviction timer
+ makes a pass through the eviction algorithm.</entry>
+ </row>
+
+ <row>
+ <entry>minTimeToLive</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration<programlisting>...
+ <object-param>
+ <name>lfu-with-old-config</name>
+ <description>The lfu cache configuration</description>
+ <object type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field name="name"><string>lfu-with-old-config</string></field>
+ <field name="maxSize"><int>${my-value}</int></field>
+ <field name="liveTime"><long>${my-value}</long></field>
+ <field name="implementation"><string>LFU</string></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><note>
+ <para>For the fields <emphasis>minNodes</emphasis> and
+ <emphasis>timeToLive</emphasis> needed by JBoss cache, we will
+ use the default values provided by the creator.</para>
+ </note></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>EA Cache - Expiration Algorithm</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration<programlisting>...
+ <object-param>
+ <name>ea</name>
+ <description>The ea cache configuration</description>
+ <object type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheConfig">
+ <field name="name"><string>ea</string></field>
+ <field name="maxNodes"><int>${my-value}</int></field>
+ <field name="minTimeToLive"><long>${my-value}</long></field>
+ <field name="expirationTimeout"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxNodes</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>minTimeToLive</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+
+ <row>
+ <entry>expirationTimeout</entry>
+
+ <entry>This is the timeout after which the cache entry
+ must be evicted.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration<programlisting>...
+ <object-param>
+ <name>ea-with-old-config</name>
+ <description>The ea cache configuration</description>
+ <object type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field name="name"><string>lfu-with-old-config</string></field>
+ <field name="maxSize"><int>${my-value}</int></field>
+ <field name="liveTime"><long>${my-value}</long></field>
+ <field name="implementation"><string>EA</string></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><note>
+ <para>For the fields <emphasis>expirationTimeout</emphasis>
+ needed by JBoss cache, we will use the default values provided
+ by the creator.</para>
+ </note></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ </section>
+</chapter>
Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/configuration.xml
===================================================================
--- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/configuration.xml 2010-03-26 13:00:58 UTC (rev 2166)
+++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/configuration.xml 2010-03-26 13:04:08 UTC (rev 2167)
@@ -1,1329 +1,1330 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter>
- <title>Configuration</title>
-
- <section>
- <title>Kernel configuration namespace</title>
-
- <para>To be effective the namespace URI <link
- linkend="???">http://www.exoplaform.org/xml/ns/kernel_1_1.xsd</link> must
- be target namespace of the XML configuration file.</para>
-
- <programlisting><xsd:schema
- targetNamespace="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"
- xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"
- xmlns:xsd="http://www.w3.org/2001/XMLSchema"
- elementFormDefault="qualified"
- attributeFormDefault="unqualified"
- version="1.0">
-
- ...
-</xsd:schema></programlisting>
- </section>
-
- <section>
- <title>Understanding How configuration files are loaded</title>
-
- <para>eXo Portal uses PicoContainer, which implements the Inversion of
- Control (IoC) design pattern. All eXo containers inherit from a
- PicoContainer. There are mainly two eXo containers used, each of them can
- provide one or several services. Each container service is delivered in a
- JAR file. This JAR file may contain a default configuration. The use of
- default configurations is recommended and most services provide it.</para>
-
- <para>When a Pico Container searches for services and its configurations,
- each configurable service may be reconfigured to override default values
- or set additional parameters. If the service is configured in two or more
- places the configuration override mechanism will be used.</para>
-
- <section>
- <title>Configuration Retrieval</title>
-
- <para>The container performs the following steps making eXo Container
- configuration retrieval depending on the container type.</para>
-
- <section>
- <title>Configuration retrieval order for the
- <envar>PortalContainer</envar></title>
-
- <para>The container is initialized by looking into different
- locations. This container is used by portal applications.
- Configurations are overloaded in the following lookup sequence:</para>
-
- <orderedlist>
- <listitem>
- <para>Services default <envar>RootContainer</envar> configurations
- from JAR files <emphasis>/conf/configuration.xml</emphasis></para>
- </listitem>
-
- <listitem>
- <para>External <envar>RootContainer</envar> configuration, if will
- be found at
- <emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para>
- </listitem>
-
- <listitem>
- <para>Services default <envar>PortalContainer</envar>
- configurations from JAR files
- <emphasis>/conf/portal/configuration.xml</emphasis></para>
- </listitem>
-
- <listitem>
- <para>Web applications configurations from WAR files
- <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para>
- </listitem>
-
- <listitem>
- <para>External configuration for services of named portal, if will
- be found at
- <emphasis>$AS_HOME/exo-conf/portal/$PORTAL_NAME/configuration.xml</emphasis></para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Configuration retrieval for a
- <envar>StandaloneContainer</envar></title>
-
- <para>The container is initialized by looking into different
- locations. This container is used by non portal applications.
- Configurations are overloaded in the following lookup sequence:</para>
-
- <orderedlist>
- <listitem>
- <para>Services default <envar>RootContainer</envar> configurations
- from JAR files <emphasis>/conf/configuration.xml</emphasis></para>
- </listitem>
-
- <listitem>
- <para>External <envar>RootContainer</envar> configuration, if will
- be found at
- <emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para>
- </listitem>
-
- <listitem>
- <para>Services default <envar>StandaloneContainer</envar>
- configurations from JAR files
- <emphasis>/conf/portal/configuration.xml</emphasis></para>
- </listitem>
-
- <listitem>
- <para>Web applications configurations from WAR files
- <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para>
- </listitem>
-
- <listitem>
- <para>Then depending on the <envar>StandaloneContainer</envar>
- configuration URL initialization:</para>
-
- <itemizedlist>
- <listitem>
- <para>if configuration URL was initialized to be added to
- services defaults, as below:<programlisting>// add configuration to the default services configurations from JARs/WARs
-StandaloneContainer.addConfigurationURL(containerConf);</programlisting></para>
-
- <para>Configuration from added URL
- <emphasis>containerConf</emphasis> will override only services
- configured in the file</para>
- </listitem>
-
- <listitem>
- <para>if configuration URL not initialized at all, it will be
- found at <emphasis>$AS_HOME/exo-configuration.xml</emphasis>.
- If <emphasis>$AS_HOME/exo-configuration.xml</emphasis> doesn't
- exist the container will try find it at
- <emphasis>$AS_HOME/exo-conf/exo-configuration.xml</emphasis>
- location and if it's still not found and the
- <envar>StandaloneContainer</envar> instance obtained with the
- dedicated configuration <envar>ClassLoader</envar> the
- container will try to retrieve the resource
- <emphasis>conf/exo-configuration.xml</emphasis> within the
- given <envar>ClassLoader</envar>.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>General notes about the configuration retrieval</title>
-
- <note>
- <para><emphasis>$AS_HOME</emphasis> - application server home
- directory, or <emphasis>user.dir</emphasis> JVM system property
- value in case of Java Standalone application.</para>
- </note>
-
- <note>
- <para><emphasis>$PORTAL_NAME</emphasis> - portal web application
- name.</para>
- </note>
-
- <note>
- <para>External configuration location can be overridden with System
- property <emphasis>exo.conf.dir</emphasis>. If the property exists
- its value will be used as path to eXo configuration directory, i.e.
- to <emphasis>$AS_HOME/exo-conf</emphasis> alternative. E.g. put
- property in command line java
- <emphasis>-Dexo.conf.dir=/path/to/exo/conf</emphasis>. In this
- particular use case, you have no need to use any prefix to import
- other files. For instance, if your configuration file is
- <emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/configuration.xml</emphasis>
- and you want to import the configuration file
- <emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/mySubConfDir/myConfig.xml</emphasis>,
- you can do it by adding
- <emphasis><import>mySubConfDir/myConfig.xml</import></emphasis>
- to your configuration file.</para>
- </note>
-
- <note>
- <para>The name of the configuration folder that is by default
- <emphasis>"exo-conf"</emphasis>, can be changed thanks to the System
- property <emphasis>exo.conf.dir.name</emphasis>.</para>
- </note>
-
- <note>
- <para>Under JBoss application server <emphasis>exo-conf</emphasis>
- will be looked up in directory described by JBoss System property
- <emphasis>jboss.server.config.url</emphasis>. If the property is not
- found or empty <emphasis>$AS_HOME/exo-conf</emphasis> will be
- asked.</para>
- </note>
-
- <note>
- <para>The search looks for a configuration file in each JAR/WAR
- available from the classpath using the current thread context
- classloader. During the search these configurations are added to a
- set. If the service was configured previously and the current JAR
- contains a new configuration of that service the latest (from the
- current JAR/WAR) will replace the previous one. The last one will be
- applied to the service during the services start phase.</para>
- </note>
-
- <warning>
- <para>Take care to have no dependencies between configurations from
- JAR files (<emphasis>/conf/portal/configuration.xml</emphasis> and
- <emphasis>/conf/configuration.xml</emphasis>) since we have no way
- to know in advance the loading order of those configurations. In
- other words, if you want to overload some configuration located in
- the file <emphasis>/conf/portal/configuration.xml</emphasis> of a
- given JAR file, you must not do it from the file
- <emphasis>/conf/portal/configuration.xml</emphasis> of another JAR
- file but from another configuration file loaded after configurations
- from JAR files
- <emphasis>/conf/portal/configuration.xml.</emphasis></para>
- </warning>
-
- <para>After the processing of all configurations available in system
- the container will initialize it and start each service in order of
- the dependency injection (DI).</para>
-
- <para>The user/developer should be careful when configuring the same
- service in different configuration files. It's recommended to
- configure a service in its own JAR only. Or, in case of a portal
- configuration, strictly reconfigure the services in portal WAR files
- or in an external configuration.</para>
-
- <para>There are services that can be (or should be) configured more
- than one time. This depends on business logic of the service. A
- service may initialize the same resource (shared with other services)
- or may add a particular object to a set of objects (shared with other
- services too). In the first case it's critical who will be the last,
- i.e. whose configuration will be used. In the second case it's no
- matter who is the first and who is the last (if the parameter objects
- are independent).</para>
- </section>
-
- <section>
- <title>Configuration retrieval log</title>
-
- <para>In case of problems with service configuration it's important to
- know from which JAR/WAR it comes. For that purpose the JVM system
- property
- <emphasis>org.exoplatform.container.configuration.debug</emphasis> can
- be used.<programlisting>java -Dorg.exoplatform.container.configuration.debug ...</programlisting></para>
-
- <para>If the property is enabled the container configuration manager
- will report the configuration adding process to the standard output
- (System.out).<programlisting>......
- Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.container-trunk.jar!/conf/portal/configuration.xml
- Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.component.cache-trunk.jar!/conf/portal/configuration.xml
- Add configuration jndi:/localhost/portal/WEB-INF/conf/configuration.xml
- import jndi:/localhost/portal/WEB-INF/conf/common/common-configuration.xml
- import jndi:/localhost/portal/WEB-INF/conf/database/database-configuration.xml
- import jndi:/localhost/portal/WEB-INF/conf/ecm/jcr-component-plugins-configuration.xml
- import jndi:/localhost/portal/WEB-INF/conf/jcr/jcr-configuration.xml
- ......</programlisting></para>
- </section>
- </section>
-
- <section>
- <title>Advanced concepts for the
- <emphasis>PortalContainers</emphasis></title>
-
- <para>Since eXo JCR 1.12, we added a set of new features that have been
- designed to extend portal applications such as GateIn.</para>
-
- <section>
- <title>Add new configuration files from a WAR file</title>
-
- <para>A <envar>ServletContextListener</envar> called
- <envar>org.exoplatform.container.web.PortalContainerConfigOwner</envar>
- has been added in order to notify the application that a given web
- application provides some configuration to the portal container, and
- this configuration file is the file
- <emphasis>WEB-INF/conf/configuration.xml</emphasis> available in the
- web application itself.</para>
-
- <para>If your war file contains some configuration to add to the
- <envar>PortalContainer</envar> simply add the following lines in your
- <emphasis>web.xml</emphasis> file.</para>
-
- <programlisting><?xml version="1.0" encoding="ISO-8859-1" ?>
-<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
- "http://java.sun.com/dtd/web-app_2_3.dtd">
-<web-app>
-...
- <!-- ================================================================== -->
- <!-- LISTENER -->
- <!-- ================================================================== -->
- <listener>
- <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class>
- </listener>
-...
-</web-app></programlisting>
- </section>
-
- <section>
- <title>Create your <emphasis>PortalContainers</emphasis> from a WAR
- file</title>
-
- <para>A <envar>ServletContextListener</envar> called
- <envar>org.exoplatform.container.web.PortalContainerCreator</envar>
- has been added in order to create the current portal containers that
- have been registered. We assume that all the web applications have
- already been loaded before calling
- <envar>PortalContainerCreator.contextInitialized<replaceable><optional>.</optional></replaceable></envar></para>
-
- <para><note>
- <para>In GateIn, the <envar>PortalContainerCreator</envar> is
- already managed by the file
- <emphasis>starter.war/ear.</emphasis></para>
- </note></para>
- </section>
-
- <section>
- <title>Define a <emphasis>PortalContainer</emphasis> with its
- dependencies and its settings</title>
-
- <para>Now we can define precisely a portal container and its
- dependencies and settings thanks to the
- <envar>PortalContainerDefinition</envar> that currently contains the
- name of the portal container, the name of the rest context, the name
- of the realm he web application dependencies ordered by loading
- priority (i.e. the first dependency must be loaded at first and so
- on..) and the settings.</para>
-
- <para>To be able to define a <envar>PortalContainerDefinition</envar>,
- we need to ensure first of all that a
- <envar>PortalContainerConfig</envar> has been defined at the
- <envar>RootContainer</envar> level, see below an example:</para>
-
- <programlisting> <component>
- <!-- The full qualified name of the PortalContainerConfig -->
- <type>org.exoplatform.container.definition.PortalContainerConfig</type>
- <init-params>
- <!-- The name of the default portal container -->
- <value-param>
- <name>default.portal.container</name>
- <value>myPortal</value>
- </value-param>
- <!-- The name of the default rest ServletContext -->
- <value-param>
- <name>default.rest.context</name>
- <value>myRest</value>
- </value-param>
- <!-- The name of the default realm -->
- <value-param>
- <name>default.realm.name</name>
- <value>my-exo-domain</value>
- </value-param>
- <!-- The default portal container definition -->
- <!-- It cans be used to avoid duplicating configuration -->
- <object-param>
- <name>default.portal.definition</name>
- <object type="org.exoplatform.container.definition.PortalContainerDefinition">
- <!-- All the dependencies of the portal container ordered by loading priority -->
- <field name="dependencies">
- <collection type="java.util.ArrayList">
- <value>
- <string>foo</string>
- </value>
- <value>
- <string>foo2</string>
- </value>
- <value>
- <string>foo3</string>
- </value>
- </collection>
- </field>
- <!-- A map of settings tied to the default portal container -->
- <field name="settings">
- <map type="java.util.HashMap">
- <entry>
- <key>
- <string>foo5</string>
- </key>
- <value>
- <string>value</string>
- </value>
- </entry>
- <entry>
- <key>
- <string>string</string>
- </key>
- <value>
- <string>value0</string>
- </value>
- </entry>
- <entry>
- <key>
- <string>int</string>
- </key>
- <value>
- <int>100</int>
- </value>
- </entry>
- </map>
- </field>
- <!-- The path to the external properties file -->
- <field name="externalSettingsPath">
- <string>classpath:/org/exoplatform/container/definition/default-settings.properties</string>
- </field>
- </object>
- </object-param>
- </init-params>
- </component></programlisting>
-
- <table>
- <title>Descriptions of the fields of
- <envar>PortalContainerConfig</envar></title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>default.portal.container</entry>
-
- <entry>The name of the default portal container. This field is
- optional.</entry>
- </row>
-
- <row>
- <entry>default.rest.context</entry>
-
- <entry>The name of the default rest
- <envar>ServletContext</envar>. This field is optional.</entry>
- </row>
-
- <row>
- <entry>default.realm.name</entry>
-
- <entry>The name of the default realm. This field is
- optional.</entry>
- </row>
-
- <row>
- <entry>default.portal.definition</entry>
-
- <entry>The definition of the default portal container. This
- field is optional. The expected type is
- <envar>org.exoplatform.container.definition.PortalContainerDefinition</envar>
- that is described below. Allow the parameters defined in this
- default <envar>PortalContainerDefinition</envar> will be the
- default values.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>A new <envar>PortalContainerDefinition</envar> can be defined at
- the <envar>RootContainer</envar> level thanks to an external plugin,
- see below an example:<programlisting> <external-component-plugins>
- <!-- The full qualified name of the PortalContainerConfig -->
- <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
- <component-plugin>
- <!-- The name of the plugin -->
- <name>Add PortalContainer Definitions</name>
- <!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions -->
- <set-method>registerPlugin</set-method>
- <!-- The full qualified name of the PortalContainerDefinitionPlugin -->
- <type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type>
- <init-params>
- <object-param>
- <name>portal</name>
- <object type="org.exoplatform.container.definition.PortalContainerDefinition">
- <!-- The name of the portal container -->
- <field name="name">
- <string>myPortal</string>
- </field>
- <!-- The name of the context name of the rest web application -->
- <field name="restContextName">
- <string>myRest</string>
- </field>
- <!-- The name of the realm -->
- <field name="realmName">
- <string>my-domain</string>
- </field>
- <!-- All the dependencies of the portal container ordered by loading priority -->
- <field name="dependencies">
- <collection type="java.util.ArrayList">
- <value>
- <string>foo</string>
- </value>
- <value>
- <string>foo2</string>
- </value>
- <value>
- <string>foo3</string>
- </value>
- </collection>
- </field>
- <!-- A map of settings tied to the portal container -->
- <field name="settings">
- <map type="java.util.HashMap">
- <entry>
- <key>
- <string>foo</string>
- </key>
- <value>
- <string>value</string>
- </value>
- </entry>
- <entry>
- <key>
- <string>int</string>
- </key>
- <value>
- <int>10</int>
- </value>
- </entry>
- <entry>
- <key>
- <string>long</string>
- </key>
- <value>
- <long>10</long>
- </value>
- </entry>
- <entry>
- <key>
- <string>double</string>
- </key>
- <value>
- <double>10</double>
- </value>
- </entry>
- <entry>
- <key>
- <string>boolean</string>
- </key>
- <value>
- <boolean>true</boolean>
- </value>
- </entry>
- </map>
- </field>
- <!-- The path to the external properties file -->
- <field name="externalSettingsPath">
- <string>classpath:/org/exoplatform/container/definition/settings.properties</string>
- </field>
- </object>
- </object-param>
- </init-params>
- </component-plugin>
- </external-component-plugins></programlisting></para>
-
- <table>
- <title>Descriptions of the fields of
- <envar>PortalContainerDefinition</envar> when it is used to define a
- new portal container</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>name</entry>
-
- <entry>The name of the portal container. This field is
- mandatory .</entry>
- </row>
-
- <row>
- <entry>restContextName</entry>
-
- <entry>The name of the context name of the rest web
- application. This field is optional. The default value will
- the value define at the <envar>PortalContainerConfig</envar>
- level.</entry>
- </row>
-
- <row>
- <entry>realmName</entry>
-
- <entry>The name of the realm. This field is optional. The
- default value will the value define at the
- <envar>PortalContainerConfig</envar> level.</entry>
- </row>
-
- <row>
- <entry>dependencies</entry>
-
- <entry>All the dependencies of the portal container ordered by
- loading priority. This field is optional. The default value
- will the value define at the
- <envar>PortalContainerConfig</envar> level. The dependencies
- are in fact the list of the context names of the web
- applications from which the portal container depends. This
- field is optional. The dependency order is really crucial
- since it will be interpreted the same way by several
- components of the platform. All those components, will
- consider the 1st element in the list less important than the
- second element and so on. It is currently used
- to:<itemizedlist>
- <listitem>
- <para>Know the loading order of all the
- dependencies.</para>
- </listitem>
-
- <listitem>
- <para>If we have several
- <envar>PortalContainerConfigOwner</envar><itemizedlist>
- <listitem>
- <para>The <envar>ServletContext</envar> of all the
- <envar>PortalContainerConfigOwner</envar> will be
- unified, if we use the unified
- <envar>ServletContext</envar>
- (<emphasis>PortalContainer.getPortalContext()</emphasis>)
- to get a resource, it will try to get the resource
- in the <envar>ServletContext</envar> of the most
- important <envar>PortalContainerConfigOwner</envar>
- (i.e. last in the dependency list) and if it cans
- find it, it will try with the second most important
- <envar>PortalContainerConfigOwner</envar> and so
- on.</para>
- </listitem>
-
- <listitem>
- <para>The <envar>ClassLoader</envar> of all the
- <envar>PortalContainerConfigOwner</envar> will be
- unified, if we use the unified
- <envar>ClassLoader</envar>
- (<emphasis>PortalContainer.getPortalClassLoader()</emphasis>)
- to get a resource, it will try to get the resource
- in the <envar>ClassLoader</envar> of the most
- important <envar>PortalContainerConfigOwner</envar>
- (i.e. last in the dependency list) and if it cans
- find it, it will try with the second most important
- <envar>PortalContainerConfigOwner</envar> and so
- on.</para>
- </listitem>
- </itemizedlist></para>
- </listitem>
- </itemizedlist></entry>
- </row>
-
- <row>
- <entry>settings</entry>
-
- <entry>A <envar>java.util.Map</envar> of internal parameters
- that we would like to tie the portal container. Those
- parameters could have any type of value. This field is
- optional. If some internal settings are defined at the
- <envar>PortalContainerConfig</envar> level, the two maps of
- settings will be merged. If a setting with the same name is
- defined in both maps, it will keep the value defined at the
- <envar>PortalContainerDefinition</envar> level.</entry>
- </row>
-
- <row>
- <entry>externalSettingsPath</entry>
-
- <entry>The path of the external properties file to load as
- default settings to the portal container. This field is
- optional. If some external settings are defined at the
- <envar>PortalContainerConfig</envar> level, the two maps of
- settings will be merged. If a setting with the same name is
- defined in both maps, it will keep the value defined at the
- <envar>PortalContainerDefinition</envar> level. The external
- properties files can be either of type "properties" or of type
- "xml". The path will be interpreted as follows:<orderedlist>
- <listitem>
- <para>The path doesn't contain any prefix of type
- "classpath:", "jar:" or "file:", we assume that the file
- could be externalized so we apply the following
- rules:<orderedlist>
- <listitem>
- <para>A file exists at
- <emphasis>${exo-conf-dir}/portal/${portalContainerName}/${externalSettingsPath}</emphasis>,
- we will load this file.</para>
- </listitem>
-
- <listitem>
- <para>No file exists at the previous path, we then
- assume that the path cans be interpreted by the
- <envar>ConfigurationManager</envar>.</para>
- </listitem>
- </orderedlist></para>
- </listitem>
-
- <listitem>
- <para>The path contains a prefix, we then assume that
- the path cans be interpreted by the
- <envar>ConfigurationManager</envar>.</para>
- </listitem>
- </orderedlist></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table>
- <title>Descriptions of the fields of
- <envar>PortalContainerDefinition</envar> when it is used to define
- the default portal container</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>name</entry>
-
- <entry>The name of the portal container. This field is
- optional. The default portal name will be:<orderedlist>
- <listitem>
- <para>If this field is not empty, then the default value
- will be the value of this field.</para>
- </listitem>
-
- <listitem>
- <para>If this field is empty and the value of the
- parameter <emphasis>default.portal.container</emphasis>
- is not empty, then the default value will be the value
- of the parameter.</para>
- </listitem>
-
- <listitem>
- <para>If this field and the parameter
- <emphasis>default.portal.container</emphasis> are both
- empty, the default value will be
- <emphasis>"portal".</emphasis></para>
- </listitem>
- </orderedlist></entry>
- </row>
-
- <row>
- <entry>restContextName</entry>
-
- <entry>The name of the context name of the rest web
- application. This field is optional. The default value wil
- be:<orderedlist>
- <listitem>
- <para>If this field is not empty, then the default value
- will be the value of this field.</para>
- </listitem>
-
- <listitem>
- <para>f this field is empty and the value of the
- parameter <emphasis>default.rest.context</emphasis> is
- not empty, then the default value will be the value of
- the parameter.</para>
- </listitem>
-
- <listitem>
- <para>f this field and the parameter
- <emphasis>default.rest.context</emphasis> are both
- empty, the default value will be
- <emphasis>"rest".</emphasis></para>
- </listitem>
- </orderedlist></entry>
- </row>
-
- <row>
- <entry>realmName</entry>
-
- <entry>The name of the realm. This field is optional. The
- default value wil be:<orderedlist>
- <listitem>
- <para>If this field is not empty, then the default value
- will be the value of this field.</para>
- </listitem>
-
- <listitem>
- <para>f this field is empty and the value of the
- parameter <emphasis>default.realm.name</emphasis> is not
- empty, then the default value will be the value of the
- parameter.</para>
- </listitem>
-
- <listitem>
- <para>f this field and the parameter
- <emphasis>default.realm.name</emphasis> are both empty,
- the default value will be
- <emphasis>"exo-domain".</emphasis></para>
- </listitem>
- </orderedlist></entry>
- </row>
-
- <row>
- <entry>dependencies</entry>
-
- <entry>All the dependencies of the portal container ordered by
- loading priority. This field is optional. If this field has a
- non empty value, it will be the default list of
- dependencies.</entry>
- </row>
-
- <row>
- <entry>settings</entry>
-
- <entry>A <envar>java.util.Map</envar> of internal parameters
- that we would like to tie the default portal container. Those
- parameters could have any type of value. This field is
- optional.</entry>
- </row>
-
- <row>
- <entry>externalSettingsPath</entry>
-
- <entry>The path of the external properties file to load as
- default settings to the default portal container. This field
- is optional. The external properties files can be either of
- type "properties" or of type "xml". The path will be
- interpreted as follows:<orderedlist>
- <listitem>
- <para>The path doesn't contain any prefix of type
- "classpath:", "jar:" or "file:", we assume that the file
- could be externalized so we apply the following
- rules:<orderedlist>
- <listitem>
- <para>A file exists at
- <emphasis>${exo-conf-dir}/portal/${externalSettingsPath}</emphasis>,
- we will load this file.</para>
- </listitem>
-
- <listitem>
- <para>No file exists at the previous path, we then
- assume that the path cans be interpreted by the
- <envar>ConfigurationManager</envar>.</para>
- </listitem>
- </orderedlist></para>
- </listitem>
-
- <listitem>
- <para>The path contains a prefix, we then assume that
- the path cans be interpreted by the
- <envar>ConfigurationManager</envar>.</para>
- </listitem>
- </orderedlist></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Internal and external settings are both optional, but if we give
- a non empty value for both the application will merge the settings. If
- the same setting name exists in both settings, we apply the following
- rules:</para>
-
- <orderedlist>
- <listitem>
- <para>The value of the external setting is
- <emphasis>null</emphasis>, we ignore the value.</para>
- </listitem>
-
- <listitem>
- <para>The value of the external setting is not
- <emphasis>null</emphasis> and the value of the internal setting is
- <emphasis>null</emphasis>, the final value will be the external
- setting value that is of type <envar>String</envar>.</para>
- </listitem>
-
- <listitem>
- <para>Both values are not <envar>null</envar>, we will have to
- convert the external setting value into the target type which is
- the type of the internal setting value, thanks to the static
- method <emphasis>valueOf(String)</emphasis>, the following
- sub-rules are then applied:</para>
-
- <orderedlist>
- <listitem>
- <para>The method cannot be found, the final value will be the
- external setting value that is of type
- <envar>String</envar>.</para>
- </listitem>
-
- <listitem>
- <para>The method can be found and the external setting value
- is an empty <envar>String</envar>, we ignore the external
- setting value.</para>
- </listitem>
-
- <listitem>
- <para>The method can be found and the external setting value
- is not an empty <envar>String</envar> but the method call
- fails, we ignore the external setting value.</para>
- </listitem>
-
- <listitem>
- <para>The method can be found and the external setting value
- is not an empty <envar>String</envar> and the method call
- succeeds, the final value will be the external setting value
- that is of type of the internal setting value.</para>
- </listitem>
- </orderedlist>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title><envar>PortalContainer</envar> settings</title>
-
- <para>We can inject the value of the portal container settings into
- the portal container configuration files thanks to the variables which
- name start with "<emphasis>portal.container.</emphasis>", so to get
- the value of a setting called "<emphasis>foo</emphasis>" just use the
- following syntax <emphasis>${portal.container.foo}</emphasis>. You can
- also use internal variables, such as:</para>
-
- <table>
- <title>Definition of the internal variables</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>portal.container.name</entry>
-
- <entry>Gives the name of the current portal container.</entry>
- </row>
-
- <row>
- <entry>portal.container.rest</entry>
-
- <entry>Gives the context name of the rest web application of
- the current portal container.</entry>
- </row>
-
- <row>
- <entry>portal.container.realm</entry>
-
- <entry>Gives the realm name of the current portal
- container.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>You can find below an example of how to use the
- variables:<programlisting><configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"
- xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd">
- <component>
- <type>org.exoplatform.container.TestPortalContainer$MyComponent</type>
- <init-params>
- <!-- The name of the portal container -->
- <value-param>
- <name>portal</name>
- <value>${portal.container.name}</value>
- </value-param>
- <!-- The name of the rest ServletContext -->
- <value-param>
- <name>rest</name>
- <value>${portal.container.rest}</value>
- </value-param>
- <!-- The name of the realm -->
- <value-param>
- <name>realm</name>
- <value>${portal.container.realm}</value>
- </value-param>
- <value-param>
- <name>foo</name>
- <value>${portal.container.foo}</value>
- </value-param>
- <value-param>
- <name>before foo after</name>
- <value>before ${portal.container.foo} after</value>
- </value-param>
- </init-params>
- </component>
-</configuration></programlisting></para>
-
- <para>In the properties file corresponding to the external settings,
- you can reuse variables previously defined (in the external settings
- or in the internal settings) to create a new variable. In this case
- the prefix "<emphasis>portal.container.</emphasis>" is not needed, see
- an example below:<programlisting>my-var1=value 1
-my-var2=value 2
-complex-value=${my-var1}-${my-var2}</programlisting></para>
-
- <para>In the external and internal settings, you can also use create
- variables based on value of System paramaters. The System parameters
- can either be defined at launch time or thanks to the
- <envar>PropertyConfigurator</envar> (see next section for more
- details). See an example below:</para>
-
- <programlisting>temp-dir=${java.io.tmpdir}${file.separator}my-temp</programlisting>
-
- <para>However, for the internal settings you can use System parameters
- only to define settings of type
- <envar>java.lang.String</envar>.</para>
-
- <para>It cans be also very usefull to define a generic variable in the
- settings of the default portal container, the value of this variable
- will change according to the current portal container. See below an
- example:<programlisting>my-generic-var=value of the portal container "${name}"</programlisting></para>
-
- <para>If this variable is defined at the default portal container
- level, the value of this variable for a portal container called
- <emphasis>"foo"</emphasis> will be <emphasis>value of the portal
- container "foo"</emphasis>.</para>
- </section>
- </section>
- </section>
-
- <section>
- <title>System property configuration</title>
-
- <para>A new property configurator service has been developed for taking
- care of configuring system properties from the inline kernel configuration
- or from specified property files.</para>
-
- <para>The services is scoped at the root container level because it is
- used by all the services in the different portal containers in the
- application runtime.</para>
-
- <section>
- <title>Properties init param</title>
-
- <para>The properties init param takes a property declared to configure
- various properties.</para>
-
- <programlisting><component>
- <key>PropertyManagerConfigurator</key>
- <type>org.exoplatform.container.PropertyConfigurator</type>
- <init-params>
- <properties-param>
- <name>properties</name>
- <property name="foo" value="bar"/>
- </properties-param>
- </init-params>
-</component></programlisting>
- </section>
-
- <section>
- <title>Properties URL init param</title>
-
- <para>The properties URL init param allow to load an external file by
- specifying its URL. Both property and XML format are supported, see the
- javadoc of the <emphasis><envar>java.util.Properties</envar></emphasis>
- class for more information. When a property file is loaded the various
- property declarations are loaded in the order in which the properties
- are declared sequentially in the file.</para>
-
- <programlisting><component>
- <key>PropertyManagerConfigurator</key>
- <type>org.exoplatform.container.PropertyConfigurator</type>
- <init-params>
- <value-param>
- <name>properties.url</name>
- <value>classpath:configuration.properties</value>
- </value-param>
- </init-params>
-</component></programlisting>
-
- <para>In the properties file corresponding to the external properties,
- you can reuse variables previously defined to create a new variable. In
- this case the prefix "<emphasis>portal.container.</emphasis>" is not
- needed, see an example below:<programlisting>my-var1=value 1
-my-var2=value 2
-complex-value=${my-var1}-${my-var2}</programlisting></para>
- </section>
-
- <section>
- <title>System Property configuration of the properties URL</title>
-
- <para>It is possible to replace the properties URL init param by a
- system property that overwrites it. The name of that property is
- <emphasis>exo.properties.url</emphasis>.</para>
- </section>
- </section>
-
- <section>
- <title>Runtime configuration profiles</title>
-
- <para>The kernel configuration is able to handle configuration profiles at
- runtime (as opposed to packaging time).</para>
-
- <section>
- <title>Profiles activation</title>
-
- <para>An active profile list is obtained during the boot of the root
- container and is composed of the system property
- <emphasis>exo.profiles</emphasis> sliced according the "," delimiter and
- also a server specific profile value (tomcat for tomcat, jboss for
- jboss, etc...).</para>
-
- <programlisting># runs GateIn on Tomcat with the profiles tomcat and foo
-sh gatein.sh -Dexo.profiles=foo
-
-# runs GateIn on JBoss with the profiles jboss, foo and bar
-sh run.sh -Dexo.profiles=foo,bar</programlisting>
- </section>
-
- <section>
- <title>Profiles configuration</title>
-
- <para>Profiles are configured in the configuration files of the eXo
- kernel.</para>
-
- <section>
- <title>Profiles definition</title>
-
- <para>Profile activation occurs at XML to configuration object
- unmarshalling time. It is based on an "profile" attribute that is
- present on some of the XML element of the configuration files. To
- enable this the kernel configuration schema has been upgraded to
- kernel_1_1.xsd. The configuration is based on the following
- rules:</para>
-
- <orderedlist>
- <listitem>
- <para>Any kernel element with the no <emphasis>profiles</emphasis>
- attribute will create a configuration object</para>
- </listitem>
-
- <listitem>
- <para>Any kernel element having a <emphasis>profiles</emphasis>
- attribute containing at least one of the active profiles will
- create a configuration object</para>
- </listitem>
-
- <listitem>
- <para>Any kernel element having a <emphasis>profiles</emphasis>
- attribute matching none of the active profile will not create a
- configuration object</para>
- </listitem>
-
- <listitem>
- <para>Resolution of duplicates (such as two components with same
- type) is left up to the kernel</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Profiles capable configuration elements</title>
-
- <para>A configuration element is <emphasis>profiles</emphasis> capable
- when it carries a profiles element.</para>
-
- <section>
- <title>Component element</title>
-
- <para>The component element declares a component when activated. It
- will shadow any element with the same key declared before in the
- same configuration file:</para>
-
- <programlisting><component>
- <key>Component</key>
- <type>Component</type>
-</component>
-
-<component profile="foo">
- <key>Component</key>
- <type>FooComponent</type>
-</component></programlisting>
- </section>
-
- <section>
- <title>Import element</title>
-
- <para>The import element imports a referenced configuration file
- when activated:</para>
-
- <programlisting><import>empty</import>
-<import profile="foo">foo</import>
-<import profile="bar">bar</import></programlisting>
- </section>
-
- <section>
- <title>Init param element</title>
-
- <para>The init param element configures the parameter argument of
- the construction of a component service:</para>
-
- <programlisting><component>
- <key>Component</key>
- <type>ComponentImpl</type>
- <init-params>
- <value-param>
- <name>param</name>
- <value>empty</value>
- </value-param>
- <value-param profile="foo">
- <name>param</name>
- <value>foo</value>
- </value-param>
- <value-param profile="bar">
- <name>param</name>
- <value>bar</value>
- </value-param>
- </init-params>
-</component></programlisting>
- </section>
-
- <section>
- <title>Value collection element</title>
-
- <para>The value collection element configures one of the value of
- collection data:</para>
-
- <programlisting><object type="org.exoplatform.container.configuration.ConfigParam">
- <field name="role">
- <collection type="java.util.ArrayList">
- <value><string>manager</string></value>
- <value profile="foo"><string>foo_manager</string></value>
- <value profile="foo,bar"><string>foo_bar_manager</string></value>
- </collection>
- </field>
-</object></programlisting>
- </section>
-
- <section>
- <title>Field configuration element</title>
-
- <para>The field configuration element configures the field of an
- object:</para>
-
- <programlisting><object-param>
- <name>test.configuration</name>
- <object type="org.exoplatform.container.configuration.ConfigParam">
- <field name="role">
- <collection type="java.util.ArrayList">
- <value><string>manager</string></value>
- </collection>
- </field>
- <field name="role" profile="foo,bar">
- <collection type="java.util.ArrayList">
- <value><string>foo_bar_manager</string></value>
- </collection>
- </field>
- <field name="role" profile="foo">
- <collection type="java.util.ArrayList">
- <value><string>foo_manager</string></value>
- </collection>
- </field>
- </object>
-</object-param></programlisting>
- </section>
- </section>
- </section>
- </section>
-
- <section>
- <title>Component request life cycle</title>
-
- <section>
- <title>Component request life cycle contract</title>
-
- <para>The component request life cycle is an interface that defines a
- contract for a component for being involved into a
- request:<programlisting>public interface ComponentRequestLifecycle
-{
- /**
- * Start a request.
- * @param container the related container
- */
- void startRequest(ExoContainer container);
-
- /**
- * Ends a request.
- * @param container the related container
- */
- void endRequest(ExoContainer container);
-}</programlisting></para>
-
- <para>The container passed is the container to which the component is
- related. This contract is often used to setup a thread local based
- context that will be demarcated by a request.</para>
-
- <para>For instance in the GateIn portal context, a component request
- life cycle is triggered for user requests. Another example is the
- initial data import in GateIn that demarcates using callbacks made to
- that interface.</para>
- </section>
-
- <section>
- <title>Request life cycle</title>
-
- <para>The <envar>RequestLifeCycle</envar> class has several statics
- methods that are used to schedule the component request life cycle of
- components. Its main responsability is to perform scheduling while
- respecting the constraint to execute the request life cycle of a
- component only once even if it can be scheduled several times.</para>
-
- <section>
- <title>Scheduling a component request life cycle</title>
-
- <programlisting>RequestLifeCycle.begin(component);
-try
-{
- // Do something
-}
-finally
-{
- RequestLifeCycle.end();
-}</programlisting>
- </section>
-
- <section>
- <title>Scheduling a container request life cycle</title>
-
- <para>Scheduling a container triggers the component request life cyle
- of all the components that implement the interface
- <envar>ComponentRequestLifeCycle</envar>. If one of the component has
- already been scheduled before then that component will not be
- scheduled again. When the local value is true then the looked
- components will be those of the container, when it is false then the
- scheduler will also look at the components in the ancestor
- containers.<programlisting>RequestLifeCycle.begin(container, local);
-try
-{
- // Do something
-}
-finally
-{
- RequestLifeCycle.end();
-}</programlisting></para>
- </section>
- </section>
-
- <section>
- <title>When request life cycle is triggered</title>
-
- <section>
- <title>Portal request life cycle</title>
-
- <para>Each portal request triggers the life cycle of the associated
- portal container.</para>
- </section>
-
- <section>
- <title>JMX request Life Cycle</title>
-
- <para>When a JMX bean is invoked, the request life cycle of the
- container to which it belongs it scheduled. Indeed JMX is an entry
- point of the system that may need component to have a request life
- cycle triggered.</para>
- </section>
- </section>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter>
+ <?dbhtml filename="ch-configuration.html"?>
+ <title>Configuration</title>
+
+ <section>
+ <title>Kernel configuration namespace</title>
+
+ <para>To be effective the namespace URI <link
+ linkend="???">http://www.exoplaform.org/xml/ns/kernel_1_1.xsd</link> must
+ be target namespace of the XML configuration file.</para>
+
+ <programlisting><xsd:schema
+ targetNamespace="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"
+ xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ elementFormDefault="qualified"
+ attributeFormDefault="unqualified"
+ version="1.0">
+
+ ...
+</xsd:schema></programlisting>
+ </section>
+
+ <section>
+ <title>Understanding How configuration files are loaded</title>
+
+ <para>eXo Portal uses PicoContainer, which implements the Inversion of
+ Control (IoC) design pattern. All eXo containers inherit from a
+ PicoContainer. There are mainly two eXo containers used, each of them can
+ provide one or several services. Each container service is delivered in a
+ JAR file. This JAR file may contain a default configuration. The use of
+ default configurations is recommended and most services provide it.</para>
+
+ <para>When a Pico Container searches for services and its configurations,
+ each configurable service may be reconfigured to override default values
+ or set additional parameters. If the service is configured in two or more
+ places the configuration override mechanism will be used.</para>
+
+ <section>
+ <title>Configuration Retrieval</title>
+
+ <para>The container performs the following steps making eXo Container
+ configuration retrieval depending on the container type.</para>
+
+ <section>
+ <title>Configuration retrieval order for the
+ <envar>PortalContainer</envar></title>
+
+ <para>The container is initialized by looking into different
+ locations. This container is used by portal applications.
+ Configurations are overloaded in the following lookup sequence:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Services default <envar>RootContainer</envar> configurations
+ from JAR files <emphasis>/conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>External <envar>RootContainer</envar> configuration, if will
+ be found at
+ <emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Services default <envar>PortalContainer</envar>
+ configurations from JAR files
+ <emphasis>/conf/portal/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Web applications configurations from WAR files
+ <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>External configuration for services of named portal, if will
+ be found at
+ <emphasis>$AS_HOME/exo-conf/portal/$PORTAL_NAME/configuration.xml</emphasis></para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Configuration retrieval for a
+ <envar>StandaloneContainer</envar></title>
+
+ <para>The container is initialized by looking into different
+ locations. This container is used by non portal applications.
+ Configurations are overloaded in the following lookup sequence:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Services default <envar>RootContainer</envar> configurations
+ from JAR files <emphasis>/conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>External <envar>RootContainer</envar> configuration, if will
+ be found at
+ <emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Services default <envar>StandaloneContainer</envar>
+ configurations from JAR files
+ <emphasis>/conf/portal/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Web applications configurations from WAR files
+ <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Then depending on the <envar>StandaloneContainer</envar>
+ configuration URL initialization:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>if configuration URL was initialized to be added to
+ services defaults, as below:<programlisting>// add configuration to the default services configurations from JARs/WARs
+StandaloneContainer.addConfigurationURL(containerConf);</programlisting></para>
+
+ <para>Configuration from added URL
+ <emphasis>containerConf</emphasis> will override only services
+ configured in the file</para>
+ </listitem>
+
+ <listitem>
+ <para>if configuration URL not initialized at all, it will be
+ found at <emphasis>$AS_HOME/exo-configuration.xml</emphasis>.
+ If <emphasis>$AS_HOME/exo-configuration.xml</emphasis> doesn't
+ exist the container will try find it at
+ <emphasis>$AS_HOME/exo-conf/exo-configuration.xml</emphasis>
+ location and if it's still not found and the
+ <envar>StandaloneContainer</envar> instance obtained with the
+ dedicated configuration <envar>ClassLoader</envar> the
+ container will try to retrieve the resource
+ <emphasis>conf/exo-configuration.xml</emphasis> within the
+ given <envar>ClassLoader</envar>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>General notes about the configuration retrieval</title>
+
+ <note>
+ <para><emphasis>$AS_HOME</emphasis> - application server home
+ directory, or <emphasis>user.dir</emphasis> JVM system property
+ value in case of Java Standalone application.</para>
+ </note>
+
+ <note>
+ <para><emphasis>$PORTAL_NAME</emphasis> - portal web application
+ name.</para>
+ </note>
+
+ <note>
+ <para>External configuration location can be overridden with System
+ property <emphasis>exo.conf.dir</emphasis>. If the property exists
+ its value will be used as path to eXo configuration directory, i.e.
+ to <emphasis>$AS_HOME/exo-conf</emphasis> alternative. E.g. put
+ property in command line java
+ <emphasis>-Dexo.conf.dir=/path/to/exo/conf</emphasis>. In this
+ particular use case, you have no need to use any prefix to import
+ other files. For instance, if your configuration file is
+ <emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/configuration.xml</emphasis>
+ and you want to import the configuration file
+ <emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/mySubConfDir/myConfig.xml</emphasis>,
+ you can do it by adding
+ <emphasis><import>mySubConfDir/myConfig.xml</import></emphasis>
+ to your configuration file.</para>
+ </note>
+
+ <note>
+ <para>The name of the configuration folder that is by default
+ <emphasis>"exo-conf"</emphasis>, can be changed thanks to the System
+ property <emphasis>exo.conf.dir.name</emphasis>.</para>
+ </note>
+
+ <note>
+ <para>Under JBoss application server <emphasis>exo-conf</emphasis>
+ will be looked up in directory described by JBoss System property
+ <emphasis>jboss.server.config.url</emphasis>. If the property is not
+ found or empty <emphasis>$AS_HOME/exo-conf</emphasis> will be
+ asked.</para>
+ </note>
+
+ <note>
+ <para>The search looks for a configuration file in each JAR/WAR
+ available from the classpath using the current thread context
+ classloader. During the search these configurations are added to a
+ set. If the service was configured previously and the current JAR
+ contains a new configuration of that service the latest (from the
+ current JAR/WAR) will replace the previous one. The last one will be
+ applied to the service during the services start phase.</para>
+ </note>
+
+ <warning>
+ <para>Take care to have no dependencies between configurations from
+ JAR files (<emphasis>/conf/portal/configuration.xml</emphasis> and
+ <emphasis>/conf/configuration.xml</emphasis>) since we have no way
+ to know in advance the loading order of those configurations. In
+ other words, if you want to overload some configuration located in
+ the file <emphasis>/conf/portal/configuration.xml</emphasis> of a
+ given JAR file, you must not do it from the file
+ <emphasis>/conf/portal/configuration.xml</emphasis> of another JAR
+ file but from another configuration file loaded after configurations
+ from JAR files
+ <emphasis>/conf/portal/configuration.xml.</emphasis></para>
+ </warning>
+
+ <para>After the processing of all configurations available in system
+ the container will initialize it and start each service in order of
+ the dependency injection (DI).</para>
+
+ <para>The user/developer should be careful when configuring the same
+ service in different configuration files. It's recommended to
+ configure a service in its own JAR only. Or, in case of a portal
+ configuration, strictly reconfigure the services in portal WAR files
+ or in an external configuration.</para>
+
+ <para>There are services that can be (or should be) configured more
+ than one time. This depends on business logic of the service. A
+ service may initialize the same resource (shared with other services)
+ or may add a particular object to a set of objects (shared with other
+ services too). In the first case it's critical who will be the last,
+ i.e. whose configuration will be used. In the second case it's no
+ matter who is the first and who is the last (if the parameter objects
+ are independent).</para>
+ </section>
+
+ <section>
+ <title>Configuration retrieval log</title>
+
+ <para>In case of problems with service configuration it's important to
+ know from which JAR/WAR it comes. For that purpose the JVM system
+ property
+ <emphasis>org.exoplatform.container.configuration.debug</emphasis> can
+ be used.<programlisting>java -Dorg.exoplatform.container.configuration.debug ...</programlisting></para>
+
+ <para>If the property is enabled the container configuration manager
+ will report the configuration adding process to the standard output
+ (System.out).<programlisting>......
+ Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.container-trunk.jar!/conf/portal/configuration.xml
+ Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.component.cache-trunk.jar!/conf/portal/configuration.xml
+ Add configuration jndi:/localhost/portal/WEB-INF/conf/configuration.xml
+ import jndi:/localhost/portal/WEB-INF/conf/common/common-configuration.xml
+ import jndi:/localhost/portal/WEB-INF/conf/database/database-configuration.xml
+ import jndi:/localhost/portal/WEB-INF/conf/ecm/jcr-component-plugins-configuration.xml
+ import jndi:/localhost/portal/WEB-INF/conf/jcr/jcr-configuration.xml
+ ......</programlisting></para>
+ </section>
+ </section>
+
+ <section>
+ <title>Advanced concepts for the
+ <emphasis>PortalContainers</emphasis></title>
+
+ <para>Since eXo JCR 1.12, we added a set of new features that have been
+ designed to extend portal applications such as GateIn.</para>
+
+ <section>
+ <title>Add new configuration files from a WAR file</title>
+
+ <para>A <envar>ServletContextListener</envar> called
+ <envar>org.exoplatform.container.web.PortalContainerConfigOwner</envar>
+ has been added in order to notify the application that a given web
+ application provides some configuration to the portal container, and
+ this configuration file is the file
+ <emphasis>WEB-INF/conf/configuration.xml</emphasis> available in the
+ web application itself.</para>
+
+ <para>If your war file contains some configuration to add to the
+ <envar>PortalContainer</envar> simply add the following lines in your
+ <emphasis>web.xml</emphasis> file.</para>
+
+ <programlisting><?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+ "http://java.sun.com/dtd/web-app_2_3.dtd">
+<web-app>
+...
+ <!-- ================================================================== -->
+ <!-- LISTENER -->
+ <!-- ================================================================== -->
+ <listener>
+ <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class>
+ </listener>
+...
+</web-app></programlisting>
+ </section>
+
+ <section>
+ <title>Create your <emphasis>PortalContainers</emphasis> from a WAR
+ file</title>
+
+ <para>A <envar>ServletContextListener</envar> called
+ <envar>org.exoplatform.container.web.PortalContainerCreator</envar>
+ has been added in order to create the current portal containers that
+ have been registered. We assume that all the web applications have
+ already been loaded before calling
+ <envar>PortalContainerCreator.contextInitialized<replaceable><optional>.</optional></replaceable></envar></para>
+
+ <para><note>
+ <para>In GateIn, the <envar>PortalContainerCreator</envar> is
+ already managed by the file
+ <emphasis>starter.war/ear.</emphasis></para>
+ </note></para>
+ </section>
+
+ <section>
+ <title>Define a <emphasis>PortalContainer</emphasis> with its
+ dependencies and its settings</title>
+
+ <para>Now we can define precisely a portal container and its
+ dependencies and settings thanks to the
+ <envar>PortalContainerDefinition</envar> that currently contains the
+ name of the portal container, the name of the rest context, the name
+ of the realm he web application dependencies ordered by loading
+ priority (i.e. the first dependency must be loaded at first and so
+ on..) and the settings.</para>
+
+ <para>To be able to define a <envar>PortalContainerDefinition</envar>,
+ we need to ensure first of all that a
+ <envar>PortalContainerConfig</envar> has been defined at the
+ <envar>RootContainer</envar> level, see below an example:</para>
+
+ <programlisting> <component>
+ <!-- The full qualified name of the PortalContainerConfig -->
+ <type>org.exoplatform.container.definition.PortalContainerConfig</type>
+ <init-params>
+ <!-- The name of the default portal container -->
+ <value-param>
+ <name>default.portal.container</name>
+ <value>myPortal</value>
+ </value-param>
+ <!-- The name of the default rest ServletContext -->
+ <value-param>
+ <name>default.rest.context</name>
+ <value>myRest</value>
+ </value-param>
+ <!-- The name of the default realm -->
+ <value-param>
+ <name>default.realm.name</name>
+ <value>my-exo-domain</value>
+ </value-param>
+ <!-- The default portal container definition -->
+ <!-- It cans be used to avoid duplicating configuration -->
+ <object-param>
+ <name>default.portal.definition</name>
+ <object type="org.exoplatform.container.definition.PortalContainerDefinition">
+ <!-- All the dependencies of the portal container ordered by loading priority -->
+ <field name="dependencies">
+ <collection type="java.util.ArrayList">
+ <value>
+ <string>foo</string>
+ </value>
+ <value>
+ <string>foo2</string>
+ </value>
+ <value>
+ <string>foo3</string>
+ </value>
+ </collection>
+ </field>
+ <!-- A map of settings tied to the default portal container -->
+ <field name="settings">
+ <map type="java.util.HashMap">
+ <entry>
+ <key>
+ <string>foo5</string>
+ </key>
+ <value>
+ <string>value</string>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>string</string>
+ </key>
+ <value>
+ <string>value0</string>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>int</string>
+ </key>
+ <value>
+ <int>100</int>
+ </value>
+ </entry>
+ </map>
+ </field>
+ <!-- The path to the external properties file -->
+ <field name="externalSettingsPath">
+ <string>classpath:/org/exoplatform/container/definition/default-settings.properties</string>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component></programlisting>
+
+ <table>
+ <title>Descriptions of the fields of
+ <envar>PortalContainerConfig</envar></title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>default.portal.container</entry>
+
+ <entry>The name of the default portal container. This field is
+ optional.</entry>
+ </row>
+
+ <row>
+ <entry>default.rest.context</entry>
+
+ <entry>The name of the default rest
+ <envar>ServletContext</envar>. This field is optional.</entry>
+ </row>
+
+ <row>
+ <entry>default.realm.name</entry>
+
+ <entry>The name of the default realm. This field is
+ optional.</entry>
+ </row>
+
+ <row>
+ <entry>default.portal.definition</entry>
+
+ <entry>The definition of the default portal container. This
+ field is optional. The expected type is
+ <envar>org.exoplatform.container.definition.PortalContainerDefinition</envar>
+ that is described below. Allow the parameters defined in this
+ default <envar>PortalContainerDefinition</envar> will be the
+ default values.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>A new <envar>PortalContainerDefinition</envar> can be defined at
+ the <envar>RootContainer</envar> level thanks to an external plugin,
+ see below an example:<programlisting> <external-component-plugins>
+ <!-- The full qualified name of the PortalContainerConfig -->
+ <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
+ <component-plugin>
+ <!-- The name of the plugin -->
+ <name>Add PortalContainer Definitions</name>
+ <!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions -->
+ <set-method>registerPlugin</set-method>
+ <!-- The full qualified name of the PortalContainerDefinitionPlugin -->
+ <type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type>
+ <init-params>
+ <object-param>
+ <name>portal</name>
+ <object type="org.exoplatform.container.definition.PortalContainerDefinition">
+ <!-- The name of the portal container -->
+ <field name="name">
+ <string>myPortal</string>
+ </field>
+ <!-- The name of the context name of the rest web application -->
+ <field name="restContextName">
+ <string>myRest</string>
+ </field>
+ <!-- The name of the realm -->
+ <field name="realmName">
+ <string>my-domain</string>
+ </field>
+ <!-- All the dependencies of the portal container ordered by loading priority -->
+ <field name="dependencies">
+ <collection type="java.util.ArrayList">
+ <value>
+ <string>foo</string>
+ </value>
+ <value>
+ <string>foo2</string>
+ </value>
+ <value>
+ <string>foo3</string>
+ </value>
+ </collection>
+ </field>
+ <!-- A map of settings tied to the portal container -->
+ <field name="settings">
+ <map type="java.util.HashMap">
+ <entry>
+ <key>
+ <string>foo</string>
+ </key>
+ <value>
+ <string>value</string>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>int</string>
+ </key>
+ <value>
+ <int>10</int>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>long</string>
+ </key>
+ <value>
+ <long>10</long>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>double</string>
+ </key>
+ <value>
+ <double>10</double>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>boolean</string>
+ </key>
+ <value>
+ <boolean>true</boolean>
+ </value>
+ </entry>
+ </map>
+ </field>
+ <!-- The path to the external properties file -->
+ <field name="externalSettingsPath">
+ <string>classpath:/org/exoplatform/container/definition/settings.properties</string>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+ </external-component-plugins></programlisting></para>
+
+ <table>
+ <title>Descriptions of the fields of
+ <envar>PortalContainerDefinition</envar> when it is used to define a
+ new portal container</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>name</entry>
+
+ <entry>The name of the portal container. This field is
+ mandatory .</entry>
+ </row>
+
+ <row>
+ <entry>restContextName</entry>
+
+ <entry>The name of the context name of the rest web
+ application. This field is optional. The default value will
+ the value define at the <envar>PortalContainerConfig</envar>
+ level.</entry>
+ </row>
+
+ <row>
+ <entry>realmName</entry>
+
+ <entry>The name of the realm. This field is optional. The
+ default value will the value define at the
+ <envar>PortalContainerConfig</envar> level.</entry>
+ </row>
+
+ <row>
+ <entry>dependencies</entry>
+
+ <entry>All the dependencies of the portal container ordered by
+ loading priority. This field is optional. The default value
+ will the value define at the
+ <envar>PortalContainerConfig</envar> level. The dependencies
+ are in fact the list of the context names of the web
+ applications from which the portal container depends. This
+ field is optional. The dependency order is really crucial
+ since it will be interpreted the same way by several
+ components of the platform. All those components, will
+ consider the 1st element in the list less important than the
+ second element and so on. It is currently used
+ to:<itemizedlist>
+ <listitem>
+ <para>Know the loading order of all the
+ dependencies.</para>
+ </listitem>
+
+ <listitem>
+ <para>If we have several
+ <envar>PortalContainerConfigOwner</envar><itemizedlist>
+ <listitem>
+ <para>The <envar>ServletContext</envar> of all the
+ <envar>PortalContainerConfigOwner</envar> will be
+ unified, if we use the unified
+ <envar>ServletContext</envar>
+ (<emphasis>PortalContainer.getPortalContext()</emphasis>)
+ to get a resource, it will try to get the resource
+ in the <envar>ServletContext</envar> of the most
+ important <envar>PortalContainerConfigOwner</envar>
+ (i.e. last in the dependency list) and if it cans
+ find it, it will try with the second most important
+ <envar>PortalContainerConfigOwner</envar> and so
+ on.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <envar>ClassLoader</envar> of all the
+ <envar>PortalContainerConfigOwner</envar> will be
+ unified, if we use the unified
+ <envar>ClassLoader</envar>
+ (<emphasis>PortalContainer.getPortalClassLoader()</emphasis>)
+ to get a resource, it will try to get the resource
+ in the <envar>ClassLoader</envar> of the most
+ important <envar>PortalContainerConfigOwner</envar>
+ (i.e. last in the dependency list) and if it cans
+ find it, it will try with the second most important
+ <envar>PortalContainerConfigOwner</envar> and so
+ on.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+ </itemizedlist></entry>
+ </row>
+
+ <row>
+ <entry>settings</entry>
+
+ <entry>A <envar>java.util.Map</envar> of internal parameters
+ that we would like to tie the portal container. Those
+ parameters could have any type of value. This field is
+ optional. If some internal settings are defined at the
+ <envar>PortalContainerConfig</envar> level, the two maps of
+ settings will be merged. If a setting with the same name is
+ defined in both maps, it will keep the value defined at the
+ <envar>PortalContainerDefinition</envar> level.</entry>
+ </row>
+
+ <row>
+ <entry>externalSettingsPath</entry>
+
+ <entry>The path of the external properties file to load as
+ default settings to the portal container. This field is
+ optional. If some external settings are defined at the
+ <envar>PortalContainerConfig</envar> level, the two maps of
+ settings will be merged. If a setting with the same name is
+ defined in both maps, it will keep the value defined at the
+ <envar>PortalContainerDefinition</envar> level. The external
+ properties files can be either of type "properties" or of type
+ "xml". The path will be interpreted as follows:<orderedlist>
+ <listitem>
+ <para>The path doesn't contain any prefix of type
+ "classpath:", "jar:" or "file:", we assume that the file
+ could be externalized so we apply the following
+ rules:<orderedlist>
+ <listitem>
+ <para>A file exists at
+ <emphasis>${exo-conf-dir}/portal/${portalContainerName}/${externalSettingsPath}</emphasis>,
+ we will load this file.</para>
+ </listitem>
+
+ <listitem>
+ <para>No file exists at the previous path, we then
+ assume that the path cans be interpreted by the
+ <envar>ConfigurationManager</envar>.</para>
+ </listitem>
+ </orderedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>The path contains a prefix, we then assume that
+ the path cans be interpreted by the
+ <envar>ConfigurationManager</envar>.</para>
+ </listitem>
+ </orderedlist></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table>
+ <title>Descriptions of the fields of
+ <envar>PortalContainerDefinition</envar> when it is used to define
+ the default portal container</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>name</entry>
+
+ <entry>The name of the portal container. This field is
+ optional. The default portal name will be:<orderedlist>
+ <listitem>
+ <para>If this field is not empty, then the default value
+ will be the value of this field.</para>
+ </listitem>
+
+ <listitem>
+ <para>If this field is empty and the value of the
+ parameter <emphasis>default.portal.container</emphasis>
+ is not empty, then the default value will be the value
+ of the parameter.</para>
+ </listitem>
+
+ <listitem>
+ <para>If this field and the parameter
+ <emphasis>default.portal.container</emphasis> are both
+ empty, the default value will be
+ <emphasis>"portal".</emphasis></para>
+ </listitem>
+ </orderedlist></entry>
+ </row>
+
+ <row>
+ <entry>restContextName</entry>
+
+ <entry>The name of the context name of the rest web
+ application. This field is optional. The default value wil
+ be:<orderedlist>
+ <listitem>
+ <para>If this field is not empty, then the default value
+ will be the value of this field.</para>
+ </listitem>
+
+ <listitem>
+ <para>f this field is empty and the value of the
+ parameter <emphasis>default.rest.context</emphasis> is
+ not empty, then the default value will be the value of
+ the parameter.</para>
+ </listitem>
+
+ <listitem>
+ <para>f this field and the parameter
+ <emphasis>default.rest.context</emphasis> are both
+ empty, the default value will be
+ <emphasis>"rest".</emphasis></para>
+ </listitem>
+ </orderedlist></entry>
+ </row>
+
+ <row>
+ <entry>realmName</entry>
+
+ <entry>The name of the realm. This field is optional. The
+ default value wil be:<orderedlist>
+ <listitem>
+ <para>If this field is not empty, then the default value
+ will be the value of this field.</para>
+ </listitem>
+
+ <listitem>
+ <para>f this field is empty and the value of the
+ parameter <emphasis>default.realm.name</emphasis> is not
+ empty, then the default value will be the value of the
+ parameter.</para>
+ </listitem>
+
+ <listitem>
+ <para>f this field and the parameter
+ <emphasis>default.realm.name</emphasis> are both empty,
+ the default value will be
+ <emphasis>"exo-domain".</emphasis></para>
+ </listitem>
+ </orderedlist></entry>
+ </row>
+
+ <row>
+ <entry>dependencies</entry>
+
+ <entry>All the dependencies of the portal container ordered by
+ loading priority. This field is optional. If this field has a
+ non empty value, it will be the default list of
+ dependencies.</entry>
+ </row>
+
+ <row>
+ <entry>settings</entry>
+
+ <entry>A <envar>java.util.Map</envar> of internal parameters
+ that we would like to tie the default portal container. Those
+ parameters could have any type of value. This field is
+ optional.</entry>
+ </row>
+
+ <row>
+ <entry>externalSettingsPath</entry>
+
+ <entry>The path of the external properties file to load as
+ default settings to the default portal container. This field
+ is optional. The external properties files can be either of
+ type "properties" or of type "xml". The path will be
+ interpreted as follows:<orderedlist>
+ <listitem>
+ <para>The path doesn't contain any prefix of type
+ "classpath:", "jar:" or "file:", we assume that the file
+ could be externalized so we apply the following
+ rules:<orderedlist>
+ <listitem>
+ <para>A file exists at
+ <emphasis>${exo-conf-dir}/portal/${externalSettingsPath}</emphasis>,
+ we will load this file.</para>
+ </listitem>
+
+ <listitem>
+ <para>No file exists at the previous path, we then
+ assume that the path cans be interpreted by the
+ <envar>ConfigurationManager</envar>.</para>
+ </listitem>
+ </orderedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>The path contains a prefix, we then assume that
+ the path cans be interpreted by the
+ <envar>ConfigurationManager</envar>.</para>
+ </listitem>
+ </orderedlist></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Internal and external settings are both optional, but if we give
+ a non empty value for both the application will merge the settings. If
+ the same setting name exists in both settings, we apply the following
+ rules:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The value of the external setting is
+ <emphasis>null</emphasis>, we ignore the value.</para>
+ </listitem>
+
+ <listitem>
+ <para>The value of the external setting is not
+ <emphasis>null</emphasis> and the value of the internal setting is
+ <emphasis>null</emphasis>, the final value will be the external
+ setting value that is of type <envar>String</envar>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Both values are not <envar>null</envar>, we will have to
+ convert the external setting value into the target type which is
+ the type of the internal setting value, thanks to the static
+ method <emphasis>valueOf(String)</emphasis>, the following
+ sub-rules are then applied:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The method cannot be found, the final value will be the
+ external setting value that is of type
+ <envar>String</envar>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method can be found and the external setting value
+ is an empty <envar>String</envar>, we ignore the external
+ setting value.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method can be found and the external setting value
+ is not an empty <envar>String</envar> but the method call
+ fails, we ignore the external setting value.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method can be found and the external setting value
+ is not an empty <envar>String</envar> and the method call
+ succeeds, the final value will be the external setting value
+ that is of type of the internal setting value.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title><envar>PortalContainer</envar> settings</title>
+
+ <para>We can inject the value of the portal container settings into
+ the portal container configuration files thanks to the variables which
+ name start with "<emphasis>portal.container.</emphasis>", so to get
+ the value of a setting called "<emphasis>foo</emphasis>" just use the
+ following syntax <emphasis>${portal.container.foo}</emphasis>. You can
+ also use internal variables, such as:</para>
+
+ <table>
+ <title>Definition of the internal variables</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>portal.container.name</entry>
+
+ <entry>Gives the name of the current portal container.</entry>
+ </row>
+
+ <row>
+ <entry>portal.container.rest</entry>
+
+ <entry>Gives the context name of the rest web application of
+ the current portal container.</entry>
+ </row>
+
+ <row>
+ <entry>portal.container.realm</entry>
+
+ <entry>Gives the realm name of the current portal
+ container.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>You can find below an example of how to use the
+ variables:<programlisting><configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"
+ xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd">
+ <component>
+ <type>org.exoplatform.container.TestPortalContainer$MyComponent</type>
+ <init-params>
+ <!-- The name of the portal container -->
+ <value-param>
+ <name>portal</name>
+ <value>${portal.container.name}</value>
+ </value-param>
+ <!-- The name of the rest ServletContext -->
+ <value-param>
+ <name>rest</name>
+ <value>${portal.container.rest}</value>
+ </value-param>
+ <!-- The name of the realm -->
+ <value-param>
+ <name>realm</name>
+ <value>${portal.container.realm}</value>
+ </value-param>
+ <value-param>
+ <name>foo</name>
+ <value>${portal.container.foo}</value>
+ </value-param>
+ <value-param>
+ <name>before foo after</name>
+ <value>before ${portal.container.foo} after</value>
+ </value-param>
+ </init-params>
+ </component>
+</configuration></programlisting></para>
+
+ <para>In the properties file corresponding to the external settings,
+ you can reuse variables previously defined (in the external settings
+ or in the internal settings) to create a new variable. In this case
+ the prefix "<emphasis>portal.container.</emphasis>" is not needed, see
+ an example below:<programlisting>my-var1=value 1
+my-var2=value 2
+complex-value=${my-var1}-${my-var2}</programlisting></para>
+
+ <para>In the external and internal settings, you can also use create
+ variables based on value of System paramaters. The System parameters
+ can either be defined at launch time or thanks to the
+ <envar>PropertyConfigurator</envar> (see next section for more
+ details). See an example below:</para>
+
+ <programlisting>temp-dir=${java.io.tmpdir}${file.separator}my-temp</programlisting>
+
+ <para>However, for the internal settings you can use System parameters
+ only to define settings of type
+ <envar>java.lang.String</envar>.</para>
+
+ <para>It cans be also very usefull to define a generic variable in the
+ settings of the default portal container, the value of this variable
+ will change according to the current portal container. See below an
+ example:<programlisting>my-generic-var=value of the portal container "${name}"</programlisting></para>
+
+ <para>If this variable is defined at the default portal container
+ level, the value of this variable for a portal container called
+ <emphasis>"foo"</emphasis> will be <emphasis>value of the portal
+ container "foo"</emphasis>.</para>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>System property configuration</title>
+
+ <para>A new property configurator service has been developed for taking
+ care of configuring system properties from the inline kernel configuration
+ or from specified property files.</para>
+
+ <para>The services is scoped at the root container level because it is
+ used by all the services in the different portal containers in the
+ application runtime.</para>
+
+ <section>
+ <title>Properties init param</title>
+
+ <para>The properties init param takes a property declared to configure
+ various properties.</para>
+
+ <programlisting><component>
+ <key>PropertyManagerConfigurator</key>
+ <type>org.exoplatform.container.PropertyConfigurator</type>
+ <init-params>
+ <properties-param>
+ <name>properties</name>
+ <property name="foo" value="bar"/>
+ </properties-param>
+ </init-params>
+</component></programlisting>
+ </section>
+
+ <section>
+ <title>Properties URL init param</title>
+
+ <para>The properties URL init param allow to load an external file by
+ specifying its URL. Both property and XML format are supported, see the
+ javadoc of the <emphasis><envar>java.util.Properties</envar></emphasis>
+ class for more information. When a property file is loaded the various
+ property declarations are loaded in the order in which the properties
+ are declared sequentially in the file.</para>
+
+ <programlisting><component>
+ <key>PropertyManagerConfigurator</key>
+ <type>org.exoplatform.container.PropertyConfigurator</type>
+ <init-params>
+ <value-param>
+ <name>properties.url</name>
+ <value>classpath:configuration.properties</value>
+ </value-param>
+ </init-params>
+</component></programlisting>
+
+ <para>In the properties file corresponding to the external properties,
+ you can reuse variables previously defined to create a new variable. In
+ this case the prefix "<emphasis>portal.container.</emphasis>" is not
+ needed, see an example below:<programlisting>my-var1=value 1
+my-var2=value 2
+complex-value=${my-var1}-${my-var2}</programlisting></para>
+ </section>
+
+ <section>
+ <title>System Property configuration of the properties URL</title>
+
+ <para>It is possible to replace the properties URL init param by a
+ system property that overwrites it. The name of that property is
+ <emphasis>exo.properties.url</emphasis>.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Runtime configuration profiles</title>
+
+ <para>The kernel configuration is able to handle configuration profiles at
+ runtime (as opposed to packaging time).</para>
+
+ <section>
+ <title>Profiles activation</title>
+
+ <para>An active profile list is obtained during the boot of the root
+ container and is composed of the system property
+ <emphasis>exo.profiles</emphasis> sliced according the "," delimiter and
+ also a server specific profile value (tomcat for tomcat, jboss for
+ jboss, etc...).</para>
+
+ <programlisting># runs GateIn on Tomcat with the profiles tomcat and foo
+sh gatein.sh -Dexo.profiles=foo
+
+# runs GateIn on JBoss with the profiles jboss, foo and bar
+sh run.sh -Dexo.profiles=foo,bar</programlisting>
+ </section>
+
+ <section>
+ <title>Profiles configuration</title>
+
+ <para>Profiles are configured in the configuration files of the eXo
+ kernel.</para>
+
+ <section>
+ <title>Profiles definition</title>
+
+ <para>Profile activation occurs at XML to configuration object
+ unmarshalling time. It is based on an "profile" attribute that is
+ present on some of the XML element of the configuration files. To
+ enable this the kernel configuration schema has been upgraded to
+ kernel_1_1.xsd. The configuration is based on the following
+ rules:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Any kernel element with the no <emphasis>profiles</emphasis>
+ attribute will create a configuration object</para>
+ </listitem>
+
+ <listitem>
+ <para>Any kernel element having a <emphasis>profiles</emphasis>
+ attribute containing at least one of the active profiles will
+ create a configuration object</para>
+ </listitem>
+
+ <listitem>
+ <para>Any kernel element having a <emphasis>profiles</emphasis>
+ attribute matching none of the active profile will not create a
+ configuration object</para>
+ </listitem>
+
+ <listitem>
+ <para>Resolution of duplicates (such as two components with same
+ type) is left up to the kernel</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Profiles capable configuration elements</title>
+
+ <para>A configuration element is <emphasis>profiles</emphasis> capable
+ when it carries a profiles element.</para>
+
+ <section>
+ <title>Component element</title>
+
+ <para>The component element declares a component when activated. It
+ will shadow any element with the same key declared before in the
+ same configuration file:</para>
+
+ <programlisting><component>
+ <key>Component</key>
+ <type>Component</type>
+</component>
+
+<component profile="foo">
+ <key>Component</key>
+ <type>FooComponent</type>
+</component></programlisting>
+ </section>
+
+ <section>
+ <title>Import element</title>
+
+ <para>The import element imports a referenced configuration file
+ when activated:</para>
+
+ <programlisting><import>empty</import>
+<import profile="foo">foo</import>
+<import profile="bar">bar</import></programlisting>
+ </section>
+
+ <section>
+ <title>Init param element</title>
+
+ <para>The init param element configures the parameter argument of
+ the construction of a component service:</para>
+
+ <programlisting><component>
+ <key>Component</key>
+ <type>ComponentImpl</type>
+ <init-params>
+ <value-param>
+ <name>param</name>
+ <value>empty</value>
+ </value-param>
+ <value-param profile="foo">
+ <name>param</name>
+ <value>foo</value>
+ </value-param>
+ <value-param profile="bar">
+ <name>param</name>
+ <value>bar</value>
+ </value-param>
+ </init-params>
+</component></programlisting>
+ </section>
+
+ <section>
+ <title>Value collection element</title>
+
+ <para>The value collection element configures one of the value of
+ collection data:</para>
+
+ <programlisting><object type="org.exoplatform.container.configuration.ConfigParam">
+ <field name="role">
+ <collection type="java.util.ArrayList">
+ <value><string>manager</string></value>
+ <value profile="foo"><string>foo_manager</string></value>
+ <value profile="foo,bar"><string>foo_bar_manager</string></value>
+ </collection>
+ </field>
+</object></programlisting>
+ </section>
+
+ <section>
+ <title>Field configuration element</title>
+
+ <para>The field configuration element configures the field of an
+ object:</para>
+
+ <programlisting><object-param>
+ <name>test.configuration</name>
+ <object type="org.exoplatform.container.configuration.ConfigParam">
+ <field name="role">
+ <collection type="java.util.ArrayList">
+ <value><string>manager</string></value>
+ </collection>
+ </field>
+ <field name="role" profile="foo,bar">
+ <collection type="java.util.ArrayList">
+ <value><string>foo_bar_manager</string></value>
+ </collection>
+ </field>
+ <field name="role" profile="foo">
+ <collection type="java.util.ArrayList">
+ <value><string>foo_manager</string></value>
+ </collection>
+ </field>
+ </object>
+</object-param></programlisting>
+ </section>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Component request life cycle</title>
+
+ <section>
+ <title>Component request life cycle contract</title>
+
+ <para>The component request life cycle is an interface that defines a
+ contract for a component for being involved into a
+ request:<programlisting>public interface ComponentRequestLifecycle
+{
+ /**
+ * Start a request.
+ * @param container the related container
+ */
+ void startRequest(ExoContainer container);
+
+ /**
+ * Ends a request.
+ * @param container the related container
+ */
+ void endRequest(ExoContainer container);
+}</programlisting></para>
+
+ <para>The container passed is the container to which the component is
+ related. This contract is often used to setup a thread local based
+ context that will be demarcated by a request.</para>
+
+ <para>For instance in the GateIn portal context, a component request
+ life cycle is triggered for user requests. Another example is the
+ initial data import in GateIn that demarcates using callbacks made to
+ that interface.</para>
+ </section>
+
+ <section>
+ <title>Request life cycle</title>
+
+ <para>The <envar>RequestLifeCycle</envar> class has several statics
+ methods that are used to schedule the component request life cycle of
+ components. Its main responsability is to perform scheduling while
+ respecting the constraint to execute the request life cycle of a
+ component only once even if it can be scheduled several times.</para>
+
+ <section>
+ <title>Scheduling a component request life cycle</title>
+
+ <programlisting>RequestLifeCycle.begin(component);
+try
+{
+ // Do something
+}
+finally
+{
+ RequestLifeCycle.end();
+}</programlisting>
+ </section>
+
+ <section>
+ <title>Scheduling a container request life cycle</title>
+
+ <para>Scheduling a container triggers the component request life cyle
+ of all the components that implement the interface
+ <envar>ComponentRequestLifeCycle</envar>. If one of the component has
+ already been scheduled before then that component will not be
+ scheduled again. When the local value is true then the looked
+ components will be those of the container, when it is false then the
+ scheduler will also look at the components in the ancestor
+ containers.<programlisting>RequestLifeCycle.begin(container, local);
+try
+{
+ // Do something
+}
+finally
+{
+ RequestLifeCycle.end();
+}</programlisting></para>
+ </section>
+ </section>
+
+ <section>
+ <title>When request life cycle is triggered</title>
+
+ <section>
+ <title>Portal request life cycle</title>
+
+ <para>Each portal request triggers the life cycle of the associated
+ portal container.</para>
+ </section>
+
+ <section>
+ <title>JMX request Life Cycle</title>
+
+ <para>When a JMX bean is invoked, the request life cycle of the
+ container to which it belongs it scheduled. Indeed JMX is an entry
+ point of the system that may need component to have a request life
+ cycle triggered.</para>
+ </section>
+ </section>
+ </section>
+</chapter>
Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/logging.xml
===================================================================
--- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/logging.xml (rev 0)
+++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/logging.xml 2010-03-26 13:04:08 UTC (rev 2167)
@@ -0,0 +1,234 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="ch_log_configuration">
+ <?dbhtml filename="ch-log-configuration.html"?>
+
+ <title>Logs configuration</title>
+
+ <section>
+ <title>Introdution</title>
+
+ <para>In order to accommodate to the different target runtime where it can
+ be deployed, eXo is capable of leveraging several logging systems. eXo
+ let's you choose the underlying logging engine to use and even configure
+ that engine (as a quick alternative to doing it directly in your runtime
+ environment).</para>
+
+ <para>The currently supported logging engines are : <itemizedlist>
+ <listitem>
+ <para>Apache Log4J</para>
+ </listitem>
+
+ <listitem>
+ <para>JDK's logging</para>
+ </listitem>
+
+ <listitem>
+ <para>Apache Commons logging (which is itself a pluggable logging
+ abstraction)</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Logs configuration initializer</title>
+
+ <para>eXo lets you choose whatever logging engine you want as this is
+ generally influences by the AS runtime or internal policy.</para>
+
+ <para>This is done through an eXo component called
+ <classname>LogConfigurationInitializer</classname>.</para>
+
+ <para><classname>org.exoplatform.services.log.LogConfigurationInitializer</classname>
+ that reads init parameters and configures logging system according to
+ them. The parameters:<itemizedlist>
+ <listitem>
+ <para><firstterm>configurator</firstterm> - an implementation of the
+ <classname>LogConfigurator</classname> interface with one method
+ configure() that accepts a list of properties (3rd init parameter)
+ to configure the underlying log system using the concrete mechanism.
+ Again there are three configurators for the most known log systems
+ (commons, log4j, jdk).</para>
+ </listitem>
+
+ <listitem>
+ <para><firstterm>properties</firstterm> - properties to configure
+ the concrete log system (system properties for commons,
+ log4j.properties or logging.properties for commons, log4j and jdk
+ respectively) Look at the configuration examples below.</para>
+ </listitem>
+
+ <listitem>
+ <para><firstterm>logger</firstterm> - an implementation of
+ commons-logging Log interface. It is possible to use commons
+ wrappers but to support buffering required by the log portlet three
+ kinds of loggers were added:
+ <classname>BufferedSimpleLog</classname>,
+ <classname>BufferedLog4JLogger</classname> and
+ <classname>BufferedJdk14Logger</classname> (they contain BufferedLog
+ and extend SimpleLog, Log4JLogger and Jdk14Logger commons-logging
+ wrappers respectively).</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Configuration examples</title>
+
+ <section>
+ <title>Log4J</title>
+
+ <para><ulink url="http://logging.apache.org/log4j/">Log4J</ulink> is a
+ very popular and flexible logging system. It is a good option for
+ JBoss.<programlisting> <component>
+ <type>org.exoplatform.services.log.LogConfigurationInitializer</type>
+ <init-params>
+ <value-param>
+ <name>logger</name>
+ <value>org.exoplatform.services.log.impl.BufferedLog4JLogger</value>
+ </value-param>
+ <value-param>
+ <name>configurator</name>
+ <value>org.exoplatform.services.log.impl.Log4JConfigurator</value>
+ </value-param>
+ <properties-param>
+ <name>properties</name>
+ <description>Log4J properties</description>
+ <property name="log4j.rootLogger" value="DEBUG, stdout, file"/>
+ <property name="log4j.appender.stdout" value="org.apache.log4j.ConsoleAppender"/>
+ <property name="log4j.appender.stdout.layout" value="org.apache.log4j.PatternLayout"/>
+ <property name="log4j.appender.stdout.layout.ConversionPattern" value="%d {dd.MM.yyyy HH:mm:ss} %c {1}: %m (%F, line %L) %n"/>
+ <property name="log4j.appender.file" value="org.apache.log4j.FileAppender"/>
+ <property name="log4j.appender.file.File" value="jcr.log"/>
+ <property name="log4j.appender.file.layout" value="org.apache.log4j.PatternLayout"/>
+ <property name="log4j.appender.file.layout.ConversionPattern" value="%d{dd.MM.yyyy HH:mm:ss} %m (%F, line %L) %n"/>
+ </properties-param >
+ </init-params>
+ </component></programlisting></para>
+
+ <section>
+ <title>Assigning logger level for classes or components</title>
+
+ <para>You can set logger level for class or group of classes by
+ setting next property:<programlisting><property name="log4j.category.{component or class name}" value="DEBUG"/></programlisting></para>
+
+ <para>For example:<itemizedlist>
+ <listitem>
+ <para>we want log all debug messages for class
+ <classname>org.exoplatform.services.jcr.impl.core.SessionDataManager</classname>,
+ that lies in <package>exo.jcr.component.core</package>
+ component<programlisting><property name="log4j.category.exo.jcr.component.core.SessionDataManager" value="DEBUG"/></programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>or we want log all debug messages for all classes in in
+ <package>exo.jcr.component.core</package>
+ component<programlisting><property name="log4j.category.exo.jcr.component.core" value="DEBUG"/></programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>or we want log all messages for all kernel
+ components<programlisting><property name="log4j.category.exo.kernel" value="DEBUG"/></programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ </section>
+
+ <section>
+ <title>JDK Logging</title>
+
+ <para>JDK logging (aka JUL) is the builtin logging framework introduced
+ in JDK 1.4. It is a good option for Tomcat AS.<itemizedlist>
+ <listitem>
+ <para>edit the variable <varname>LOG_OPTS</varname> in your
+ <filename>eXo.sh</filename> or <filename>eXo.bat</filename>
+ :<programlisting>LOG_OPTS="-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger"</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Edit your <filename>logs-configuration.xml</filename>
+ :<programlisting><component>
+ <type>org.exoplatform.services.log.LogConfigurationInitializer</type>
+ <init-params>
+ <value-param>
+ <name>logger</name>
+ <value>org.exoplatform.services.log.impl.BufferedJdk14Logger</value>
+ </value-param>
+ <value-param>
+ <name>configurator</name>
+ <value>org.exoplatform.services.log.impl.Jdk14Configurator</value>
+ </value-param>
+ <properties-param>
+ <name>properties</name>
+ <description>jdk1.4 Logger properties</description>
+ <property name="handlers" value="java.util.logging.ConsoleHandler"/>
+ <property name=".level" value="FINE"/>
+ <property name="java.util.logging.ConsoleHandler.level" value="FINE"/>
+ </properties-param>
+ </init-params>
+ </component></programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Commons Logging SimpleLog</title>
+
+ <para>SimpleLog is a minimal logging system distributed with Commons
+ Logging. To be used when nothing else is available or when you seek
+ simplicity.<programlisting> <component>
+ <type>org.exoplatform.services.log.LogConfigurationInitializer</type>
+ <init-params>
+ <value-param>
+ <name>logger</name>
+ <value>org.exoplatform.services.log.impl.BufferedSimpleLog</value>
+ </value-param>
+ <value-param>
+ <name>configurator</name>
+ <value>org.exoplatform.services.log.impl.SimpleLogConfigurator</value>
+ </value-param>
+ <properties-param>
+ <name>properties</name>
+ <description>SimpleLog properties</description>
+ <property name="org.apache.commons.logging.simplelog.defaultlog" value="debug"/>
+ <property name="org.apache.commons.logging.simplelog.showdatetime" value="true"/>
+ </properties-param>
+ </init-params>
+ </component></programlisting></para>
+ </section>
+ </section>
+
+ <section>
+ <title>Tips and Troubleshooting</title>
+
+ <section>
+ <title>JBoss tips</title>
+
+ <para>If you use log4j configuration, you can change the log
+ configuration directly at runtime in:
+ <filename>JBOSS_HOME/server/default/conf/jboss-log4j.xml</filename>.<itemizedlist>
+ <listitem>
+ <para>To enable debug logs :<programlisting> <param name="Threshold" value="DEBUG"/> </programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>To exclude messages from unnecessary classes (server's
+ internal) modify the threshold of these classes to "FATAL".</para>
+ </listitem>
+ </itemizedlist><tip>
+ <para>If you see only ERROR level logs while starting ear on jboss
+ (4.2.2), you have to remove log4j*.jar from your ear and
+ application.xml.</para>
+ </tip></para>
+ </section>
+
+ <section>
+ <title>Other tips</title>
+
+ <para>If you see only ERROR level logs while starting ear on jboss
+ (4.2.2), you have to remove log4j*.jar from your ear and
+ application.xml.</para>
+ </section>
+ </section>
+</chapter>
Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml
===================================================================
--- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml 2010-03-26 13:00:58 UTC (rev 2166)
+++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml 2010-03-26 13:04:08 UTC (rev 2167)
@@ -8,7 +8,7 @@
<xi:include href="kernel/kernel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
-
+
<xi:include href="kernel/configuration.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -17,8 +17,11 @@
<xi:include href="kernel/transaction-service.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
-
+
<xi:include href="kernel/jndi-naming.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
-
+
+ <xi:include href="kernel/logging.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
</part>
More information about the exo-jcr-commits
mailing list