Author: smumford Date: 2010-05-19 03:47:16 -0400 (Wed, 19 May 2010) New Revision: 3122 Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/lock-manager-config.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/query-handler-config.xml Log: JBEPP-276: Continuing edits to JCR section. Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/lock-manager-config.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/lock-manager-config.xml 2010-05-19 07:37:40 UTC (rev 3121) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/lock-manager-config.xml 2010-05-19 07:47:16 UTC (rev 3122) @@ -7,175 +7,216 @@ <title>LockManager</title> <para> - In common words, LockManager stores lock objects, so it can give Lock object or can release it, etc. + The LockManager stores lock objects. It can lock or release objects as required. It is also responsible for removing stale locks. </para> <para> - Also LockManager is responsible for removing Locks that live too long. This parameter may be configured with "time-out" property. + The length of time LockManager allows a lock to remain in place can be configured with the "<literal>time-out</literal>" property. </para> <para> - JCR provide two base implementation of LockManager: + JCR provides two base implementations of the LockManager: </para> - <itemizedlist> + <orderedlist> <listitem> <para> <classname>org.exoplatform.services.jcr.impl.core.lock.LockManagerImpl</classname>; </para> </listitem> <listitem> - <para> - <classname>org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl</classname>; + <para> <classname>org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl</classname>; </para> </listitem> - </itemizedlist> + </orderedlist> <para> - In this article we will talk mostly about CacheableLockManagerImpl. + <classname>LockManagerImpl</classname> is simple implementation of LockManager which is faster than <classname>CacheableLockManager</classname>. It stores lock objects in HashMap and can retain persistant locks if the <literal>LockPersister</literal> is configured. </para> <para> - You can enable LockManager by adding lock-manager-configuration to workspace-configuration. + However, <classname>LockManagerImpl</classname> does not support replication. </para> + <para> + The second implementation (<classname>CacheableLockManagerImpl</classname>) will be the primary focus of this section. + </para> + + <para> + LockManager is enabled by adding <literal>lock-manager-configuration</literal> to <literal>workspace-configuration</literal>. + </para> + <para> For example: </para> -<programlisting>&lt;workspace name="ws"&gt; +<programlisting language="XML" role="XML"><![CDATA[<workspace name="ws"> ... - &lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; - &lt;properties&gt; - &lt;property name="time-out" value="15m" /&gt; + <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"> + <properties> + <property name="time-out" value="15m" /> ... - &lt;/properties&gt; - &lt;/lock-manager&gt; + </properties> + </lock-manager> ... -&lt;/workspace&gt; -</programlisting> +</workspace>]]></programlisting> - <section id="sect-Reference_Guide-LockManager_configuration-LockManagerImpl"> - <title>LockManagerImpl</title> - <para> - LockManagerImpl is simple implementation of LockManager, and also faster than CacheableLockManager. It stores Lock objects in HashMap and may also persist Locks if LockPersister is configured. LockManagerImpl do not support replication in any way. - </para> - <para> - See more about LockManager Configuration in <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/>. - </para> - </section> <section id="sect-Reference_Guide-LockManager_configuration-CacheableLockManagerImpl"> <title>CacheableLockManagerImpl</title> <para> - CacheableLockManagerImpl stores Lock object in JBoss-cache, so Locks are replicable and affects on cluster, not only a single node. Also JBoss-cache has JDBCCacheLoader, so locks will be stored to database. + <classname>CacheableLockManagerImpl</classname> stores lock objects in JBoss-cache (which implements JDBCCacheLoader to store locks in a database). This means its locks are replicable and can affect an entire cluster rather than just a single node. </para> <para> - Both implementation supports Expired Locks removing. There is LockRemover - separate thread, that periodically ask LockManager for Locks that lives to much and must be removed. So, timeout for LockRemover may be set as follows, default value is 30m. + Both implementations support the removal of expired locks. The LockRemover thread periodically polls LockManager for locks that have passed the time-out limit and must be removed. </para> - -<programlisting>&lt;properties&gt; - &lt;property name="time-out" value="10m" /&gt; + <para> + The time-out for LockRemover is set as follows (the default value is 30m): + </para> + +<programlisting language="XML" role="XML"><![CDATA[<properties> + <property name="time-out" value="10m" /> ... -&lt;/properties&gt; -</programlisting> +</properties>]]></programlisting> + +<!-- Doesn't seem necessary <formalpara> - <title>Configuration</title> + <title>Configuration</title> <para> Replication requirements are same as for Cache </para> </formalpara> <para> Full JCR configuration example can be seen in <xref linkend="sect-Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster"/>. - </para> - <para> - Common tips: - </para> - <itemizedlist> + </para> + + + <title>Configuration Tips:</title> <listitem> <para> - <parameter>clusterName</parameter> ("jbosscache-cluster-name") must be unique; + The <parameter>clusterName</parameter> ("jbosscache-cluster-name") must be unique; </para> </listitem> <listitem> <para> - <parameter>cache.jdbc.table.name</parameter> must be unique per datasource; + The <parameter>cache.jdbc.table.name</parameter> must be unique per datasource; </para> </listitem> <listitem> <para> - <parameter>cache.jdbc.fqn.type</parameter> must and cache.jdbc.node.type must be configured according to used database; + The <parameter>cache.jdbc.fqn.type</parameter> and <parameter>cache.jdbc.node.type</parameter> paramters must be configured according to the database being used. </para> </listitem> - </itemizedlist> + </itemizedlist>--> + <para> - There is few ways how to configure CacheableLockManagerImpl, and all of them configures JBoss-cache and JDBCCacheLoader. + There are a number of ways to configure <classname>CacheableLockManagerImpl</classname>. Each involves configuring JBoss Cache and JDBCCacheLoader. </para> + + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"/> + </para> + </listitem> + </itemizedlist> <para> - See <ulink url="http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader"... + Refer to <ulink url="http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader"... for more information about JBoss Cache and JDBCCacheLoader. </para> - - <formalpara> - <title>Simple JbossCache Configuraion</title> + + + <section id="sect-Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration"> + <title>Simple Jboss Cache Configuration</title> <para> - First one is - put JbossCache configuraion file path to CacheableLockManagerImpl + One method to configure the LockManager is to put a JBoss Cache configuration file path into <classname>CacheableLockManagerImpl</classname>. </para> - </formalpara> + + <note> + <para> + This is not the most efficient method for configuring the LockManager as it requires a JBoss Cache configuration file for each LockManager configuration in each workspace of each repository. The configuration set up can subsequently become quite difficult to manage. + </para> + <para> + This method is useful, however, if a single, specially configured LockManager is required. + </para> + </note> + <para> - <note> - <para> - This configuration is not so good, as you can think. Because repository may contain many workspaces, and each workspace must contain LockManager configuration, and LockManager config may contain JbossCache config file. So total configuration is growing up. But it is usefull if we want a single LockManager with special configuration. - </para> - </note> + The required configuration is shown in the example below: </para> + <programlistingco> + <areaspec> + <area coords="4" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration-test-jbosscache-lock-config.xml"/> + </areaspec> + +<programlisting language="XML" role="XML"><![CDATA[<lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"> + <properties> + <property name="time-out" value="15m" /> + <property name="jbosscache-configuration" value="conf/standalone/cluster/test-jbosscache-lock-config.xml" /> + </properties> +</lock-manager>]]></programlisting> + + <calloutlist> + <callout arearefs="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration-test-jbosscache-lock-config.xml"> + <para> + The <replaceable>test-jbosscache-lock-config.xml</replaceable> is shown below. + </para> + </callout> + </calloutlist> + </programlistingco> + <para> - Config is: + The <filename>test-jbosscache-lock-config.xml</filename> file: </para> + <programlistingco> + <areaspec> + <area coords="5" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration-clusterName"/> + <area coords="42" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration-cache.jdbc.table.name"/> + <areaset coords="" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration-cache.jdbc.types"> + <area coords="49" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration-cache.jdbc.node.type"/> + <area coords="46" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration-cache.jdbc.fqn.type"/> + </areaset> + </areaspec> -<programlisting>&lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; - &lt;properties&gt; - &lt;property name="time-out" value="15m" /&gt; - &lt;property name="jbosscache-configuration" value="conf/standalone/cluster/test-jbosscache-lock-config.xml" /&gt; - &lt;/properties&gt; -&lt;/lock-manager&gt; -</programlisting> - <para> - <filename>test-jbosscache-lock-config.xml</filename> -<programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.2"&gt; +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.2"> - &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" lockAcquisitionTimeout="20000" /&gt; + <locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" lockAcquisitionTimeout="20000" /> - &lt;clustering mode="replication" clusterName="JBoss-Cache-Lock-Cluster_Name"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" nonBlocking="true" /&gt; - &lt;jgroupsConfig&gt; + <clustering mode="replication" clusterName="JBoss-Cache-Lock-Cluster_Name"> + <stateRetrieval timeout="20000" fetchInMemoryState="false" nonBlocking="true" /> + <jgroupsConfig> - &lt;TCP bind_addr="127.0.0.1" start_port="9800" loopback="true" recv_buf_size="20000000" send_buf_size="640000" discard_incompatible_packets="true" + <TCP bind_addr="127.0.0.1" start_port="9800" loopback="true" recv_buf_size="20000000" send_buf_size="640000" discard_incompatible_packets="true" max_bundle_size="64000" max_bundle_timeout="30" use_incoming_packet_handler="true" enable_bundling="false" use_send_queues="false" sock_conn_timeout="300" skip_suspected_members="true" use_concurrent_stack="true" thread_pool.enabled="true" thread_pool.min_threads="1" thread_pool.max_threads="25" thread_pool.keep_alive_time="5000" thread_pool.queue_enabled="false" thread_pool.queue_max_size="100" thread_pool.rejection_policy="run" oob_thread_pool.enabled="true" oob_thread_pool.min_threads="1" oob_thread_pool.max_threads="8" oob_thread_pool.keep_alive_time="5000" - oob_thread_pool.queue_enabled="false" oob_thread_pool.queue_max_size="100" oob_thread_pool.rejection_policy="run" /&gt; - &lt;MPING timeout="2000" num_initial_members="2" mcast_port="34540" bind_addr="127.0.0.1" mcast_addr="224.0.0.1" /&gt; + oob_thread_pool.queue_enabled="false" oob_thread_pool.queue_max_size="100" oob_thread_pool.rejection_policy="run" /> + <MPING timeout="2000" num_initial_members="2" mcast_port="34540" bind_addr="127.0.0.1" mcast_addr="224.0.0.1" /> - &lt;MERGE2 max_interval="30000" min_interval="10000" /&gt; - &lt;FD_SOCK /&gt; - &lt;FD max_tries="5" shun="true" timeout="10000" /&gt; - &lt;VERIFY_SUSPECT timeout="1500" /&gt; - &lt;pbcast.NAKACK discard_delivered_msgs="true" gc_lag="0" retransmit_timeout="300,600,1200,2400,4800" use_mcast_xmit="false" /&gt; - &lt;UNICAST timeout="300,600,1200,2400,3600" /&gt; - &lt;pbcast.STABLE desired_avg_gossip="50000" max_bytes="400000" stability_delay="1000" /&gt; - &lt;pbcast.GMS join_timeout="5000" print_local_addr="true" shun="false" view_ack_collection_timeout="5000" view_bundling="true" /&gt; - &lt;FRAG2 frag_size="60000" /&gt; - &lt;pbcast.STREAMING_STATE_TRANSFER /&gt; - &lt;pbcast.FLUSH timeout="0" /&gt; + <MERGE2 max_interval="30000" min_interval="10000" /> + <FD_SOCK /> + <FD max_tries="5" shun="true" timeout="10000" /> + <VERIFY_SUSPECT timeout="1500" /> + <pbcast.NAKACK discard_delivered_msgs="true" gc_lag="0" retransmit_timeout="300,600,1200,2400,4800" use_mcast_xmit="false" /> + <UNICAST timeout="300,600,1200,2400,3600" /> + <pbcast.STABLE desired_avg_gossip="50000" max_bytes="400000" stability_delay="1000" /> + <pbcast.GMS join_timeout="5000" print_local_addr="true" shun="false" view_ack_collection_timeout="5000" view_bundling="true" /> + <FRAG2 frag_size="60000" /> + <pbcast.STREAMING_STATE_TRANSFER /> + <pbcast.FLUSH timeout="0" /> - &lt;/jgroupsConfig + </jgroupsConfig - &lt;sync /&gt; - &lt;/clustering&gt; + <sync /> + </clustering> - &lt;loaders passivation="false" shared="true"&gt; - &lt;preload&gt; - &lt;node fqn="/" /&gt; - &lt;/preload&gt; - &lt;loader class="org.jboss.cache.loader.JDBCCacheLoader" async="false" fetchPersistentState="false" ignoreModifications="false" purgeOnStartup="false"&gt; - &lt;properties&gt; + <loaders passivation="false" shared="true"> + <preload> + <node fqn="/" /> + </preload> + <loader class="org.jboss.cache.loader.JDBCCacheLoader" async="false" fetchPersistentState="false" ignoreModifications="false" purgeOnStartup="false"> + <properties> cache.jdbc.table.name=jcrlocks_ws cache.jdbc.table.create=true cache.jdbc.table.drop=false @@ -183,167 +224,38 @@ cache.jdbc.fqn.column=fqn cache.jdbc.fqn.type=VARCHAR(512) cache.jdbc.node.column=node - cache.jdbc.node.type=&lt;BLOB&gt; + cache.jdbc.node.type=<BLOB> cache.jdbc.parent.column=parent cache.jdbc.datasource=jdbcjcr - &lt;/properties&gt; - &lt;/loader&gt; + </properties> + </loader> - &lt;/loaders&gt; + </loaders> -&lt;/jbosscache&gt; -</programlisting> - </para> - <para> - Configuration requirements: - </para> - <itemizedlist> - <listitem> - <para> - &lt;clustering mode="replication" clusterName="JBoss-Cache-Lock-Cluster_Name"&gt; - cluster name must be unique; - </para> - </listitem> - <listitem> - <para> - <parameter>cache.jdbc.table.name</parameter> must be unique per datasource; - </para> - </listitem> - <listitem> - <para> - <parameter>cache.jdbc.node.type</parameter> and <parameter>cache.jdbc.fqn.type</parameter> must be configured according to using database. See <xref linkend="tabl-Reference_Guide-Data_Types_in_Different_Databases-Fqn_type_and_node_type_in_different_databases"/>. - </para> - </listitem> - </itemizedlist> - - <formalpara> - <title>Template JBossCache Configuration</title> - <para> - Second one is - use template JBoss-cache configuration for all LockManagers - </para> - </formalpara> - <para> - <citetitle>Lock template configuration</citetitle> - </para> - <para> - <filename>test-jbosscache-lock.xml</filename> - </para> - -<programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; +</jbosscache>]]></programlisting> - &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" - lockAcquisitionTimeout="20000" /&gt; - - &lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; - &lt;jgroupsConfig multiplexerStack="jcr.stack" /&gt; - &lt;sync /&gt; - &lt;/clustering&gt; - - &lt;loaders passivation="false" shared="true"&gt; - &lt;!-- All the data of the JCR locks needs to be loaded at startup --&gt; - &lt;preload&gt; - &lt;node fqn="/" /&gt; - &lt;/preload&gt; - &lt;!-- - For another cache-loader class you should use another template with - cache-loader specific parameters - -&gt; - &lt;loader class="org.jboss.cache.loader.JDBCCacheLoader" async=q"false" fetchPersistentState="false" - ignoreModifications="false" purgeOnStartup="false"&gt; - &lt;properties&gt; - cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name} - cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create} - cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop} - cache.jdbc.table.primarykey=${jbosscache-cl-cache.jdbc.table.primarykey} - cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column} - cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type} - cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column} - cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type} - cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column} - cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource} - &lt;/properties&gt; - &lt;/loader&gt; - &lt;/loaders&gt; -&lt;/jbosscache&gt; -</programlisting> - <para> - As you see, all configurable paramaters filled by templates and will be replaced by LockManagers conf parameters: - </para> -<programlisting>&lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; - &lt;properties&gt; - &lt;property name="time-out" value="15m" /&gt; - &lt;property name="jbosscache-configuration" value="test-jbosscache-lock.xml" /&gt; - &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="JCR-cluster-locks-ws" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_ws" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.create" value="true" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.drop" value="false" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_ws_pk" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.fqn.type" value="AUTO"/&gt; - &lt;property name="jbosscache-cl-cache.jdbc.node.column" value="node" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.node.type" value="AUTO"/&gt; - &lt;property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" /&gt; - &lt;/properties&gt; -&lt;/lock-manager&gt; -</programlisting> - <para> - Configuration requirements: - <itemizedlist> - <listitem> + <calloutlist> + <callout arearefs="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration-clusterName"> <para> - <parameter>jbosscache-cl-cache.jdbc.fqn.column</parameter> and <parameter>jbosscache-cl-cache.jdbc.node.type</parameter> is nothing else as cache.jdbc.fqn.type and cache.jdbc.node.type in JBoss-Cache configuration. You can set those data types according to database type (See <xref linkend="tabl-Reference_Guide-Data_Types_in_Different_Databases-Fqn_type_and_node_type_in_different_databases"/>) or set it as AUTO (or do not set at all) and data type will by detected automaticaly. + The cluster name at <parameter>clustering mode="replication" clusterName="JBoss-Cache-Lock-Cluster_Name"</parameter> must be unique; </para> - </listitem> - <listitem> + </callout> + <callout arearefs="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration-cache.jdbc.table.name"> <para> - as you see, jgroups-configuration moved to separate config file - udp-mux.xml; In our case udp-mux.xml is common JGroup config for all components (QueryHandler, cache, LockManager). But we, still, can create own config. + The <parameter>cache.jdbc.table.name</parameter> must be unique per datasource. </para> - </listitem> - </itemizedlist> - </para> - <para> - <filename>our-udp-mux.xml</filename> -<programlisting>&lt;protocol_stacks&gt; - &lt;stack name="jcr.stack"&gt; - &lt;config&gt; - &lt;UDP mcast_addr="228.10.10.10" mcast_port="45588" tos="8" ucast_recv_buf_size="20000000" - ucast_send_buf_size="640000" mcast_recv_buf_size="25000000" mcast_send_buf_size="640000" loopback="false" - discard_incompatible_packets="true" max_bundle_size="64000" max_bundle_timeout="30" - use_incoming_packet_handler="true" ip_ttl="2" enable_bundling="true" enable_diagnostics="true" - thread_naming_pattern="cl" use_concurrent_stack="true" thread_pool.enabled="true" thread_pool.min_threads="2" - thread_pool.max_threads="8" thread_pool.keep_alive_time="5000" thread_pool.queue_enabled="true" - thread_pool.queue_max_size="1000" thread_pool.rejection_policy="discard" oob_thread_pool.enabled="true" - oob_thread_pool.min_threads="1" oob_thread_pool.max_threads="8" oob_thread_pool.keep_alive_time="5000" - oob_thread_pool.queue_enabled="false" oob_thread_pool.queue_max_size="100" oob_thread_pool.rejection_policy="Run" /&gt; - - &lt;PING timeout="2000" num_initial_members="3" /&gt; - &lt;MERGE2 max_interval="30000" min_interval="10000" /&gt; - &lt;FD_SOCK /&gt; - &lt;FD timeout="10000" max_tries="5" shun="true" /&gt; - &lt;VERIFY_SUSPECT timeout="1500" /&gt; - &lt;BARRIER /&gt; - &lt;pbcast.NAKACK use_stats_for_retransmission="false" exponential_backoff="150" use_mcast_xmit="true" - gc_lag="0" retransmit_timeout="50,300,600,1200" discard_delivered_msgs="true" /&gt; - &lt;UNICAST timeout="300,600,1200" /&gt; - &lt;pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000" max_bytes="1000000" /&gt; - &lt;VIEW_SYNC avg_send_interval="60000" /&gt; - &lt;pbcast.GMS print_local_addr="true" join_timeout="3000" shun="false" view_bundling="true" /&gt; - &lt;FC max_credits="500000" min_threshold="0.20" /&gt; - &lt;FRAG2 frag_size="60000" /&gt; - &lt;!--pbcast.STREAMING_STATE_TRANSFER /--&gt; - &lt;pbcast.STATE_TRANSFER /&gt; - &lt;!-- pbcast.FLUSH /--&gt; - &lt;/config&gt; - &lt;/stack&gt; -&lt;/protocol_stacks&gt; -</programlisting> - </para> - + </callout> + <callout arearefs="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration-cache.jdbc.types"> + <para> + The <parameter>cache.jdbc.node.type</parameter> and <parameter>cache.jdbc.fqn.type</parameter> parameters must be configured according to the database in use. + </para> + <para> + Refer to the table below for information about data types. + </para> + </callout> + </calloutlist> + </programlistingco> <table id="tabl-Reference_Guide-Data_Types_in_Different_Databases-Fqn_type_and_node_type_in_different_databases"> <title>Data Types in Different Databases</title> <tgroup cols="3"> @@ -463,6 +375,164 @@ </tbody> </tgroup> </table> + + </section> + + <section id="sect-Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"> + <title>Template JBoss Cache Configuration</title> + <para> + Another method to configure LockManager is to use a JBoss Cache configuration template for all LockManagers. + </para> + <para> + Below is an example <filename>test-jbosscache-lock.xml</filename> template file: + </para> + <programlistingco> + <areaspec> + <areaset coords="" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.templates"> + <area coords="24" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.table.name"/> + <area coords="34" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.datasource"/> + </areaset> + </areaspec> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"> + + <locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" + lockAcquisitionTimeout="20000" /> + + <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> + <stateRetrieval timeout="20000" fetchInMemoryState="false" /> + <jgroupsConfig multiplexerStack="jcr.stack" /> + <sync /> + </clustering> + + <loaders passivation="false" shared="true"> + <!-- All the data of the JCR locks needs to be loaded at startup --> + <preload> + <node fqn="/" /> + </preload> + <!-- + For another cache-loader class you should use another template with + cache-loader specific parameters + --> + <loader class="org.jboss.cache.loader.JDBCCacheLoader" async=q"false" fetchPersistentState="false" + ignoreModifications="false" purgeOnStartup="false"> + <properties> + cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name} + cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create} + cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop} + cache.jdbc.table.primarykey=${jbosscache-cl-cache.jdbc.table.primarykey} + cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column} + cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type} + cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column} + cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type} + cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column} + cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource} + </properties> + </loader> + </loaders> +</jbosscache>]]></programlisting> + + <calloutlist> + <callout arearefs="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.templates"> + <para> + All the configurable parameters in this file are populated with templates which will be replaced with LockManager's configuration parameters. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + The parameters that will populate the above file are shown below: + </para> + <programlistingco> + <areaspec> + <areaset coords="" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.parameters"> + <area coords="12" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.fqn.column"/> + <area coords="15" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.node.type"/> + </areaset> + <area coords="5" id="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-udp-mux.xml"/> + </areaspec> + +<programlisting language="XML" role="XML"><![CDATA[<lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"> + <properties> + <property name="time-out" value="15m" /> + <property name="jbosscache-configuration" value="test-jbosscache-lock.xml" /> + <property name="jgroups-configuration" value="udp-mux.xml" /> + <property name="jgroups-multiplexer-stack" value="true" /> + <property name="jbosscache-cluster-name" value="JCR-cluster-locks-ws" /> + <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_ws" /> + <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_ws_pk" /> + <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" /> + <property name="jbosscache-cl-cache.jdbc.fqn.type" value="AUTO"/> + <property name="jbosscache-cl-cache.jdbc.node.column" value="node" /> + <property name="jbosscache-cl-cache.jdbc.node.type" value="AUTO"/> + <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" /> + <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" /> + </properties> +</lock-manager>]]></programlisting> + + <calloutlist> + <callout arearefs="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.parameters"> + <para> + The <parameter>jbosscache-cl-cache.jdbc.fqn.column</parameter> and <parameter>jbosscache-cl-cache.jdbc.node.type</parameter> parameters are not explicitly defined as <parameter>cache.jdbc.fqn.type</parameter> and <parameter>cache.jdbc.node.type</parameter> are defined in the JBoss Cache configuration. + </para> + <para> + Refer to <xref linkend="tabl-Reference_Guide-Data_Types_in_Different_Databases-Fqn_type_and_node_type_in_different_databases"/> for information about setting these parameters or set them as <parameter>AUTO</parameter> and the data type will by detected automatically. + </para> + </callout> + <callout arearefs="Reference_Guide-LockManager_configuration-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-udp-mux.xml"> + <para> + The <literal>jgroups-configuration</literal> has been moved to a separate configuration file (<filename>udp-mux.xml</filename>, shown below). + </para> + <para> + In this case the <filename>udp-mux.xml</filename> is a common configuration for all JGroup components (QueryHandler, cache, LockManager), but this is not a requirement of the configuration method. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + <filename>udp-mux.xml</filename>: + </para> + +<programlisting language="XML" role="XML"><![CDATA[<protocol_stacks> + <stack name="jcr.stack"> + <config> + <UDP mcast_addr="228.10.10.10" mcast_port="45588" tos="8" ucast_recv_buf_size="20000000" + ucast_send_buf_size="640000" mcast_recv_buf_size="25000000" mcast_send_buf_size="640000" loopback="false" + discard_incompatible_packets="true" max_bundle_size="64000" max_bundle_timeout="30" + use_incoming_packet_handler="true" ip_ttl="2" enable_bundling="true" enable_diagnostics="true" + thread_naming_pattern="cl" use_concurrent_stack="true" thread_pool.enabled="true" thread_pool.min_threads="2" + thread_pool.max_threads="8" thread_pool.keep_alive_time="5000" thread_pool.queue_enabled="true" + thread_pool.queue_max_size="1000" thread_pool.rejection_policy="discard" oob_thread_pool.enabled="true" + oob_thread_pool.min_threads="1" oob_thread_pool.max_threads="8" oob_thread_pool.keep_alive_time="5000" + oob_thread_pool.queue_enabled="false" oob_thread_pool.queue_max_size="100" oob_thread_pool.rejection_policy="Run" /> + + <PING timeout="2000" num_initial_members="3" /> + <MERGE2 max_interval="30000" min_interval="10000" /> + <FD_SOCK /> + <FD timeout="10000" max_tries="5" shun="true" /> + <VERIFY_SUSPECT timeout="1500" /> + <BARRIER /> + <pbcast.NAKACK use_stats_for_retransmission="false" exponential_backoff="150" use_mcast_xmit="true" + gc_lag="0" retransmit_timeout="50,300,600,1200" discard_delivered_msgs="true" /> + <UNICAST timeout="300,600,1200" /> + <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000" max_bytes="1000000" /> + <VIEW_SYNC avg_send_interval="60000" /> + <pbcast.GMS print_local_addr="true" join_timeout="3000" shun="false" view_bundling="true" /> + <FC max_credits="500000" min_threshold="0.20" /> + <FRAG2 frag_size="60000" /> + <!--pbcast.STREAMING_STATE_TRANSFER /--> + <pbcast.STATE_TRANSFER /> + <!-- pbcast.FLUSH /--> + </config> + </stack> +</protocol_stacks>]]></programlisting> + + </section> </section> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/query-handler-config.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/query-handler-config.xml 2010-05-19 07:37:40 UTC (rev 3121) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/query-handler-config.xml 2010-05-19 07:47:16 UTC (rev 3122) @@ -6,165 +6,139 @@ <section id="sect-Reference_Guide-QueryHandler_configuration"> <title>QueryHandler configuration</title> <para> - Lets talk about indexing content in cluster. + Indexing content in a cluster can be problematic as indexes cannot be replicated across nodes. Data present and indexed on one node will not be indexed if it is replicated to another. </para> + <para> - For couple of reasons, we can't replicate index. That's means, some data added and indexed on one cluster node, will be replicated to another cluster node, but will not be indexed on that node. + This problem can be overcome with the use of a <emphasis>coordinator-node</emphasis>. A coordinator-node can maintain a Lucene index of the data on a cluster. </para> <para> - <citetitle>So, how do the indexing works in cluster environment?</citetitle> + The coordinator-node is chosen automatically, so there is no need for any special configuration. </para> <para> - As, we can not index same data on all nodes of cluster, we must index it on one node. Node, that can index data and do changes on lucene index, is called "coordinator". Coordinator-node is choosen automaticaly, so we do not need special configuration for coordinator. + Other nodes in the cluster deliver indexing request messages to JBoss Cache. The coordinator retrieves those messages and updates the index accordingly. </para> <para> - But, how can another nodes save their changes to lucene index? + Searching data on a cluster can be likewise problematic, as search engines are unable to work with the index/coordinator model proposed above. Therefore each node in the cluster must be configured to access the Lucene index from a shared directory. However the coordinator reserves the ability to edit that index. </para> + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/Advanced/JCR/diagram-shared-index.png" format="PNG" align="center" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/Advanced/JCR/diagram-shared-index.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> + </mediaobject> + <para> - First of all, data is already saved and replicated to another cluster-nodes, so we need only deliver message like "we need to index this data" to coordinator. Thats why Jboss-cache is used. + Regardless of whether they are running in a clustered environment or not, Indexers do not writes changes to the file system Lucene index immediately. The data is written to a volatile index first. </para> <para> - All nodes of cluster writes messages into JBoss-cache but only coordinator takes those messages and makes changes Lucene index. + If (or when) the volatile index size reaches or exceeds 1 Mb it is flushed to the shared file system index. Volatile indexes can also be flushed after a given time. The volatile index time out is configured with the "<parameter>max-volatile-time</parameter>" parameter. </para> <para> - <citetitle>How do the search works in cluster environment?</citetitle> + Refer to <xref linkend="sect-Reference_Guide-Search_Configuration"/> for more information. </para> - <para> - Search engine do not works with indexer, coordinator, etc. Search needs only lucene index. But only one cluster node can change lucene index - asking you. Yes - lucene index is shared. So, all cluster nodes must be configured to use lucene index from shared directory. - </para> - <para> - A little bit about indexing process (no matter, cluster or not) Indexer do not writes changes to FS lucene index immediately. At first, Indexer writes changes to Volatile index. If Volatile index size become 1Mb or more it is flushed to FS. Also there is timer, that flushes volatile index by timeout. Volatile index timeout configured by "max-volatile-time" paremeter. - </para> - <para> - See more in <xref linkend="sect-Reference_Guide-Search_Configuration"/>. - </para> - <para> - Common scheme of Shared Index - <mediaobject> - <imageobject> - <imagedata fileref="images/Advanced/JCR/diagram-shared-index.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - </para> + <section id="sect-Reference_Guide-QueryHandler_configuration-Configuration"> <title>Configuration</title> <formalpara> <title>Common requirements</title> <para> - Now, lets see what we need to run Search engine in cluster environment. + The following requirements must be met to run a search engine in clustered environment: </para> </formalpara> - <itemizedlist> + <orderedlist> <listitem> <para> - shared directory for storing Lucene index (i.e. NFS); + A shared directory for storing the Lucene index (an NFS mounted directory, for example); </para> </listitem> <listitem> <para> - changes filter configured as org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter; + A JBoss Cache changes filter configured as <parameter>org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter</parameter>: </para> <note> <para> - This filter ignore changes on non-coordinator nodes, and index changes on coordinator node. + This filter ignores changes on non-coordinator nodes and indexes changes on the coordinator node. </para> </note> </listitem> <listitem> <para> - configure JBoss-cache, course; + A correctly configured instance of JBoss Cache; </para> </listitem> - </itemizedlist> + </orderedlist> <formalpara> <title>Query-handler configuration</title> <para> - Configuration example: + An example configuration </para> </formalpara> -<programlisting>&lt;workspace name="ws"&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="shareddir/index/db1/ws" /&gt; - &lt;property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /&gt; - &lt;property name="jbosscache-configuration" value="jbosscache-indexer.xml" /&gt; - &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /&gt; - &lt;property name="max-volatile-time" value="60" /&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; -&lt;/workspace&gt; -</programlisting> - <table id="tabl-Reference_Guide-Query_handler_configuration-Config_properties_description"> - <title>Config properties description</title> - <tgroup cols="2"> - <thead> - <row> - <entry> - Property name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - index-dir - </entry> - <entry> - path to index - </entry> - </row> - <row> - <entry> - jbosscache-configuration - </entry> - <entry> - template of JBoss-cache configuration for all query-handlers in repository - </entry> - </row> - <row> - <entry> - jgroups-configuration - </entry> - <entry> - jgroups-configuration is template configuration for all components (search, cache, locks) <!--[TODO 5.1 Add link to document describing template configurations] --> - </entry> - </row> - <row> - <entry> - jgroups-multiplexer-stack - </entry> - <entry> - If "jgroups-multiplexer-stack" is true and "jgroups-configuration" parameters are set then Multiplexing stack is enabled in JBossCache. - </entry> - </row> - <row> - <entry> - jbosscache-cluster-name - </entry> - <entry> - cluster name (must be unique) - </entry> - </row> - <row> - <entry> - max-volatile-time - </entry> - <entry> - max time to live for Volatile Index - </entry> - </row> - </tbody> - </tgroup> - </table> + + <programlistingco> + <areaspec> + <area coords="4" id="Reference_Guide-QueryHandler_configuration-Configuration-index-dir"/> + <area coords="8" id="Reference_Guide-QueryHandler_configuration-Configuration-jbosscache-configuration"/> + <area coords="9" id="Reference_Guide-QueryHandler_configuration-Configuration-jgroups-configuration"/> + <area coords="10" id="Reference_Guide-QueryHandler_configuration-Configuration-jgroups-multiplexer-stack"/> + <area coords="11" id="Reference_Guide-QueryHandler_configuration-Configuration-jbosscache-cluster-name"/> + <area coords="12" id="Reference_Guide-QueryHandler_configuration-Configuration-max-volatile-time"/> + </areaspec> +<programlisting language="" role=""><![CDATA[<workspace name="ws"> + <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <properties> + <property name="index-dir" value="shareddir/index/db1/ws" /> + <property name="changesfilter-class" + value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /> + <property name="jbosscache-configuration" value="jbosscache-indexer.xml" /> + <property name="jgroups-configuration" value="udp-mux.xml" /> + <property name="jgroups-multiplexer-stack" value="true" /> + <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /> + <property name="max-volatile-time" value="60" /> + </properties> + </query-handler> +</workspace>]]></programlisting> + + <calloutlist> + <callout arearefs="Reference_Guide-QueryHandler_configuration-Configuration-index-dir"> + <para> + The <parameter>index-dir</parameter> property is the path to the index directory. + </para> + </callout> + <callout arearefs="Reference_Guide-QueryHandler_configuration-Configuration-jbosscache-configuration"> + <para> + The <parameter>jbosscache-configuration</parameter> property is the configuration template for all query-handlers in the repository + </para> + </callout> + <callout arearefs="Reference_Guide-QueryHandler_configuration-Configuration-jgroups-configuration"> + <para> + The <parameter>jgroups-configuration</parameter> property is the configuration template for all components (search, cache, locks). <!--[TODO 5.1 Add link to document describing template configurations] --> + </para> + </callout> + <callout arearefs="Reference_Guide-QueryHandler_configuration-Configuration-jgroups-multiplexer-stack"> + <para> + When the <parameter>jgroups-multiplexer-stack</parameter> property is set to <emphasis>true</emphasis> (and appropriate <parameter>jgroups-configuration</parameter> paramters are set) then Multiplexing stack is enabled in JBoss Cache. + </para> + </callout> + <callout arearefs="Reference_Guide-QueryHandler_configuration-Configuration-jbosscache-cluster-name"> + <para> + The <parameter>jbosscache-cluster-name</parameter> property is the cluster name. This name must be unique. + </para> + </callout> + <callout arearefs="Reference_Guide-QueryHandler_configuration-Configuration-max-volatile-time"> + <para> + The <parameter>max-volatile-time</parameter> property controls the time-out period between volatile index flushes. + </para> + </callout> + + </calloutlist> + </programlistingco> + <formalpara> <title>JBoss-Cache template configuration</title> <para>