Author: smumford Date: 2010-05-18 16:31:43 -0400 (Tue, 18 May 2010) New Revision: 3113 Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/gadgets.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/navigation.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/pages.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/portal.xml Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/cluster-config.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration-persister.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml 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/multilanguage-support.xml 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/search-configuration.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Introduction.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml Log: JBEPP-276:Triage Changes and copy edits. Revert to r3112 if required Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/cluster-config.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/cluster-config.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/cluster-config.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -5,192 +5,212 @@ ]> <section id="sect-Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster"> <title>Configuring JBoss AS with eXo JCR in cluster</title> - <section id="sect-Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster-Launching_Cluster"> - <title>Launching Cluster</title> - <section id="sect-Reference_Guide-Launching_Cluster-Deploying_eXo_JCR_to_JBoss_As"> + <formalpara> <title>Deploying eXo JCR to JBoss As</title> <para> - To deploy eXo JCR to JBoss As follow next steps: + To deploy eXo JCR to JBoss As follow these steps: </para> - <orderedlist> - <listitem> + </formalpara> + <procedure> + <step> <para> - Dowload the latest version of eXo JCR ear distribution. + Dowload the latest version of the eXo JCR <filename>ear</filename> distribution. </para> - </listitem> - <listitem> + </step> + <step> <para> - Copy &lt;jcr.ear&gt; into &lt;%jboss_home%/server/default/deploy&gt; + Copy the <filename>jcr.ear</filename> into <filename>%jboss_home%/server/default/deploy</filename>. </para> - </listitem> - <listitem> + </step> + <step> <para> - Put exo-configuration.xml to the root &lt;%jboss_home%/exo-configuration.xml&gt; + Save the <filename>exo-configuration.xml</filename> into the root <filename>%jboss_home%/exo-configuration.xml</filename>. </para> - </listitem> - <listitem> + </step> + <step> <para> - Configure JAAS by inserting XML fragment shown below into &lt;%jboss_home%/server/default/conf/login-config.xml&gt; + Configure JAAS by inserting the XML fragment shown below into <filename>%jboss_home%/server/default/conf/login-config.xml</filename>. </para> -<programlisting>&lt;application-policy name="exo-domain"&gt; - &lt;authentication&gt; - &lt;login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required"&gt;&lt;/login-module&gt; - &lt;/authentication&gt; -&lt;/application-policy&gt; -</programlisting> - </listitem> - <listitem> +<programlisting language="XML" role="XML"><![CDATA[<application-policy name="exo-domain"> + <authentication> + <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required"></login-module> + </authentication> +</application-policy>]]></programlisting> + + </step> + <step> <para> - Ensure that you use JBossTS <xref linkend="chap-Reference_Guide-eXoJCR"/> and JBossCache <xref linkend="sect-Reference_Guide-JBossTransactionsService"/>. Your exo-configuration.xml must contain such parts: + Ensure that you use JBossTS and JBossCache. See <xref linkend="chap-Reference_Guide-eXoJCR"/> and <xref linkend="sect-Reference_Guide-JBossTransactionsService"/> for more information. </para> + <para> + The <filename>exo-configuration.xml</filename> must contain the following parts: + </para> -<programlisting>&lt;component&gt; - &lt;key&gt;org.jboss.cache.transaction.TransactionManagerLookup&lt;/key&gt; - &lt;type&gt;org.jboss.cache.GenericTransactionManagerLookup&lt;/type&gt;^ -&lt;/component&gt; +<programlisting language="XML" role="XML"><![CDATA[<component> + <key>org.jboss.cache.transaction.TransactionManagerLookup</key> + <type>org.jboss.cache.GenericTransactionManagerLookup</type>^ +</component> -&lt;component&gt; - &lt;key&gt;org.exoplatform.services.transaction.TransactionService&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.transaction.jbosscache.JBossTransactionsService&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;timeout&lt;/name&gt; - &lt;value&gt;300&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; -&lt;/component&gt; -</programlisting> - </listitem> - <listitem> +<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> + </step> + <step> <para> - Start server: + Start the server using <filename>bin/run.sh</filename> for Unix or <filename>bin/run.bat</filename> for Windows systems. </para> - <itemizedlist> - <listitem> - <para> - bin/run.sh for Unix - </para> - </listitem> - <listitem> - <para> - bin/run.bat for Windows - </para> - </listitem> - </itemizedlist> - </listitem> - <listitem> + </step> + <step> <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. + Navigate a web browser to <ulink url="http://localhost:8080/browser">http://localhost:8080/browser</ulink>. This should access to repository browser. </para> - </listitem> - </orderedlist> - </section> - - <section id="sect-Reference_Guide-Launching_Cluster-Configuring_JCR_to_use_external_configuration"> - <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&... Configuration</ulink>. Your configuration must look like: + The default user login and password combination is root/exo. </para> - -<programlisting>&lt;repository-service default-repository="repository1"&gt; - &lt;repositories&gt; - &lt;repository name="repository1" system-workspace="ws1" default-workspace="ws1"&gt; - &lt;security-domain&gt;exo-domain&lt;/security-domain&gt; - &lt;access-control&gt;optional&lt;/access-control&gt; - &lt;authentication-policy&gt;org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator&lt;/authentication-policy&gt; - &lt;workspaces&gt; - &lt;workspace name="ws1"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr" /&gt; - &lt;property name="dialect" value="oracle" /&gt; - &lt;property name="multi-db" value="false" /&gt; - &lt;property name="update-storage" value="false" /&gt; - &lt;property name="max-buffer-size" value="200k" /&gt; - &lt;property name="swap-directory" value="../temp/swap/production" /&gt; - &lt;/properties&gt; - &lt;value-storages&gt; - <emphasis>(See item 1 in the list in <xref linkend="sect-Reference_Guide-Requirements-Environment_requirements"/>)</emphasis> - &lt;/value-storages&gt; - &lt;/container&gt; - &lt;initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"&gt; - &lt;properties&gt; - &lt;property name="root-nodetype" value="nt:unstructured" /&gt; - &lt;/properties&gt; - &lt;/initializer&gt; - &lt;cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"&gt; - <emphasis>(See item 2 in the list in <xref linkend="sect-Reference_Guide-Requirements-Environment_requirements"/>)</emphasis> - &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - <emphasis>(See item 3 in the list in <xref linkend="sect-Reference_Guide-Requirements-Environment_requirements"/>)</emphasis> - &lt;/query-handler&gt; - &lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; - <emphasis>(See item 4 in the list in <xref linkend="sect-Reference_Guide-Requirements-Environment_requirements"/>)</emphasis> - &lt;/lock-manager&gt; - &lt;/workspace&gt; - &lt;workspace name="ws2"&gt; + </step> + </procedure> + + <formalpara> + <title>Configuring JCR to use an external configuration</title> + <para> + To manually configure a repository, create a new configuration file (<filename>exo-jcr-configuration.xml</filename>). + </para> + </formalpara> + <para> + For more information refer to <ulink url="http://wiki.exoplatform.org/xwiki/bin/view/JCR/#HConfiguration&... Configuration</ulink>. + </para> + <para> + The configuration must look like: + </para> + + <programlistingco> + <areaspec> + <area coords="19" id="Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster-value-storages"/> + <area coords="28" id="Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster-cache"/> + <area coords="31" id="Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster-indexer"/> + <area coords="34" id="Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster-lock-manager"/> + </areaspec> + +<programlisting language="XML" role="XML"><![CDATA[<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> + + </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"> + + </cache> + <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + + </query-handler> + <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"> + + </lock-manager> + </workspace> + <workspace name="ws2"> ... - &lt;/workspace&gt; - &lt;workspace name="wsN"&gt; + </workspace> + <workspace name="wsN"> ... - &lt;/workspace&gt; - &lt;/workspaces&gt; - &lt;/repository&gt; - &lt;/repositories&gt; -&lt;/repository-service&gt; -</programlisting> - </listitem> - <listitem> + </workspace> + </workspaces> + </repository> + </repositories> +</repository-service>]]></programlisting> + + <calloutlist> + <callout arearefs="Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster-value-storages"> <para> - and update RepositoryServiceConfiguration configuration in exo-configuration.xml to use this file: -<programlisting>&lt;component&gt; - &lt;key&gt;org.exoplatform.services.jcr.config.RepositoryServiceConfiguration&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;conf-path&lt;/name&gt; - &lt;description&gt;JCR configuration file&lt;/description&gt; - &lt;value&gt;exo-jcr-configuration.xml&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; -&lt;/component&gt; -</programlisting> + Refer to the first item in the list in <xref linkend="sect-Reference_Guide-Requirements-Environment_requirements"/> for more information. </para> - </listitem> - </itemizedlist> - </section> + </callout> + <callout arearefs="Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster-cache"> + <para> + Refer to the second item in the list in <xref linkend="sect-Reference_Guide-Requirements-Environment_requirements"/> for more information. + </para> + </callout> + <callout arearefs="Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster-indexer"> + <para> + Refer to the third item in the list in <xref linkend="sect-Reference_Guide-Requirements-Environment_requirements"/> for more information. + </para> + </callout> + <callout arearefs="Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster-lock-manager"> + <para> + Refer to the fourth item in the list in <xref linkend="sect-Reference_Guide-Requirements-Environment_requirements"/> for more information. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + To update <parameter>RepositoryServiceConfiguration</parameter>, configurate the settings in <filename>exo-configuration.xml</filename> to use the new file: + </para> - </section> - - <section id="sect-Reference_Guide-Configuring_JBoss_AS_with_eXo_JCR_in_cluster-Requirements"> - <title>Requirements</title> - <section id="sect-Reference_Guide-Requirements-Environment_requirements"> - <title>Environment requirements</title> +<programlisting language="XML" role="XML"><![CDATA[<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> + + + <section id="sect-Reference_Guide-Requirements-Environment_requirements"> + <title>Environment requirements</title> <itemizedlist> <listitem> <para> - Every node of cluster MUST have the same mounted Network File System with read and write permissions on it. + Every node in the 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 + Every node of the cluster MUST use the same database. </para> </listitem> <listitem> <para> - Same Clusters on different nodes MUST have the same cluster names (that is; 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" ) + Clusters spanning different nodes MUST have the same cluster names. </para> + <para> + For example; if the <literal>Indexer</literal> cluster on the first node is named "<replaceable>production_indexer_cluster</replaceable>" then indexer clusters on all other nodes must also use the name "<replaceable>production_indexer_cluster</replaceable>". + </para> </listitem> </itemizedlist> <para> - Configuration of every workspace in repository must contains of such parts: + The configuration of every workspace in the repository must contain: </para> <orderedlist> <listitem> @@ -198,79 +218,100 @@ Value Storage configuration: </para> -<programlisting>&lt;value-storages&gt; - &lt;value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; - &lt;properties&gt; - &lt;property name="path" value="/mnt/tornado/temp/values/production" /&gt; &lt;!--path within NFS where ValueStorage will hold it's data--&gt; - &lt;/properties&gt; - &lt;filters&gt; - &lt;filter property-type="Binary" /&gt; - &lt;/filters&gt; - &lt;/value-storage&gt; -&lt;/value-storages&gt; -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[<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="list-Reference_Guide-conf_cache"> <para> Cache configuration: </para> + <programlistingco> + <areaspec> + <area coords="3" id="Reference_Guide-Requirements-Environment_requirements-jboss_cache_config"/> + <area coords="4" id="Reference_Guide-Requirements-Environment_requirements-jgroups_config"/> + <area coords="5" id="Reference_Guide-Requirements-Environment_requirements-cluster_name"/> + </areaspec> -<programlisting>&lt;cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"&gt; - &lt;properties&gt; - &lt;property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-data.xml" /&gt; &lt;!-- path to JBoss Cache configuration for data storage --&gt; - &lt;property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /&gt; &lt;!-- path to JGroups configuration --&gt; - &lt;property name="jbosscache-cluster-name" value="JCR_Cluster_cache_production" /&gt; &lt;!-- JBoss Cache data storage cluster name --&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;/properties&gt; -&lt;/cache&gt; -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[<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" /> + <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> + <property name="jbosscache-cluster-name" value="JCR_Cluster_cache_production" /> + <property name="jgroups-multiplexer-stack" value="true" /> + </properties> +</cache>]]></programlisting> + + <calloutlist> + <callout arearefs="Reference_Guide-Requirements-Environment_requirements-jboss_cache_config"> + <para> + The path to JBoss Cache configuration for data storage. + </para> + </callout> + <callout arearefs="Reference_Guide-Requirements-Environment_requirements-jgroups_config"> + <para> + The path to JGroups configuration. + </para> + </callout> + <callout arearefs="Reference_Guide-Requirements-Environment_requirements-cluster_name"> + <para> + The JBoss Cache data storage cluster name. + </para> + </callout> + </calloutlist> + </programlistingco> + </listitem> <listitem id="list-Reference_Guide-conf_indexer"> <para> Indexer configuration: </para> -<programlisting>&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /&gt; - &lt;property name="index-dir" value="/mnt/tornado/temp/jcrlucenedb/production" /&gt; &lt;!-- path within NFS where ValueStorage will hold it's data --&gt; - &lt;property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-indexer.xml" /&gt; &lt;!-- path to JBoss Cache configuration for indexer --&gt; - &lt;property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /&gt; &lt;!-- path to JGroups configuration --&gt; - &lt;property name="jbosscache-cluster-name" value="JCR_Cluster_indexer_production" /&gt; &lt;!-- JBoss Cache indexer cluster name --&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;/properties&gt; -&lt;/query-handler&gt; -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[<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="list-Reference_Guide-conf_lock_manager"> <para> Lock Manager configuration: </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="jar:/conf/portal/test-jbosscache-lock.xml" /&gt; &lt;!-- path to JBoss Cache configuration for lock manager --&gt; - &lt;property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /&gt; &lt;!-- path to JGroups configuration --&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="JCR_Cluster_lock_production" /&gt; &lt;!-- JBoss Cache locks cluster name --&gt; +<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="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 --> - &lt;property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_production"/&gt; &lt;!-- the name of the DB table where lock's data will be stored --&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_production_pk"/&gt; - &lt;property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn"/&gt; - &lt;property name="jbosscache-cl-cache.jdbc.node.column" value="node"/&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> + <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> </orderedlist> - </section> - </section> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration-persister.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration-persister.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration-persister.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -3,87 +3,95 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "../../../Reference_Guide.ent"> %BOOK_ENTITIES; ]> -<section id="sect-Reference_Guide-JCR_Configuration_persister"> - <title>JCR Configuration persister</title> - <section id="sect-Reference_Guide-JCR_Configuration_persister-Idea"> - <title>Idea</title> +<section id="sect-Reference_Guide-The_The_JCR_Configuration_persister"> + <title>The JCR Configuration persister</title> + <para> - JCR Repository Service uses <classname>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</classname> component to read its configuration. + The JCR Repository Service uses the <classname>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</classname> component to read its configuration. </para> -<programlisting>&lt;component&gt; - &lt;key&gt;org.exoplatform.services.jcr.config.RepositoryServiceConfiguration&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;conf-path&lt;/name&gt; - &lt;description&gt;JCR configuration file&lt;/description&gt; - &lt;value&gt;/conf/standalone/exo-jcr-config.xml&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; - &lt;/component&gt; -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[<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>/conf/standalone/exo-jcr-config.xml</value> + </value-param> + </init-params> + </component>]]></programlisting> + <para> - In the example Repository Service will read the configuration from the file <filename>/conf/standalone/exo-jcr-config.xml</filename>. + In the example above the Repository Service will read the configuration from the file <filename>/conf/standalone/exo-jcr-config.xml</filename>. </para> <para> - But in some cases it's required to change the configuration on the fly. And know that the new one will be used. Additionally we wish not to modify the original file. + To make changes while the JCR is active, to be sure the changes will be used, and to avoid modifying the orginal file, the configuration persister feature allows new configurations to stored in different locations. </para> + + <section id="sect-Reference_Guide-The_JCR_Configuration_persister-Usage"> + <title>Usage</title> <para> - In this case we have to use the configuration persister feature which allows to store the configuration in different locations. + On startup, the <classname>RepositoryServiceConfiguration</classname> component checks if a configuration persister has been configured. </para> - </section> - - <section id="sect-Reference_Guide-JCR_Configuration_persister-Usage"> - <title>Usage</title> <para> - On startup <classname>RepositoryServiceConfiguration</classname> component checks if a configuration persister was configured. In that case it uses the provided <classname>ConfigurationPersister</classname> implementation class to instantiate the persister object. + It one has been, it uses the provided <classname>ConfigurationPersister</classname> implementation class to instantiate the persister object. </para> <para> - Configuration with persister: -<programlisting>&lt;component&gt; - &lt;key&gt;org.exoplatform.services.jcr.config.RepositoryServiceConfiguration&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;conf-path&lt;/name&gt; - &lt;description&gt;JCR configuration file&lt;/description&gt; - &lt;value&gt;/conf/standalone/exo-jcr-config.xml&lt;/value&gt; - &lt;/value-param&gt; - &lt;properties-param&gt; - &lt;name&gt;working-conf&lt;/name&gt; - &lt;description&gt;working-conf&lt;/description&gt; - &lt;property name="source-name" value="jdbcjcr" /&gt; - &lt;property name="dialect" value="mysql" /&gt; - &lt;property name="persister-class-name" value="org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister" /&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component&gt; -</programlisting> + An example of a configuration using the persister: </para> - <para> - Where: - <itemizedlist> - <listitem> + <programlistingco> + <areaspec> + <area coords="13" id="Reference_Guide-The_The_JCR_Configuration_persister-source-name"/> + <area coords="14" id="Reference_Guide-The_The_JCR_Configuration_persister-dialect"/> + <area coords="15" id="Reference_Guide-The_The_JCR_Configuration_persister-persister-class-name"/> + </areaspec> + +<programlisting language="XML" role="XML"><![CDATA[<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>/conf/standalone/exo-jcr-config.xml</value> + </value-param> + <properties-param> + <name>working-conf</name> + <description>working-conf</description> + <property name="source-name" value="jdbcjcr" /> + <property name="dialect" value="mysql" /> + <property name="persister-class-name" value="org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister" /> + </properties-param> + </init-params> + </component>]]></programlisting> + + + <calloutlist> + <callout arearefs="Reference_Guide-The_The_JCR_Configuration_persister-source-name"> <para> - <parameter>source-name</parameter> - JNDI source name configured in <classname>InitialContextInitializer</classname> component. (<parameter>sourceName</parameter> prior v.1.9.) Find more in <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/>. + The <parameter>source-name</parameter> parameter is the JNDI source name configured in <classname>InitialContextInitializer</classname> component (also known as <parameter>sourceName</parameter> in versions prior to 1.9.). refer to <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/> for more information. </para> - </listitem> - <listitem> + </callout> + <callout arearefs="Reference_Guide-The_The_JCR_Configuration_persister-dialect"> <para> - <parameter>dialect</parameter> - SQL dialect which will be used with database from <parameter>source-name</parameter>. Find more in <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/>. + The <parameter>dialect</parameter> parameter is the SQL dialect which will be used with the database from <parameter>source-name</parameter>. Refer to <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/> for more information. </para> - </listitem> - <listitem> + </callout> + <callout arearefs="Reference_Guide-The_The_JCR_Configuration_persister-persister-class-name"> <para> - <parameter>persister-class-name</parameter> - class name of <classname>ConfigurationPersister</classname> interface implementation. (<parameter>persisterClassName</parameter> prior v.1.9.) + The <parameter>persister-class-name</parameter> parameter is the class name of the <classname>ConfigurationPersister</classname> interface implementation. (known as <parameter>persisterClassName</parameter> in version earlier than 1.9.) </para> - </listitem> - </itemizedlist> + </callout> + </calloutlist> + </programlistingco> + + + <para> + The <parameter>ConfigurationPersister</parameter> interface: </para> - <para> - ConfigurationPersister interface: -<programlisting>/** + +<programlisting language="Java" role="JAVA">/** * Init persister. * Used by RepositoryServiceConfiguration on init. * @return - config data stream @@ -108,16 +116,14 @@ */ boolean hasConfig() throws RepositoryConfigurationException; </programlisting> - </para> + <para> - JCR Core implementation contains a persister which stores the repository configuration in the relational database using JDBC calls - <classname>org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister</classname>. + The JCR Core implementation contains a persister which stores the repository configuration in the relational database using JDBC calls (<classname>org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister</classname>). </para> <para> - The implementation will crate and use table JCR_CONFIG in the provided database. + The implementation will create and use the table <parameter>JCR_CONFIG</parameter> in the provided database. However, a developer can implement another persister for any particular usecase. </para> - <para> - But the developer can implement his own persister for his particular usecase. - </para> + </section> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -5,73 +5,170 @@ ]> <section id="sect-Reference_Guide-eXo_JCR_configuration"> <title>eXo JCR configuration</title> - - <section id="sect-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration"> - <title>Portal and Standalone configuration</title> <para> - Like other eXo services eXo JCR can be configured and used in Portal (or Embedded) mode (as a service embedded in eXo Portal) and in Standalone mode. + The JCR configuration is defined in an XML file (as per the DTD below). </para> <para> - In Embedded mode, JCR services are registered in the Portal container. In Standalone mode JCR uses a Standalone container. + The JCR Service can use multiple Repositories and each repository can have multiple Workspaces. </para> <para> - The main difference between these container types is that the first is intended to be used in a Portal (Web) environment while the second can be used standalone. <!--(DOC TODO see the comprehensive page Service Configuration for Beginners for more details) --> + The Repositories configuration parameters support human-readable formats of values. They are not case-sensitive. </para> <para> - The following setup procedure is used to obtain a Standalone configuration: <!--(DOC TODO find more in Container configuration)--> + The parameters are: </para> -<!-- DOC TODO: The following list of points are unclear. Are the edited versions correct? --> - - <itemizedlist> + <variablelist> + <varlistentry> + <term>Number formats:</term> <listitem> - <!--Original <para> - Configuration that is set explicitly using StandaloneContainer.addConfigurationURL(String url) or StandaloneContainer.addConfigurationPath(String path) before getInstance() - </para> --> - <!-- Revised --><para> - Configuration must be explicitly set using <literal>StandaloneContainer.addConfigurationURL(String url)</literal> or <literal>StandaloneContainer.addConfigurationPath(String path)</literal>before <literal>getInstance()</literal> makes a call. + <para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">K</emphasis> or <emphasis role="bold">KB</emphasis> for kilobytes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">M</emphasis> or <emphasis role="bold">MB</emphasis> for megabytes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">G</emphasis> or <emphasis role="bold">GB</emphasis> for gigabytes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">T</emphasis> or <emphasis role="bold">TB</emphasis> for terrabytes. + </para> + </listitem> + <listitem> + <para> + Examples: 200k or 200 Kbytes; 4m or 4 Mbytes; 1.4G or 1.4 Gbytes; 10T or 10 Tbytes + </para> + </listitem> + </itemizedlist> </para> </listitem> + </varlistentry> + <varlistentry> + <term>Time formats:</term> <listitem> - <!-- Original <para> - Configuration from $base:directory/exo-configuration.xml or $base:directory/conf/exo-configuration.xml file. Where $base:directory is either AS's home directory in case of J2EE AS environment or just the current directory in case of a standalone application. - </para> --> - <!-- Revised --><para> - Configuration settings are read from <filename><replaceable>$base:directory</replaceable>/exo-configuration.xml</filename> or <filename><replaceable>$base:directory</replaceable>/conf/exo-configuration.xml</filename>. - </para> <para> - Replace <replaceable>$base:directory</replaceable> in the above locations with, either the Application Server's home directory (in J2EE environments) or the current directory for standalone applications. + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">ms</emphasis> for milliseconds. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">s</emphasis> for seconds. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">m</emphasis> for minutes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">h</emphasis> for hours. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">d</emphasis> for days. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">w</emphasis> for weeks. + </para> + </listitem> + <listitem> + <para> + The default time format is seconds if no other format is specified. + </para> + </listitem> + <listitem> + <para> + Examples: 500ms or 500 milliseconds; 20, 20s or 20 seconds; 30m or 30 minutes; 12h or 12 hours; 5d or 5 days; 4w or 4 weeks. + </para> + </listitem> + </itemizedlist> </para> </listitem> - <listitem> - <!-- Original <para> - /conf/exo-configuration.xml in the current classloader (e.g. war, ear archive) - </para> --> - <!-- Revised --><para> - The current classloader <code>war</code> or <code>ear</code> archive must contain a <filename>/conf/exo-configuration.xml</filename> file. - </para> - </listitem> - <listitem> - <!-- Original <para> - Configuration from $service_jar_file/conf/portal/configuration.xml. WARNING: do not rely on some concrete jar's configuration if you have more than one jar containing conf/portal/configuration.xml file. In this case choosing a configuration is unpredictable. - </para> --> - <!-- Revised --><para> - Further configuration setting are read from <filename><replaceable>$service_jar_file</replaceable>/conf/portal/configuration.xml</filename> - </para> - <important> + </varlistentry> + </variablelist> + + <section id="sect-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration"> + <title>Portal and Standalone configuration</title> + <para> + Like other eXo services eXo JCR can be configured and used in Portal (or Embedded) mode (as a service embedded in eXo Portal) and in Standalone mode. + </para> + <para> + In Embedded mode, JCR services are registered in the Portal container. In Standalone mode JCR uses a Standalone container. + </para> + <para> + The main difference between these container types is that the first is intended to be used in a Portal (Web) environment while the second can be used standalone. <!--(DOC TODO see the comprehensive page Service Configuration for Beginners for more details) --> + </para> + <para> + The following setup procedure is used to obtain a Standalone configuration: <!--(DOC TODO find more in Container configuration)--> + </para> +<!-- DOC TODO: The following list of points are unclear. Are the edited versions correct? --> + + <itemizedlist> + <listitem> + <!--Original <para> + Configuration that is set explicitly using StandaloneContainer.addConfigurationURL(String url) or StandaloneContainer.addConfigurationPath(String path) before getInstance() + </para> --> + <!-- Revised --><para> + Configuration must be explicitly set using <literal>StandaloneContainer.addConfigurationURL(String url)</literal> or <literal>StandaloneContainer.addConfigurationPath(String path)</literal>before <literal>getInstance()</literal> makes a call. + </para> + </listitem> + <listitem> + <!-- Original <para> + Configuration from $base:directory/exo-configuration.xml or $base:directory/conf/exo-configuration.xml file. Where $base:directory is either AS's home directory in case of J2EE AS environment or just the current directory in case of a standalone application. + </para> --> + <!-- Revised --><para> + Configuration settings are read from <filename><replaceable>$base:directory</replaceable>/exo-configuration.xml</filename> or <filename><replaceable>$base:directory</replaceable>/conf/exo-configuration.xml</filename>. + </para> <para> - Do not rely on the settings contained in any particular configuration file if you have more than one <code>jar</code> archive that contains a <filename>conf/portal/configuration.xml</filename> file. Behavior in this scenario can be erratic as the JCR's choice of configuration file is unpredictable. + Replace <replaceable>$base:directory</replaceable> in the above locations with, either the Application Server's home directory (in J2EE environments) or the current directory for standalone applications. </para> - </important> - </listitem> - </itemizedlist> - <para> - The JCR service configuration is formatted as follows: - </para> - <programlistingco> - <areaspec> - <area coords="10" id="area-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration-JCR_Service_Configuration-conf-path" /> - <area coords="16" id="area-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration-JCR_Service_Configuration-working-conf" /> - </areaspec> + </listitem> + <listitem> + <!-- Original <para> + /conf/exo-configuration.xml in the current classloader (e.g. war, ear archive) + </para> --> + <!-- Revised --><para> + The current classloader <code>war</code> or <code>ear</code> archive must contain a <filename>/conf/exo-configuration.xml</filename> file. + </para> + </listitem> + <listitem> + <!-- Original <para> + Configuration from $service_jar_file/conf/portal/configuration.xml. WARNING: do not rely on some concrete jar's configuration if you have more than one jar containing conf/portal/configuration.xml file. In this case choosing a configuration is unpredictable. + </para> --> + <!-- Revised --><para> + Further configuration setting are read from <filename><replaceable>$service_jar_file</replaceable>/conf/portal/configuration.xml</filename> + </para> + <important> + <para> + Do not rely on the settings contained in any particular configuration file if you have more than one <code>jar</code> archive that contains a <filename>conf/portal/configuration.xml</filename> file. Behavior in this scenario can be erratic as the JCR's choice of configuration file is unpredictable. + </para> + </important> + </listitem> + </itemizedlist> + <para> + The JCR service configuration is formatted as follows: + </para> + <programlistingco> + <areaspec> + <area coords="10" id="area-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration-JCR_Service_Configuration-conf-path" /> + <area coords="15" id="area-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration-JCR_Service_Configuration-working-conf" /> + </areaspec> <programlisting language="XML" role="XML"><![CDATA[<component> <key>org.exoplatform.services.jcr.RepositoryService</key> @@ -82,13 +179,11 @@ <type>org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl</type> <init-params> <value-param> - <name>conf-path</name> <description>JCR repositories configuration file</description> <value>jar:/conf/standalone/exo-jcr-config.xml</value> </value-param> <properties-param> - <name>working-conf</name> <description>working-conf</description> <property name="source-name" value="jdbcjcr" /> @@ -97,132 +192,32 @@ </properties-param> </init-params> </component>]]></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration-JCR_Service_Configuration-conf-path"> - <para> - <literal>&lt;conf-path&gt;</literal> is a path to a <literal>RepositoryService</literal> JCR Configuration. - </para> - </callout> - <callout arearefs="area-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration-JCR_Service_Configuration-working-conf"> - <para> - <literal>&lt;working-conf&gt;</literal> is an optional JCR configuration persister configuration. The persister will be disabled if there is no <literal>&lt;working-conf&gt;</literal> defined. - </para> - </callout> - </calloutlist> - </programlistingco> - - <section id="sect-Reference_Guide-Portal_and_Standalone_configuration-JCR_Configuration"> - <title>JCR Configuration</title> - <para> - The JCR configuration is defined in an XML file (as per the DTD below). - </para> - <para> - The JCR Service can use multiple Repositories and each repository can have multiple Workspaces. - </para> - <para> - The Repositories configuration parameters support human-readable formats of values. They are not case-sensitive. - </para> - <para> - The parameters are: - </para> - <variablelist> - <varlistentry> - <term>Number formats:</term> - <listitem> - <para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">K</emphasis> or <emphasis role="bold">KB</emphasis> for kilobytes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">M</emphasis> or <emphasis role="bold">MB</emphasis> for megabytes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">G</emphasis> or <emphasis role="bold">GB</emphasis> for gigabytes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">T</emphasis> or <emphasis role="bold">TB</emphasis> for terrabytes. - </para> - </listitem> - <listitem> - <para> - Examples: 200k or 200 Kbytes; 4m or 4 Mbytes; 1.4G or 1.4 Gbytes; 10T or 10 Tbytes - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Time formats:</term> - <listitem> - <para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">ms</emphasis> for milliseconds. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">s</emphasis> for seconds. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">m</emphasis> for minutes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">h</emphasis> for hours. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">d</emphasis> for days. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">w</emphasis> for weeks. - </para> - </listitem> - <listitem> - <para> - The default time format is seconds if no other format is specified. - </para> - </listitem> - <listitem> - <para> - Examples: 500ms or 500 milliseconds; 20, 20s or 20 seconds; 30m or 30 minutes; 12h or 12 hours; 5d or 5 days; 4w or 4 weeks. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - </variablelist> + <calloutlist> + <callout arearefs="area-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration-JCR_Service_Configuration-conf-path"> + <para> + <literal>&lt;conf-path&gt;</literal> is a path to a <literal>RepositoryService</literal> JCR Configuration. + </para> + </callout> + <callout arearefs="area-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration-JCR_Service_Configuration-working-conf"> + <para> + <literal>&lt;working-conf&gt;</literal> is an optional JCR configuration persister configuration. The persister will be disabled if there is no <literal>&lt;working-conf&gt;</literal> defined. + </para> + </callout> + </calloutlist> + </programlistingco> </section> <section id="sect-Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration"> <title>Repository service configuration</title> - <para> - The default configuration of the Repository Service is defined in <filename><replaceable>jar:</replaceable>/conf/portal/exo-jcr-config.xml</filename>. It is available in both portal and standalone modes. - </para> - <para> - In portal mode it is overriden and located in the portal web application <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. - </para> - <para> - An example of the Repository Service configuration for standalone mode is included below: - </para> + <para> + The default configuration of the Repository Service is defined in <filename><replaceable>jar:</replaceable>/conf/portal/exo-jcr-config.xml</filename>. It is available in both portal and standalone modes. + </para> + <para> + In portal mode it is overriden and located in the portal web application <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + </para> + <para> + An example of the Repository Service configuration for standalone mode is included below: + </para> <!-- <programlistingco> @@ -356,184 +351,278 @@ </calloutlist> </programlistingco> --> - <variablelist> - <title>Repository Service configuration:</title> - <varlistentry> - <term>default-repository</term> - <listitem> - <para> - The name of a default repository (one returned by RepositoryService.getRepository()) - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>repositories</term> - <listitem> - <para> - The list of repositories. - </para> - </listitem> - </varlistentry> - </variablelist> + <variablelist> + <title>Repository Service configuration:</title> + <varlistentry> + <term>default-repository</term> + <listitem> + <para> + The name of a default repository (one returned by <literal>RepositoryService.getRepository()</literal>) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>repositories</term> + <listitem> + <para> + The list of repositories. + </para> + </listitem> + </varlistentry> + </variablelist> - <variablelist> - <title>Repository configuration:</title> - <varlistentry> - <term>name</term> - <listitem> - <para> - The name of a repository. - </para> - </listitem> - </varlistentry> + <variablelist> + <title>Repository configuration:</title> + <varlistentry> + <term>name</term> + <listitem> + <para> + The name of the repository. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>default-workspace</term> + <listitem> + <para> + The name of the default workspace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>system-workspace</term> + <listitem> + <para> + The name of workspace where /jcr:system node is placed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>security-domain</term> + <listitem> + <para> + The name of a security domain for JAAS authentication + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>access-control</term> + <listitem> + <para> + The name of an access control policy. There can be 3 types: + </para> + <para> + <emphasis role="bold">optional</emphasis> + </para> + <para> + AN ACL is created on-demand. This is the default policy. + </para> + <para> + <emphasis role="bold">disable</emphasis> + </para> + <para> + Disables access control. + </para> + <para> + <emphasis role="bold">mandatory</emphasis> + </para> + <para> + An ACL is created for each added node. This function not supported in this release. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>authentication-policy</term> + <listitem> + <para> + The name of an authentication policy class. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>workspaces</term> + <listitem> + <para> + The list of workspaces. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>session-max-age</term> + <listitem> + <para> + The amount of time before an idle session will be removed (called logout). If not set, the idle session will never be removed. + </para> + </listitem> + </varlistentry> + </variablelist> - <varlistentry> - <term>default-workspace</term> - <listitem> - <para> - - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>system-workspace</term> - <listitem> - <para> - The name of workspace where /jcr:system node is placed. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>security-domain</term> - <listitem> - <para> - The name of a security domain for JAAS authentication - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>access-control</term> - <listitem> - <para> - The name of an access control policy. There can be 3 types: optional - ACL is created on-demand(default), disable - no access control, mandatory - an ACL is created for each added node(not supported yet) - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>authentication-policy</term> - <listitem> - <para> - The name of an authentication policy class - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>workspaces</term> - <listitem> - <para> - The list of workspaces. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>session-max-age</term> - <listitem> - <para> - The time after which an idle session will be removed (called logout). If not set, the idle session will never be removed. - </para> - </listitem> - </varlistentry> - </variablelist> + <variablelist> + <title>Workspace configuration:</title> + <varlistentry> + <term>name</term> + <listitem> + <para> + The name of the workspace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>auto-init-root-nodetype</term> + <listitem> + <para> + The node type for root node initialization. This is deprecated in JCR 1.9. The initializer is to be used instead. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>container</term> + <listitem> + <para> + Workspace data container (physical storage) configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>initializer</term> + <listitem> + <para> + Workspace initializer configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>cache</term> + <listitem> + <para> + Workspace storage cache configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>query-handler</term> + <listitem> + <para> + Query handler configuration. + </para> + </listitem> + </varlistentry> + </variablelist> - <variablelist> - <title>Workspace configuration:</title> - <varlistentry> - <term>name</term> - <listitem> + <variablelist> + <title>Workspace data container configuration:</title> + <varlistentry> + <term>class</term> + <listitem> + <para> + A workspace data container class name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> + The list of properties (in name-value pairs) for the concrete Workspace data container. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>value-storages</term> + <listitem> + <para> + The list of value storage plugins. + </para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <title>Value Storage plugin configuration (optional feature):</title> + <varlistentry> + <term>value-storage</term> + <listitem> + <para> + Optional value Storage plugin definition. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>class</term> + <listitem> + <para> + A value storage plugin class name (attribute). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> + The list of properties (in name-value pairs) for a concrete Value Storage plugin. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>filters</term> + <listitem> + <para> + The list of filters defining conditions when this plugin is applicable. + </para> + </listitem> + </varlistentry> + </variablelist> + <note> <para> - The name of a workspace. + The value-storage element is optional. If you don't include it, the values will be stored as BLOBs inside the database. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>auto-init-root-nodetype</term> + </note> + + <variablelist> + <title>Initializer configuration (optional):</title> + <varlistentry> + <term>class</term> <listitem> <para> - DEPRECATED in JCR 1.9 (use initializer). The node type for root node initialization. + Initializer implementation class. </para> </listitem> </varlistentry> - <varlistentry> - <term>container</term> + <varlistentry> + <term>properties</term> <listitem> <para> - Workspace data container (physical storage) configuration. + The list of properties (in name-value pairs). Properties are supported: </para> - </listitem> - </varlistentry> - <varlistentry> - <term>initializer</term> - <listitem> <para> - Workspace initializer configuration. + <emphasis role="bold">root-nodetype</emphasis> </para> - </listitem> - </varlistentry> - <varlistentry> - <term>cache</term> - <listitem> <para> - Workspace storage cache configuration. + The node type for root node initialization. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>query-handler</term> - <listitem> <para> - Query handler configuration. + <emphasis role="bold">root-permissions</emphasis> </para> - </listitem> - </varlistentry> - </variablelist> - <formalpara> - <title>Workspace data container configuration:</title> - <para></para> - </formalpara> - <variablelist> - <varlistentry> - <term>class</term> - <listitem> <para> - A workspace data container class name. + Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities and the type of permission. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> <para> - The list of properties (name-value pairs) for the concrete Workspace data container. + For example any read;:/admin read;:/admin add_node;:/admin set_property;:/admin remove means that users from group admin have all permissions and other users have only a 'read' permission. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>value-storages</term> - <listitem> <para> - The list of value storage plugins. + Configurable initializer adds a capability to override workspace initial startup procedure. </para> </listitem> </varlistentry> </variablelist> <variablelist> - <title>Value Storage plugin configuration (optional feature):</title> + <title>Cache configuration:</title> <varlistentry> - <term>value-storage</term> + <term>enabled</term> <listitem> <para> - Optional value Storage plugin definition. + Defines if the workspace cache is enabled. </para> </listitem> </varlistentry> @@ -541,105 +630,43 @@ <term>class</term> <listitem> <para> - A value storage plugin class name (attribute) + Cache implementation class. This is optional from JCR version 1.9. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> <para> - The list of properties (name-value pairs) for a concrete Value Storage plugin. + The default value is <literal>org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl</literal>. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>filters</term> - <listitem> <para> - The list of filters defining conditions when this plugin is applicable. + The cache can be configured to use concrete implementation of <literal>WorkspaceStorageCache</literal> interface. </para> - </listitem> - </varlistentry> - </variablelist> - <note> - <para> - The value-storage element is optional. If you don't include it, the values will be stored as BLOBs inside the database. - </para> - </note> - - <variablelist> - <title>Initializer configuration (optional):</title> - <varlistentry> - <term>class</term> - <listitem> <para> - Initializer implementation class. + The JCR core has two implementation to use: </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> <para> - The list of properties (name-value pairs). Properties are supported: + <emphasis role="bold">LinkedWorkspaceStorageCacheImpl</emphasis> </para> - </listitem> - </varlistentry> - <varlistentry> - <term>root-nodetype</term> - <listitem> <para> - The node type for root node initialization + The default implementation, with configurable read behavior and statistic. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>root-permissions</term> - <listitem> <para> - Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities (user, group etc, see Organization service documentation for details) and the type of permission. For example any read;:/admin read;:/admin add_node;:/admin set_property;:/admin remove means that users from group admin have all permissions and other users have only a 'read' permission. + <emphasis role="bold">WorkspaceStorageCacheImpl</emphasis> </para> <para> - Configurable initializer adds a capability to override workspace initial startup procedure. + This implememtation if a legacy from pre 1.9 version of the JCR, however, it may still be used. </para> </listitem> </varlistentry> - </variablelist> - - <variablelist> - <title>Cache configuration:</title> - <varlistentry> - <term>enabled</term> - <listitem> - <para> - If workspace cache is enabled. - </para> - </listitem> - </varlistentry> <varlistentry> - <term>class</term> - <listitem> - <para> - Cache implementation class, optional from 1.9. Default value is <literal>org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl</literal>. - </para> - <para> - Cache can be configured to use concrete implementation of WorkspaceStorageCache interface. JCR core has two implementation to use: * LinkedWorkspaceStorageCacheImpl - default, with configurable read behavior and statistic. * WorkspaceStorageCacheImpl - pre 1.9, still can be used. - </para> - </listitem> - </varlistentry> - <varlistentry> <term>properties</term> <listitem> <para> - The list of properties (name-value pairs) for Workspace cache: + The list of properties (in name-value pairs) for the Workspace cache: </para> <variablelist> <varlistentry> <term>max-size</term> <listitem> <para> - Cache maximum size. + The maximum size of the Cache. </para> </listitem> </varlistentry> @@ -652,9 +679,9 @@ </listitem> </varlistentry> </variablelist> - <para> +<!-- TODO <para> TODO LinkedWorkspaceStorageCacheImpl supports additional optional parameters - </para> + </para> --> </listitem> </varlistentry> </variablelist> @@ -673,7 +700,7 @@ <term>properties</term> <listitem> <para> - The list of properties (name-value pairs) for a Query Handler (indexDir) properties and advanced features described in *Search Configuration*. + The list of properties (name-value pairs) for a Query Handler (<literal>indexDir</literal>) properties and advanced features described in <xref linkend="sect-Reference_Guide-Search_Configuration"/>. </para> </listitem> </varlistentry> @@ -685,7 +712,7 @@ <term>time-out</term> <listitem> <para> - Time after which the unused global lock will be removed. + The amount of time before the unused global lock is removed. </para> </listitem> </varlistentry> @@ -693,7 +720,7 @@ <term>persister</term> <listitem> <para> - A class for storing lock information for future use. For example, remove lock after jcr restart. + A class for storing lock information for future use. For example; remove lock after jcr restart. </para> </listitem> </varlistentry> @@ -752,9 +779,9 @@ &lt;!ELEMENT properties (property+)&gt; &lt;!ELEMENT property EMPTY&gt; </programlisting> - </section> + </section> <section id="sect-Reference_Guide-eXo_JCR_configuration-Related_documents"> - <title>Related documents</title> + <title>Related Sections</title> <itemizedlist> <listitem> <para> @@ -773,8 +800,8 @@ </listitem> </itemizedlist> </section> - </section> </section> + Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -8,72 +8,100 @@ <section id="sect-Reference_Guide-External_Value_Storages-Introduction"> <title>Introduction</title> <para> - By default JCR Values are stored in the Workspace Data container along with the JCR structure (i.e. Nodes and Properties). eXo JCR offers an additional option of storing JCR Values separately from Workspace Data container, which can be extremely helpful to keep Binary Large Objects (BLOBs) for example. + JCR Values are stored in the Workspace Data container by default. eXo JCR offers an additional option of storing JCR Values separately from Workspace Data container which can help keep Binary Large Objects (BLOBs). </para> <para> - Value storage configuration is a part of Repository configuration, find more details in <xref linkend="sect-Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration"/>. + Value storage configuration is a part of the Repository configuration.Refer to <xref linkend="sect-Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration"/> for more details. </para> <para> - Tree-based storage is recommended for most of cases. If you run an application on Amazon EC2 - the S3 option may be interesting for architecture. Simple 'flat' storage is good in speed of creation/deletion of values, it might be a compromise for a small storages. + Tree-based storage is recommended in most cases. </para> +<!--Not sure this is necessary + <para> + If you run an application on Amazon EC2 - the S3 option may be interesting for architecture. Simple 'flat' storage is good in speed of creation/deletion of values, it might be a compromise for a small storages. + </para> --> </section> <section id="sect-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage"> <title>Tree File Value Storage</title> <para> - Holds Values in tree-like FileSystem files. <property>path</property> property points to the root directory to store the files. + Tree File Value Storage holds Values in tree-like FileSystem files. <property>path</property> property points to the root directory to store the files. </para> <para> This is a recommended type of external storage, it can contain large amount of files limited only by disk/volume free space. </para> <para> - A disadvantage it's a higher time on Value deletion due to unused tree-nodes remove. + However using Tree File Value Storage can result in a higher time on Value deletion, due to the removal of unused tree-nodes. </para> + + <programlistingco> + <areaspec> + <area coords="1" id="Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-id"/> + <area coords="3" id="Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-path"/> + </areaspec> -<programlisting>&lt;value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; - &lt;properties&gt; - &lt;property name="path" value="data/values"/&gt; - &lt;/properties&gt; - &lt;filters&gt; - &lt;filter property-type="Binary" min-value-size="1M"/&gt; - &lt;/filters&gt; -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[<value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> + <properties> + <property name="path" value="data/values"/> + </properties> + <filters> + <filter property-type="Binary" min-value-size="1M"/> + </filters> +]]></programlisting> + <calloutlist> + <callout arearefs="Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-id"> + <para> + The <emphasis role="bold">id</emphasis> is the value storage unique identifier, used for linking with properties stored in workspace container + </para> + </callout> + <callout arearefs="Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-path"> + <para> + <emphasis role="bold">path</emphasis> is a location where value files will be stored. + </para> + </callout> + </calloutlist> + </programlistingco> + <para> - Where : - <simplelist> - <member><parameter>id</parameter> - the value storage unique identifier, used for linking with properties stored in workspace container</member> - <member><parameter>path</parameter> - a location where value files will be stored</member> - </simplelist> + Each file value storage can have the <function>filter(s)</function> for incoming values. A filter can match values by <property>property-type</property>, <property>property-name</property>, <property>ancestor-path</property> and/or the size of values stored (<property>min-value-size</property>, in bytes). </para> <para> - Each file value storage can have the <function>filter(s)</function> for incoming values. A filter can match values by property type (<property>property-type</property>), property name (<property>property-name</property>), ancestor path (<property>ancestor-path</property>) and/or size of values stored (<property>min-value-size</property>, in bytes). In code sample we use a filter with property-type and min-value-size only. I.e. storage for binary values with size greater of 1MB. It's recommended to store properties with large values in file value storage only. + In the example above a filter with <property>property-type</property> and <property>min-value-size</property> has been used. This results in storage for binary values with size greater of 1MB. </para> <para> - Another example shows a value storage with different locations for large files (<property>min-value-size</property> a 20Mb-sized filter). A value storage uses ORed logic in the process of filter selection. That means the first filter in the list will be asked first and if not matched the next will be called etc. Here a value matches the 20 MB-sized filter <property>min-value-size</property> and will be stored in the path "data/20Mvalues", all other in "data/values". + It is recommended that properties with large values are stored in file value storage only. </para> + <para> + The example below shows a value storage with different locations for large files (<property>min-value-size</property> a 20Mb-sized filter). + </para> + <para> + A value storage uses ORed logic in the process of filter selection. This means the first filter in the list will be called first and if it is not matched the next will be called, and so on. + </para> + <para> + In this example a value matches the 20MB filter <property>min-value-size</property> and will be stored in the path "<literal>data/20Mvalues</literal>", all other filters will be stored in "<literal>data/values</literal>". + </para> -<programlisting>&lt;value-storages&gt; - &lt;value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; - &lt;properties&gt; - &lt;property name="path" value="data/20Mvalues"/&gt; - &lt;/properties&gt; - &lt;filters&gt; - &lt;filter property-type="Binary" min-value-size="20M"/&gt; - &lt;/filters&gt; - &lt;value-storage&gt; - &lt;value-storage id="Storage #2" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; - &lt;properties&gt; - &lt;property name="path" value="data/values"/&gt; - &lt;/properties&gt; - &lt;filters&gt; - &lt;filter property-type="Binary" min-value-size="1M"/&gt; - &lt;/filters&gt; - &lt;value-storage&gt; -&lt;value-storages&gt; -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[<value-storages> + <value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> + <properties> + <property name="path" value="data/20Mvalues"/> + </properties> + <filters> + <filter property-type="Binary" min-value-size="20M"/> + </filters> + <value-storage> + <value-storage id="Storage #2" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> + <properties> + <property name="path" value="data/values"/> + </properties> + <filters> + <filter property-type="Binary" min-value-size="1M"/> + </filters> + <value-storage> +<value-storages>]]></programlisting> </section> - <section id="sect-Reference_Guide-External_Value_Storages-Simple_File_Value_Storage"> +<!-- Triaged <section id="sect-Reference_Guide-External_Value_Storages-Simple_File_Value_Storage"> <title>Simple File Value Storage</title> <note> <para> @@ -95,86 +123,112 @@ &lt;filter property-type="Binary" min-value-size="1M"/&gt; &lt;/filters&gt; </programlisting> - </section> + </section> --> <section id="sect-Reference_Guide-External_Value_Storages-Content_Addressable_Value_storage_CAS_support"> <title>Content Addressable Value storage (CAS) support</title> <para> - eXo JCR supports <phrase>Content-addressable storage</phrase> feature for <phrase>Values</phrase> storing. + eXo JCR supports the <phrase>Content-addressable storage</phrase> feature for <phrase>Values</phrase> storing. </para> - <note> - <para> - Content-addressable storage, also referred to as associative storage and abbreviated CAS, is a mechanism for storing information that can be retrieved based on its content, not its storage location. It is typically used for high-speed storage and retrieval of fixed content, such as documents stored for compliance with government regulations. - </para> - </note> <para> + Content-addressable storage, also referred to as associative storage and abbreviated as <emphasis role="bold">CAS</emphasis>, is a mechanism for storing information that can be retrieved based on its content, not its storage location. + </para> + <para> + It is typically used for high-speed storage and retrieval of fixed content, such as documents stored for compliance with government regulations. + </para> + <para> Content Addressable Value storage stores unique content once. Different properties (values) with same content will be stored as one data file shared between those values. We can tell the Value content will be shared across some Values in storage and will be stored on one physical file. </para> <para> Storage size will be decreased for application which governs potentially same data in the content. </para> - <note> - <para> - For example: if you have 100 different properties containing the same data (e.g. mail attachment) the storage stores only one single file. The file will be shared with all referencing properties. - </para> - </note> <para> - If property Value changes it is stored in an additional file. Alternatively the file is shared with other values, pointing to the same content. + As an example; if 100 different properties contain the same data (e.g. mail attachment) the storage stores only one single file. The file will be shared with all referencing properties. </para> <para> - The storage calculates Value content address each time the property was changed. CAS write operations are much more expensive compared to the non-CAS storages. + If a property Value changes it is stored in an additional file. Alternatively the file is shared with other values, pointing to the same content. </para> <para> - Content address calculation based on java.security.MessageDigest hash computation and tested with <abbrev>MD5</abbrev> and <abbrev>SHA1</abbrev> algorithms. + The storage calculates Value content address each time the property was changed. CAS write operations are more expensive compared to the non-CAS storages. </para> + <para> + Content address calculation based on java.security.MessageDigest hash computation and tested with MD5 and SHA1 algorithms. + </para> <note> <para> - CAS storage works most efficiently on data that does not change often. For data that changes frequently, CAS is not as efficient as location-based addressing. + CAS storage works most efficiently on data that does not change often. For data that changes frequently CAS is not as efficient as location-based addressing. </para> </note> <para> CAS support can be enabled for <phrase>Tree</phrase> and <phrase>Simple File Value Storage</phrase> types. </para> <para> - To enable CAS support just configure it in JCR Repositories configuration like we do for other Value Storages. + To enable CAS support just configure it in the JCR Repositories configuration with other Value Storages. </para> - -<programlisting>&lt;workspaces&gt; - &lt;workspace name="ws"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr"/&gt; - &lt;property name="dialect" value="oracle"/&gt; - &lt;property name="multi-db" value="false"/&gt; - &lt;property name="update-storage" value="false"/&gt; - &lt;property name="max-buffer-size" value="200k"/&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws"/&gt; - &lt;/properties&gt; - &lt;value-storages&gt; -&lt;!------------------- here -----------------------&gt; - &lt;value-storage id="ws" class="org.exoplatform.services.jcr.impl.storage.value.fs.CASableTreeFileValueStorage"&gt; - &lt;properties&gt; - &lt;property name="path" value="target/temp/values/ws"/&gt; - &lt;property name="digest-algo" value="MD5"/&gt; - &lt;property name="vcas-type" value="org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImpl"/&gt; - &lt;property name="jdbc-source-name" value="jdbcjcr"/&gt; - &lt;property name="jdbc-dialect" value="oracle"/&gt; - &lt;/properties&gt; - &lt;filters&gt; - &lt;filter property-type="Binary"/&gt; - &lt;/filters&gt; - &lt;/value-storage&gt; - &lt;/value-storages&gt; -</programlisting> - <para> - Properties: - <simplelist> - <member><parameter>digest-algo</parameter> - digest hash algorithm (MD5 and SHA1 were tested);</member> - <member><parameter>vcas-type</parameter> - Value CAS internal data type, JDBC backed is currently implemented org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImp;l</member> - <member><parameter>jdbc-source-name</parameter> - JDBCValueContentAddressStorageImpl specific parameter, database will be used to save CAS metadata. It's simple to use same as in workspace container;</member> - <member><parameter>jdbc-dialect</parameter> - JDBCValueContentAddressStorageImpl specific parameter, database dialect. It's simple to use same as in workspace container;</member> - </simplelist> - </para> + +<programlisting language="XML" role="XML"><![CDATA[<workspaces> + <workspace name="ws"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <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="target/temp/swap/ws"/> + </properties> + <value-storages> +<!------------------- here -----------------------> + <value-storage id="ws" class="org.exoplatform.services.jcr.impl.storage.value.fs.CASableTreeFileValueStorage"> + <properties> + <property name="path" value="target/temp/values/ws"/> + <property name="digest-algo" value="MD5"/> + <property name="vcas-type" value="org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImpl"/> + <property name="jdbc-source-name" value="jdbcjcr"/> + <property name="jdbc-dialect" value="oracle"/> + </properties> + <filters> + <filter property-type="Binary"/> + </filters> + </value-storage> + </value-storages>]]></programlisting> + + <variablelist> + <title>CAS Properties</title> + <varlistentry> + <term>digest-algo</term> + <listitem> + <para> + Digest hash algorithm (MD5 and SHA1 were tested). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>vcas-type</term> + <listitem> + <para> + Value CAS internal data type, JDBC backed is currently implemented <literal>org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImpl</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>jdbc-source-name</term> + <listitem> + <para> + A <literal>JDBCValueContentAddressStorageImpl</literal> specific parameter, a database will be used to save CAS metadata. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>jdbc-dialect</term> + <listitem> + <para> + A <literal>DBCValueContentAddressStorageImpl</literal> specific parameter defining database dialect. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -6,133 +6,167 @@ <section id="sect-Reference_Guide-JBoss_Cache_configuration"> <title>JBoss Cache configuration</title> <section id="sect-Reference_Guide-JBoss_Cache_configuration-JBoss_cache_configuration_for_indexer_lock_manager_and_data_container"> - <title>JBoss cache configuration for indexer, lock manager and data container</title> + <title>Indexer, Lock Manager and Data Container</title> <para> - Each mentioned components uses instances of JBoss Cache product for caching in clustered environment. So every element has it's own transport and has to be configured in proper way. As usual, workspaces has similar configuration but with different cluster-names and may-be some other parameters. The simplest way to configure them is to define their's own configuration files for each component in each workspace: + Each of these components use instances of the JBoss Cache product for caching in a clustered environment so every element has its own transport and has to be configured correctly. </para> + <para> + As usual, workspaces has similar configuration but with different cluster-names (and possibly some other parameters). The best way to configure them is to define specific configuration files for each component in each workspace: + </para> + <para> + For example: + </para> <programlisting>&lt;property name="jbosscache-configuration" value="conf/standalone/test-jbosscache-lock-db1-ws1.xml" /&gt; </programlisting> <para> - But if there are few workspaces, configuring them in such a way can be painful and hard-manageable. eXo JCR offers a template-based configuration for JBoss Cache instances. You can have one template for Lock Manager, one for Indexer and one for data container and use them in all the workspaces, defining the map of substitution parameters in main configuration file. Just simply define ${jbosscache-&lt;parameter name&gt;} inside xml-template and list correct value in JCR configuration file just below "jbosscache-configuration", as shown: + If there are many workspaces, however, configuring them in such a way can be hard to manage. Therefore the JCR offers a template-based configuration method for JBoss Cache instances. </para> <para> - template: + Administrators can use one template for the Lock Manager, another for the Indexer and a third for the data container and then use them in all the workspaces by defining the map of substitution parameters in main configuration file. </para> + <para> + To do this, define <replaceable>${jbosscache-&lt;parameter name&gt;}</replaceable> inside an xml-template and list the correct value in the JCR configuration file (below the "<parameter>jbosscache-configuration</parameter>" entry) as shown below: + </para> + <para> + The xml-template: + </para> -<programlisting>... -&lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; -... -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[... +<clustering mode="replication" clusterName="${jbosscache-cluster-name}"> + <stateRetrieval timeout="20000" fetchInMemoryState="false" /> +...]]></programlisting> <para> - and JCR configuration file: + The JCR configuration file: </para> -<programlisting>... -&lt;property name="jbosscache-configuration" value="jar:/conf/portal/jbosscache-lock.xml" /&gt; -&lt;property name="jbosscache-cluster-name" value="JCR-cluster-locks-db1-ws" /&gt; -... -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[... +<property name="jbosscache-configuration" value="jar:/conf/portal/jbosscache-lock.xml" /> +<property name="jbosscache-cluster-name" value="JCR-cluster-locks-db1-ws" /> +...]]></programlisting> </section> <section id="sect-Reference_Guide-JBoss_Cache_configuration-JGroups_configuration"> <title>JGroups configuration</title> <para> - JGroups is used by JBoss Cache for network communications and transport in clustered environment. If property "jgroups-configuration" is defined in component configuration, it will be injected into the JBoss Cache instance on startup. + JGroups is used by JBoss Cache for network communications and transport in clustered environment. If the property "<parameter>jgroups-configuration</parameter>" is defined in the component configuration, it will be injected into the JBoss Cache instance on startup. </para> -<programlisting>&lt;property name="jgroups-configuration" value="your/path/to/modified-udp.xml" /&gt; +<programlisting language="XML" role="XML"><![CDATA[<property name="jgroups-configuration" value="your/path/to/modified-udp.xml" />]]> </programlisting> <para> - As mentioned above, each component (lock manager, data container and query handler) for each workspace requires it's own clustered environment. Saying with another words, they have their own clusters with unique names. By default each cluster should perform multi-casts on separate port. This configuration leads to great unnecessary overhead on cluster. Thats why JGroups offers multiplexer feature, providing ability to use one single channel for set of clusters. This feature reduces network overheads increasing performance and stability of application. To enable multiplexer stack, You should define appropriate configuration file (upd-mux.xml is pre-shipped one with eXo JCR) and set "jgroups-multiplexer-stack" into "true". + As mentioned previously, each component (lock manager, data container and query handler) for each workspace requires its own clustered environment. </para> + <para> + Each cluster should perform multi-casts on separate port by default. This configuration leads to unnecessary overhead on the cluster. JGroups offers a multiplexer feature providing the ability to use a single channel for a set of clusters. This feature reduces network overheads and increases the performance and stability of an application. + </para> + <para> + To enable the multiplexer stack feature, the appropriate configuration file must be defined and the "<parameter>jgroups-multiplexer-stack</parameter>" should be set to "<replaceable>true</replaceable>". + </para> + <para> + A configuration file named <filename>upd-mux.xml</filename> is pre-shipped with the product. + </para> + <para> + Example: + </para> -<programlisting>&lt;property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /&gt; -&lt;property name="jgroups-multiplexer-stack" value="true" /&gt; -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[<property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> +<property name="jgroups-multiplexer-stack" value="true" />]]></programlisting> </section> - <section id="sect-Reference_Guide-JBoss_Cache_configuration-Shipped_JBoss_Cache_configuration_templates"> - <title>Shipped JBoss Cache configuration templates</title> + <section id="sect-Reference_Guide-JBoss_Cache_configuration-Templates"> + <title>Templates</title> <para> - Exo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR's components. They are situated in application package in /conf/porta/ folder. + The eXo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR components. They are located in the application package in <filename>/conf/portal/</filename> directory. </para> - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Data_container_template"> + <formalpara> <title>Data container template</title> <para> - Data container template is "jbosscache-data.xml" It's + The data container template is called "<filename>jbosscache-data.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; + </formalpara> + <para> + Example: + </para> + <programlistingco> + <areaspec> + <area coords="7" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cluster-name"/> + </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"> - &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="${jbosscache-cluster-name}"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; - &lt;jgroupsConfig multiplexerStack="jcr.stack" /&gt; - &lt;sync /&gt; - &lt;/clustering&gt; + <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> + <stateRetrieval timeout="20000" fetchInMemoryState="false" /> + <jgroupsConfig multiplexerStack="jcr.stack" /> + <sync /> + </clustering> - &lt;!-- Eviction configuration --&gt; - &lt;eviction wakeUpInterval="5000"&gt; - &lt;default algorithmClass="org.jboss.cache.eviction.LRUAlgorithm" + <!-- Eviction configuration --> + <eviction wakeUpInterval="5000"> + <default algorithmClass="org.jboss.cache.eviction.LRUAlgorithm" actionPolicyClass="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.ParentNodeEvictionActionPolicy" - eventQueueSize="1000000"&gt; - &lt;property name="maxNodes" value="1000000" /&gt; - &lt;property name="timeToLive" value="120000" /&gt; - &lt;/default&gt; - &lt;/eviction&gt; -&lt;/jbosscache&gt; -</programlisting> - <table id="tabl-Reference_Guide-Data_container_template-Template_variables"> - <title>Template variables</title> - <tgroup cols="1"> - <thead> - <row> - <entry align="center"> - Variable - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - jbosscache-cluster-name - </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - </para> - </section> + eventQueueSize="1000000"> + <property name="maxNodes" value="1000000" /> + <property name="timeToLive" value="120000" /> + </default> + </eviction> +</jbosscache>]]></programlisting> - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template"> + <calloutlist> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cluster-name"> + <para> + Insert the appropriate cluster name at <replaceable>jbosscache-cluster-name</replaceable> + </para> + </callout> + </calloutlist> + </programlistingco> + + <formalpara> <title>Lock manager template</title> <para> - It's template name is "jbosscache-lock.xml" + The Lock Manager uses a template called "<filename>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; + </formalpara> + <para> + Replace the variables in the example below with the appropriate parameters: + </para> + <programlistingco> + <areaspec> + <area coords="6" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cluster-name1"/> + <area coords="18" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.table.name"/> + <area coords="19" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.table.create"/> + <area coords="20" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.table.drop"/> + <area coords="21" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.table.primarykey"/> + <area coords="22" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.fqn.column"/> + <area coords="23" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.fqn.type"/> + <area coords="24" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.node.column"/> + <area coords="25" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.node.type"/> + <area coords="26" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.parent.column"/> + <area coords="27" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.datasource"/> - &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;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; + </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"> + <preload> + <node fqn="/" /> + </preload> + <loader class="org.jboss.cache.loader.JDBCCacheLoader" async="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} @@ -143,127 +177,110 @@ 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> - <table id="tabl-Reference_Guide-Lock_manager_template-Template_variables"> - <title>Template variables</title> - <tgroup cols="1"> - <thead> - <row> - <entry align="center"> - Variable - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - jbosscache-cluster-name - </entry> - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.table.name - </entry> - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.table.create - </entry> - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.table.drop - </entry> - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.table.primarykey - </entry> - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.fqn.column - </entry> - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.fqn.type - </entry> - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.node.column - </entry> - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.node.type - </entry> - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.parent.column - </entry> - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.datasource - </entry> - </row> - </tbody> - </tgroup> - </table> - </section> + </properties> + </loader> + </loaders> +</jbosscache>]]></programlisting> - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Query_handler_indexer_template"> + <calloutlist> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cluster-name1"> + <para> + <replaceable>jbosscache-cluster-name</replaceable> + </para> + </callout> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.table.name"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.table.name</replaceable> + </para> + </callout> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.table.create"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.table.create</replaceable> + </para> + </callout> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.table.drop"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.table.drop</replaceable> + </para> + </callout> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.table.primarykey"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.table.primarykey</replaceable> + </para> + </callout> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.fqn.column"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.fqn.column</replaceable> + </para> + </callout> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.fqn.type"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.fqn.type</replaceable> + </para> + </callout> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.node.column"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.node.column</replaceable> + </para> + </callout> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.node.type"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.node.type</replaceable> + </para> + </callout> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.parent.column"> + <para> + <replaceable>bosscache-cl-cache.jdbc.parent.column</replaceable> + </para> + </callout> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cl-cache.jdbc.datasource"> + <para> + <replaceable>jbosscache-jbosscache-cl-cache.jdbc.datasource</replaceable> + </para> + </callout> + </calloutlist> + </programlistingco> + + + <formalpara> <title>Query handler (indexer) template</title> <para> - Have a look at "jbosscache-indexer.xml" + The Query Handler uses a template called "<filename>jbosscache-indexer.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; - &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;!-- Eviction configuration --&gt; - &lt;eviction wakeUpInterval="5000"&gt; - &lt;default algorithmClass="org.jboss.cache.eviction.FIFOAlgorithm" eventQueueSize="1000000"&gt; - &lt;property name="maxNodes" value="10000" /&gt; - &lt;property name="minTimeToLive" value="60000" /&gt; - &lt;/default&gt; - &lt;/eviction&gt; -&lt;/jbosscache&gt; -</programlisting> - <table id="tabl-Reference_Guide-Query_handler_indexer_template-Template_variables"> - <title>Template variables</title> - <tgroup cols="1"> - <thead> - <row> - <entry align="center"> - Variable - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - jbosscache-cluster-name - </entry> - </row> - </tbody> - </tgroup> - </table> - </section> + </formalpara> + <programlistingco> + <areaspec> + <area coords="5" id="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cluster-name2"/> + </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> + <!-- Eviction configuration --> + <eviction wakeUpInterval="5000"> + <default algorithmClass="org.jboss.cache.eviction.FIFOAlgorithm" eventQueueSize="1000000"> + <property name="maxNodes" value="10000" /> + <property name="minTimeToLive" value="60000" /> + </default> + </eviction> +</jbosscache>]]></programlisting> + + <calloutlist> + <callout arearefs="Reference_Guide-JBoss_Cache_configuration-Templates-jbosscache-cluster-name2"> + <para> + Replace <replaceable>jbosscache-cluster-name</replaceable> with the appropriate parameter. + </para> + </callout> + </calloutlist> + </programlistingco> + </section> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -8,25 +8,32 @@ <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Introduction"> <title>Introduction</title> <para> - eXo JCR persistent data container can work in two configuration modes: - <itemizedlist> - <listitem> - <para> - <phrase>Multi-database</phrase>: one database for each workspace (used in standalone eXo JCR service mode) - </para> - </listitem> - <listitem> - <para> - <phrase>Single-database</phrase>: all workspaces persisted in one database (used in embedded eXo JCR service mode, e.g. in eXo portal) - </para> - </listitem> - </itemizedlist> + The eXo JCR persistent data container can work in two configuration modes: </para> + <variablelist> + <varlistentry> + <term>Multi-database</term> + <listitem> + <para> + One database is used for each workspace. This mode is used in standalone eXo JCR service mode. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Single-database</term> + <listitem> + <para> + All the workspaces are persisted in one database. This mode is used in embedded eXo JCR service mode, e.g. in eXo portal. + </para> + </listitem> + </varlistentry> + </variablelist> <para> - The data container uses the JDBC driver to communicate with the actual database software, i.e. any JDBC-enabled data storage can be used with eXo JCR implementation. + The data container uses the JDBC driver to communicate with the actual database software. That is, any JDBC-enabled data storage can be used with eXo JCR implementation. </para> <para> - Currently the data container is tested with the following RDBMS: + Currently the data container is tested with the following Rational Database Management Systems (RDBMS): + </para> <itemizedlist> <listitem> <para> @@ -69,34 +76,56 @@ </para> </listitem> </itemizedlist> + + <para> + Each of these database managers supports ANSI SQL standards but each has its own specifics as well. Consequently, each database has its own configuration in eXo JCR as a database dialect parameter. </para> <para> - Each database software supports ANSI SQL standards but has its own specifics too. So, each database has its own configuration in eXo JCR as a database dialect parameter. If you need a more detailed configuration of the database it's possible to do that by editing the metadata SQL-script files. + A more detailed configuration of the database is possible through editing the metadata SQL-script files. </para> <para> - In case the non-ANSI node name is used it's necessary to use a database with MultiLanguage support <!--[TODO link to MultiLanguage] -->. Some JDBC drivers need additional parameters for establishing a Unicode friendly connection. E.g. under mysql it's necessary to add an additional parameter for the JDBC driver at the end of JDBC URL. For instance: <code>jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8<... + If the non-ANSI node name is used, a database with MultiLanguage support is required (refer to <xref linkend="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend"/> for more information). </para> <para> - There are preconfigured configuration files for HSQLDB. Look for these files in /conf/portal and /conf/standalone folders of the jar-file <package>exo.jcr.component.core-XXX.XXX.jar</package> or source-distribution of eXo JCR implementation. + Some JDBC drivers need additional parameters for establishing a Unicode friendly connection. </para> <para> - By default the configuration files are located in service jars <filename>/conf/portal/configuration.xml</filename> (eXo services including JCR Repository Service) and <filename>exo-jcr-config.xml</filename> (repositories configuration). In eXo portal product JCR is configured in portal web application <filename>portal/WEB-INF/conf/jcr/jcr-configuration.xml</filename> (JCR Repository Service and related serivces) and repository-configuration.xml (repositories configuration). + For example, in <application>mysql</application> it is necessary to add a parameter for the JDBC driver to the JDBC URL protocol. For instance: <code>jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8<... </para> <para> - Read more about <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/>. + There are pre-configured configuration files for HSQLDB. These files are stored in the <filename>/conf/portal</filename> and <filename>/conf/standalone</filename> folders of the <filename>exo.jcr.component.core-XXX.XXX.jar</filename> jar-file or source-distribution of the eXo JCR implementation. </para> + <para> + The configuration files are located in service jars <filename>/conf/portal/configuration.xml</filename> (eXo services including JCR Repository Service) and <filename>exo-jcr-config.xml</filename> (repositories configuration) by default. + </para> + <para> + In &PRODUCT; the JCR is configured in portal web application <filename>portal/WEB-INF/conf/jcr/jcr-configuration.xml</filename> (containing JCR Repository Service and related services) and <filename>repository-configuration.xml</filename> (which contains the repositories configuration). + </para> + <para> + Refer to <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/> for more information. + </para> </section> <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Multi_database_Configuration"> <title>Multi-database Configuration</title> <para> - You need to configure each workspace in a repository. You may have each one on different remote servers as far as you need. + Each workspace must be configured in a repository. You may have each one on different remote servers as required. </para> <para> - First of all configure the data containers in the <classname>org.exoplatform.services.naming.InitialContextInitializer</classname> service. It's the JNDI context initializer which registers (binds) naming resources (DataSources) for data containers. + Use the following steps to configure workspaces </para> - <para> - Example (standalone mode, two data containers <parameter>jdbcjcr</parameter> - local HSQLDB, <parameter>jdbcjcr1</parameter> - remote MySQL): + <procedure> + <step> + <para> + Configure the data containers in the <classname>org.exoplatform.services.naming.InitialContextInitializer</classname> service. + </para> + <para> + It's the JNDI context initializer which registers (binds) naming resources (DataSources) for data containers. + </para> + <para> + The following example is in standalone mode with two data containers <parameter>jdbcjcr</parameter> (a local HSQLDB) and <parameter>jdbcjcr1</parameter> (a remote MySQL container): + </para> + <programlisting>&lt;component&gt; &lt;key&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/key&gt; &lt;type&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/type&gt; @@ -167,62 +196,91 @@ &lt;/init-params&gt; &lt;/component&gt; </programlisting> - </para> - <para> - We configure the database connection parameters: - <itemizedlist> - <listitem> - <para> - <parameter>driverClassName</parameter>, e.g. "org.hsqldb.jdbcDriver", "com.mysql.jdbc.Driver", "org.postgresql.Driver" - </para> - </listitem> - <listitem> - <para> - <parameter>url</parameter>, e.g. "jdbc:hsqldb:file:target/temp/data/portal", "jdbc:mysql://exoua.dnsalias.net/jcr" - </para> - </listitem> - <listitem> - <para> - <parameter>username</parameter>, e.g. "sa", "exoadmin" - </para> - </listitem> - <listitem> - <para> - <parameter>password</parameter>, e.g. "", "exo12321" - </para> - </listitem> - </itemizedlist> - </para> - <para> - There can be connection pool configuration parameters (org.apache.commons.dbcp.BasicDataSourceFactory): - <itemizedlist> - <listitem> - <para> - <parameter>maxActive</parameter>, e.g. 50 - </para> - </listitem> - <listitem> - <para> - <parameter>maxIdle</parameter>, e.g. 5 - </para> - </listitem> - <listitem> - <para> - <parameter>initialSize</parameter>, e.g. 5 - </para> - </listitem> - <listitem> - <para> - and other according to <ulink url="http://jakarta.apache.org/commons/dbcp/configuration.html"... DBCP configuration</ulink> - </para> - </listitem> - </itemizedlist> - </para> - <para> - When the data container configuration is done we can configure the repository service. Each workspace will be configured for its own data container. - </para> - <para> - Example (two workspaces <parameter>ws</parameter> - jdbcjcr, <parameter>ws1</parameter> - jdbcjcr1): + </step> + <step> + <para> + Configure the database connection parameters: + </para> + <variablelist> + <varlistentry> + <term>driverClassName</term> + <listitem> + <para> + Some examples are "<literal>org.hsqldb.jdbcDriver</literal>", "<literal>com.mysql.jdbc.Driver</literal>" and "<literal>org.postgresql.Driver</literal>" + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + For example: "<literal>jdbc:hsqldb:file:target/temp/data/portal", "jdbc:mysql://exoua.dnsalias.net/jcr</literal>" + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>username</term> + <listitem> + <para> + Examples are "<literal>sa</literal>", "<literal>exoadmin</literal>" + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>password</term> + <listitem> + <para> + Enter a password. + </para> + </listitem> + </varlistentry> + </variablelist> + </step> + <step> + <para> + Configure the connection pool configuration parameters (<literal>org.apache.commons.dbcp.BasicDataSourceFactory</literal>): + </para> + <variablelist> + <varlistentry> + <term>maxActive</term> + <listitem> + <para> + Enter a maximum period of active time. For example; 50. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>maxIdle</term> + <listitem> + <para> + Enter a period of idle time. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>initialSize</term> + <listitem> + <para> + Define an initial size. For example; 5. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + For information on defining other parameters, refer to the <ulink url="http://jakarta.apache.org/commons/dbcp/configuration.html"... DBCP configuration</ulink> + </para> + </step> + <step> + <para> + When the data container configuration is complete the repository service can be configured. + </para> + <para> + Each workspace will be configured for its own data container. + </para> + <para> + The following example contains two workspaces <parameter>ws</parameter> (<literal>jdbcjcr</literal>) and <parameter>ws1</parameter> (<literal>jdbcjcr1</literal>): + </para> + <programlisting>&lt;workspaces&gt; &lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; @@ -286,40 +344,117 @@ &lt;/workspace&gt; &lt;/workspaces&gt; </programlisting> - <itemizedlist> + + <variablelist> + <varlistentry> + <term>source-name</term> <listitem> <para> - <parameter>source-name</parameter> - a javax.sql.DataSource name configured in InitialContextInitializer component (was <parameter>sourceName</parameter> prior JCR 1.9); + A <literal>javax.sql.DataSource</literal> name configured in the <literal>InitialContextInitializer</literal> component. This was known as <parameter>sourceName</parameter> in JCR version earlier than 1.9. </para> </listitem> + </varlistentry> + <varlistentry> + <term>dialect</term> <listitem> <para> - <parameter>dialect</parameter> - a database dialect, one of "hsqldb", "mysql", "mysql-utf8", "pgsql", "oracle", "oracle-oci", "mssql", "sybase", "derby", "db2", "db2v8" or "auto" for dialect autodetection; + A database dialect. </para> + <itemizedlist> + <listitem> + <para> + "hsqldb" + </para> + </listitem> + <listitem> + <para> + "mysql" + </para> + </listitem> + <listitem> + <para> + "mysql-utf8" + </para> + </listitem> + <listitem> + <para> + "pgsql" + </para> + </listitem> + <listitem> + <para> + "oracle" + </para> + </listitem> + <listitem> + <para> + "oracle-oci" + </para> + </listitem> + <listitem> + <para> + "mssql" + </para> + </listitem> + <listitem> + <para> + "sybase" + </para> + </listitem> + <listitem> + <para> + "derby" + </para> + </listitem> + <listitem> + <para> + "db2" + </para> + </listitem> + <listitem> + <para> + "db2v8" + </para> + </listitem> + </itemizedlist> + <para> + The dialect and also be set to "auto" to allow dialect autodetection. + </para> </listitem> + </varlistentry> + <varlistentry> + <term>multi-db</term> <listitem> <para> - <parameter>multi-db</parameter> - enable multi-database container with this parameter (set value "true"); + This parameter enables multi-database containers when set to "true". </para> </listitem> + </varlistentry> + <varlistentry> + <term>max-buffer-size</term> <listitem> <para> - <parameter>max-buffer-size</parameter> - a threshold (in bytes) after which a javax.jcr.Value content will be swapped to a file in a temporary storage. I.e. swap for pending changes. + A threshold (in bytes) after which a <literal>javax.jcr.Value</literal> content will be swapped to a file in a temporary storage. That is, swap for pending changes. </para> </listitem> + </varlistentry> + <varlistentry> + <term>swap-directory</term> <listitem> <para> - <parameter>swap-directory</parameter> - a path in the file system used to swap the pending changes. + A path in the file system used to swap the pending changes. </para> </listitem> - </itemizedlist> - </para> + </varlistentry> + </variablelist> + </step> + </procedure> <para> - In this way we have configured two workspace which will be persisted in two different databases (ws in HSQLDB, ws1 in MySQL). + The above configures two workspaces which will be persisted in two different databases (<literal>ws</literal> in <literal>HSQLDB</literal> and <literal>ws1</literal> in <literal>MySQL</literal>. </para> <note> <para> - Starting from v.1.9 <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/> parameters supports human-readable formats of values (e.g. 200K - 200 Kbytes, 30m - 30 minutes etc) + JCR version 1.9 supports human-readable parameter formats. See <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/> for more information). </para> </note> </section> @@ -327,10 +462,12 @@ <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Single_database_configuration"> <title>Single-database configuration</title> <para> - It's more simple to configure a single-database data container. We have to configure one naming resource. + Only one naming resource must be set to configure a single database data container. </para> <para> - Example (embedded mode for <parameter>jdbcjcr</parameter> data container): + The following example shows the settings for embedded mode for the <parameter>jdbcjcr</parameter> data container: + </para> + <programlisting>&lt;external-component-plugins&gt; &lt;target-component&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/target-component&gt; &lt;component-plugin&gt; @@ -365,12 +502,14 @@ &lt;/component-plugin&gt; &lt;/external-component-plugins&gt; </programlisting> + + <para> + To configure multiple repository workspaces with one database the "multi-db" parameter must be switched off (set the value to "false"). </para> <para> - And configure repository workspaces in repositories configuration with this one database. Parameter "multi-db" must be switched off (set value "false"). + The following example shows configuration for two workspaces <parameter>ws</parameter> (jdbcjcr) and <parameter>ws1</parameter> (jdbcjcr) which will be persisted in one <application>PostgreSQL</application> database: </para> - <para> - Example (two workspaces <parameter>ws</parameter> - jdbcjcr, <parameter>ws1</parameter> - jdbcjcr): + <programlisting>&lt;workspaces&gt; &lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; @@ -429,36 +568,25 @@ &lt;/workspace&gt; &lt;/workspaces&gt; </programlisting> - </para> - <para> - In this way we have configured two workspaces which will be persisted in one database (PostgreSQL). - </para> + <section id="sect-Reference_Guide-Single_database_configuration-Configuration_without_DataSource"> <title>Configuration without DataSource</title> <para> - Repository configuration without using of the <classname>javax.sql.DataSource</classname> bounded in JNDI. + If you have a dedicated JDBC driver implementation with special features (such as XA transactions and statements/connections pooling) it is possible to configure a repository without using the <classname>javax.sql.DataSource</classname> bound in JNDI. </para> - <para> - This case may be usable if you have a dedicated JDBC driver implementation with special features like XA transactions, statements/connections pooling etc: - <itemizedlist> - <listitem> + <procedure> + <step> <para> - You have to remove the configuration in <classname>InitialContextInitializer</classname> for your database and configure a new one directly in the workspace container. + Remove the configuration in <classname>InitialContextInitializer</classname> for your database and configure a new one directly in the workspace container. </para> - </listitem> - <listitem> + </step> + <step> <para> - Remove parameter "source-name" and add next lines instead. Describe your values for a JDBC driver, database url and username. + Remove the "source-name" parameter and include values for a <emphasis role="bold">JDBC driver</emphasis>, <emphasis role="bold">database url</emphasis> and <emphasis role="bold">username</emphasis> instead. </para> - </listitem> - </itemizedlist> - </para> - <note> - <para> - But be careful in this case JDBC driver should implement and provide connection pooling. Connection pooling is very recommended for use with JCR to prevent a database overload. - </para> - </note> - + </step> + </procedure> + <programlisting>&lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; &lt;properties&gt; @@ -469,6 +597,11 @@ &lt;property name="password" value=""/&gt; ...... </programlisting> + <note> + <para> + Ensure the JDBC driver provides connection pooling. Connection pooling is required for use with JCR to prevent a database overload. + </para> + </note> </section> <section id="sect-Reference_Guide-Single_database_configuration-Dynamic_Workspace_Creation"> @@ -477,20 +610,20 @@ Workspaces can be added dynamically during runtime. </para> <para> - This can be performed in two steps: - <itemizedlist> - <listitem> - <para> - Firstly, <classname>ManageableRepository.configWorkspace(WorkspaceEntry wsConfig)</classname> - register a new configuration in RepositoryContainer and create a WorkspaceContainer. - </para> - </listitem> - <listitem> - <para> - Secondly, the main step, <classname>ManageableRepository.createWorkspace(String workspaceName)</classname> - creation of a new workspace. - </para> - </listitem> - </itemizedlist> + Add new workspaces by: </para> + <procedure> + <step> + <para> + Registering a new configuration in <literal>RepositoryContainer</literal> and create a WorkspaceContainer (<classname>ManageableRepository.configWorkspace(WorkspaceEntry wsConfig)</classname>). + </para> + </step> + <step> + <para> + Creating a new workspace (<classname>ManageableRepository.createWorkspace(String workspaceName)</classname>). + </para> + </step> + </procedure> </section> </section> @@ -498,10 +631,31 @@ <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Simple_and_Complex_queries"> <title>Simple and Complex queries</title> <para> - eXo JCR provides two ways for interact with Database - <classname>JDBCStorageConnection</classname> that uses simple queries and <classname>CQJDBCStorageConection</classname> that uses complex queries for reducing amount of database callings. + eXo JCR provides two ways to interact with a database: </para> + <variablelist> + <varlistentry> + <term>JDBCStorageConnection</term> + <listitem> + <para> + This method uses simple queries. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>CQJDBCStorageConection</term> + <listitem> + <para> + This method uses complex queries which reduce the amount of database calls. + </para> + </listitem> + </varlistentry> + </variablelist> <para> - Simple queries will be used if you chose <classname>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</classname>: + Simple queries will be used if you chose + <classname>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</classname>: + </para> + <programlisting>&lt;workspaces&gt; &lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; @@ -509,9 +663,13 @@ &lt;/workspace&gt; &lt;/worksapces&gt; </programlisting> + <para> + Simple queries are implemented in such a way so as to support as many database dialects as possible. They do not use sub queries, left or right joins. </para> + <para> Complex queries will be used if you chose <classname>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</classname>: + </para> <programlisting>&lt;workspaces&gt; &lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"&gt; @@ -519,27 +677,23 @@ &lt;/workspace&gt; &lt;/worksapces&gt; </programlisting> - </para> <para> - Why we should use a Complex Queries? - <simplelist> - <member>They are optimised to reduce amount of requests to database.</member> - </simplelist> - Why we should use a Simple Queries? - <simplelist> - <member>Simple queries implemented in way to support as many database dialects as possible.</member> - <member>Simple queries do not use sub queries, left or right joins.</member> - </simplelist> + Complex queries are optimized to reduce the number of requests made to a database. </para> - </section> + <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Forse_Query_Hints"> - <title>Forse Query Hints</title> + <title>Force Query Hints</title> <para> - Some databases supports hints to increase query performance (like Oracle, MySQL, etc). eXo JCR have separate Complex Query implementation for Orcale dialect, that uses query hints to increase performance for few important queries. + Some databases (such as <application>Oracle</application> and <application>MySQL</application>)support hints to increase query performanc. </para> <para> - To enable this option put next configuration property: + eXo JCR has a separate Complex Query implementation for the <application>Oracle</application> dialect which uses query hints to increase performance for important queries. + </para> + <para> + To enable this option complete the configuration property as shown below: + </para> + <programlisting>&lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; &lt;properties&gt; @@ -547,16 +701,18 @@ &lt;property name="force.query.hints" value="true" /&gt; ...... </programlisting> - </para> - <para> - Query hints enabled by default. - </para> - <para> - eXo JCR uses query hints only for Complex Query Oracle dialect. For all other dialects this parameter is ignored. - </para> + + <note> + <para> + Query hints are enabled by default. + </para> + <para> + eXo JCR only uses query hints for complex queries using the Oracle dialect. For all other dialects this parameter is ignored. + </para> + </note> </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Notes_for_Microsoft_Windows_users"> +<!--Traiged <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Notes_for_Microsoft_Windows_users"> <title>Notes for Microsoft Windows users</title> <para> The current configuration of eXo JCR uses Apache DBCP connection pool (<classname>org.apache.commons.dbcp.BasicDataSourceFactory</classname>). It's possible to set a big value for maxActive parameter in <filename>configuration.xml</filename>. That means usage of lots of TCP/IP ports from a client machine inside the pool (i.e. JDBC driver). As a result the data container can throw exceptions like "Address already in use". To solve this problem you have to configure the client's machine networking software for the usage of shorter timeouts for opened TCP/IP ports. @@ -585,8 +741,8 @@ "TcpTimedWaitDelay"=dword:0000001e </programlisting> </para> + </section> --> </section> - </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-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/lock-manager-config.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -3,14 +3,10 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "../../../Reference_Guide.ent"> %BOOK_ENTITIES; ]> -<section id="sect-Reference_Guide-LockManager_configuration"> - <title>LockManager configuration</title> - <section id="sect-Reference_Guide-LockManager_configuration-Introduction"> - <title>Introduction</title> +<section id="sect-Reference_Guide-LockManager"> + <title>LockManager</title> + <para> - What LockManager does? - </para> - <para> In common words, LockManager stores lock objects, so it can give Lock object or can release it, etc. </para> <para> @@ -52,7 +48,6 @@ ... &lt;/workspace&gt; </programlisting> - </section> <section id="sect-Reference_Guide-LockManager_configuration-LockManagerImpl"> <title>LockManagerImpl</title> @@ -78,13 +73,14 @@ ... &lt;/properties&gt; </programlisting> - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Configuration"> + <formalpara> <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-Launching_Cluster-Configuring_JCR_to_use_external_configuration"/>. + 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: @@ -112,13 +108,13 @@ <para> See <ulink url="http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader"... </para> - </section> - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JbossCache_Configuraion"> + <formalpara> <title>Simple JbossCache Configuraion</title> <para> First one is - put JbossCache configuraion file path to CacheableLockManagerImpl </para> + </formalpara> <para> <note> <para> @@ -218,13 +214,13 @@ </para> </listitem> </itemizedlist> - </section> - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBossCache_Configuration"> + <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> @@ -347,12 +343,9 @@ &lt;/protocol_stacks&gt; </programlisting> </para> - </section> - - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Data_Types_in_Different_Databases"> - <title>Data Types in Different Databases</title> + <table id="tabl-Reference_Guide-Data_Types_in_Different_Databases-Fqn_type_and_node_type_in_different_databases"> - <title>Fqn type and node type in different databases</title> + <title>Data Types in Different Databases</title> <tgroup cols="3"> <thead> <row> @@ -472,8 +465,6 @@ </table> </section> - </section> - </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -5,31 +5,62 @@ ]> <section id="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend"> <title>Multilanguage support in eXo JCR RDB backend</title> - <section id="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-Intro"> - <title>Intro</title> + <para> - Whenever relational database is used to store multilingual text data of eXo Java Content Repository we need to adapt configuration in order to support UTF-8 encoding. Here is a short HOWTO instruction for several supported RDBMS with examples. + Whenever a relational database is used to store multilingual text data in the eXo Java Content Repository the configuration must be adapted to support UTF-8 encoding. </para> <para> - The configuration file you have to modify: .../webapps/portal/WEB-INF/conf/jcr/repository-configuration.xml + The following sections describe enabling UTF-8 support with various databases. </para> + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-Oracle"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-DB2"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-MySQL"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-PostgreSQL"/> + </para> + </listitem> + </itemizedlist> <note> - <para> - Datasource <parameter>jdbcjcr</parameter> used in examples can be configured via <classname>InitialContextInitializer</classname> component. - </para> + <orderedlist> + <listitem> + <para> + The configuration file to be modified for these changes is:<filename>/webapps/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename> + </para> + </listitem> + <listitem> + <para> + The datasource <parameter>jdbcjcr</parameter> used in the following examples can be configured via the <classname>InitialContextInitializer</classname> component. + </para> + </listitem> + </orderedlist> </note> - </section> - + <section id="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-Oracle"> <title>Oracle</title> <para> - In order to run multilanguage JCR on an Oracle backend Unicode encoding for characters set should be applied to the database. Other Oracle globalization parameters don't make any impact. The only property to modify is <constant>NLS_CHARACTERSET</constant>. + In order to run a multi-language instance of JCR on an Oracle backend Unicode encoding should be applied to the database. Other Oracle globalization parameters will not be effective in this. The property to modify is <constant>NLS_CHARACTERSET</constant>. </para> <para> - We have tested <constant>NLS_CHARACTERSET</constant> = <constant>AL32UTF8</constant> and it's works well for many European and Asian languages. + <constant>NLS_CHARACTERSET</constant> has tested well with many European and Asian languages when set at <constant>AL32UTF8</constant>. </para> <para> - Example of database configuration (used for JCR testing): + The below example of the multi-language database configuration has been used in pre-release JCR testing: + </para> + <programlisting>NLS_LANGUAGE AMERICAN NLS_TERRITORY AMERICA NLS_CURRENCY $ @@ -50,56 +81,57 @@ NLS_NCHAR_CONV_EXCP FALSE NLS_NCHAR_CHARACTERSET AL16UTF16 </programlisting> - </para> + <warning> <para> - JCR 1.12.x doesn't use NVARCHAR columns, so that the value of the parameter NLS_NCHAR_CHARACTERSET does not matter for JCR. + JCR 1.12.<replaceable>x</replaceable> versions do not use <parameter>NVARCHAR</parameter> columns, so the value of the <parameter>NLS_NCHAR_CHARACTERSET</parameter> parameter has no effect. </para> </warning> <para> - Create database with Unicode encoding and use Oracle dialect for the Workspace Container: + To create a database with Unicode encoding using Oracle dialect for the Workspace Container implement the follwing settings: </para> - -<programlisting>&lt;workspace name="collaboration"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr" /&gt; - &lt;property name="dialect" value="oracle" /&gt; - &lt;property name="multi-db" value="false" /&gt; - &lt;property name="max-buffer-size" value="200k" /&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws" /&gt; - &lt;/properties&gt; - ..... -</programlisting> + +<programlisting language="XML" role="XML"><![CDATA[<workspace name="collaboration"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="source-name" value="jdbcjcr" /> + <property name="dialect" value="oracle" /> + <property name="multi-db" value="false" /> + <property name="max-buffer-size" value="200k" /> + <property name="swap-directory" value="target/temp/swap/ws" /> + </properties> + .....]]></programlisting> </section> <section id="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-DB2"> <title>DB2</title> <para> - DB2 Universal Database (DB2 UDB) supports <ulink url="http://publib.boulder.ibm.com/infocenter/db2luw/v9/index.jsp?to... and UTF-16/UCS-2</ulink>. When a Unicode database is created, CHAR, VARCHAR, LONG VARCHAR data are stored in UTF-8 form. It's enough for JCR multi-lingual support. + DB2 Universal Database (DB2 UDB) supports <ulink url="http://publib.boulder.ibm.com/infocenter/db2luw/v9/index.jsp?to... and UTF-16/UCS-2</ulink>. When a Unicode database is created, <parameter>CHAR</parameter>, <parameter>VARCHAR</parameter> and <parameter>LONG VARCHAR</parameter> data are stored in UTF-8 form. </para> <para> - Example of UTF-8 database creation: -<programlisting>DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US -</programlisting> + This enables JCR multi-lingual support. </para> <para> - Create database with UTF-8 encoding and use db2 dialect for Workspace Container on DB2 v.9 and higher: -<programlisting>&lt;workspace name="collaboration"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr" /&gt; - &lt;property name="dialect" value="db2" /&gt; - &lt;property name="multi-db" value="false" /&gt; - &lt;property name="max-buffer-size" value="200k" /&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws" /&gt; - &lt;/properties&gt; - ..... + Below is an example of creating a UTF-8 database using the <parameter>db2</parameter> dialect for a Workspace Container with DB2 version 9 and higher: + </para> + +<programlisting>DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US </programlisting> - </para> + +<programlisting language="XML" role="XML"><![CDATA[<workspace name="collaboration"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="source-name" value="jdbcjcr" /> + <property name="dialect" value="db2" /> + <property name="multi-db" value="false" /> + <property name="max-buffer-size" value="200k" /> + <property name="swap-directory" value="target/temp/swap/ws" /> + </properties> + .....]]></programlisting> + <note> <para> - For DB2 v.8.x support change the property "dialect" to db2v8. + For DB2 version 8.<replaceable>x</replaceable> support change the property "dialect" to db2v8. </para> </note> </section> @@ -107,55 +139,74 @@ <section id="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-MySQL"> <title>MySQL</title> <para> - JCR MySQL-backend requires special dialect <ulink url="http://jira.exoplatform.org/browse/JCR-375">MySQL-UTF8&... to be used for internationalization support. But the database default charset should be latin1 to use limited index space effectively (1000 bytes for MyISAM engine, 767 for InnoDB). If database default charset is multibyte, a JCR database initialization error is thrown concerning index creation failure. In other words JCR can work on any singlebyte default charset of database, with UTF8 supported by MySQL server. But we have tested it only on latin1 database default charset. + USing JCR with a MySQL-backend requires a special dialect <ulink url="http://jira.exoplatform.org/browse/JCR-375">MySQL-UTF8&... to be used for internationalization support. </para> <para> - Repository configuration, workspace container entry example: -<programlisting>&lt;workspace name="collaboration"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr" /&gt; - &lt;property name="dialect" value="mysql-utf8" /&gt; - &lt;property name="multi-db" value="false" /&gt; - &lt;property name="max-buffer-size" value="200k" /&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws" /&gt; - &lt;/properties&gt; - ..... -</programlisting> + The database default charset should be <parameter>latin1</parameter> so as to use limited index space effectively (1000 bytes for an <literal>MyISAM</literal> engine and 767 for <literal>InnoDB</literal>). </para> + <para> + If the database default charset is multibyte, a JCR database initialization error is encountered concerning index creation failure. + </para> + <para> + JCR can work on any singlebyte default charset of database, with UTF8 supported by MySQL server. However it has only been tested using the <parameter>latin1</parameter> charset. + </para> + <para> + An example entry: + </para> + +<programlisting language="XML" role="XML"><![CDATA[<workspace name="collaboration"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="source-name" value="jdbcjcr" /> + <property name="dialect" value="mysql-utf8" /> + <property name="multi-db" value="false" /> + <property name="max-buffer-size" value="200k" /> + <property name="swap-directory" value="target/temp/swap/ws" /> + </properties> + .....]]></programlisting> + </section> <section id="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-PostgreSQL"> <title>PostgreSQL</title> <para> - On PostgreSQL-backend multilingual support can be enabled in <ulink url="http://www.postgresql.org/docs/8.3/interactive/charset.html&quo... ways</ulink>: - <itemizedlist> + Multilingual support can be enabled with a PostgreSQL-backend in <ulink url="http://www.postgresql.org/docs/8.3/interactive/charset.html&quo... ways</ulink>: + </para> + + <orderedlist> <listitem> <para> - Using the locale features of the operating system to provide locale-specific collation order, number formatting, translated messages, and other aspects. UTF-8 is widely used on Linux distributions by default, so it can be useful in such case. + Using the locale features of the operating system to provide locale-specific collation order, number formatting, translated messages, and other aspects. </para> + <para> + UTF-8 is widely used on Linux distributions by default, so it can be useful in such cases. + </para> </listitem> <listitem> <para> - Providing a number of different character sets defined in the PostgreSQL server, including multiple-byte character sets, to support storing text any language, and providing character set translation between client and server. We recommend to use UTF-8 database charset, it will allow any-to-any conversations and make this issue transparent for the JCR. + Providing a number of different character sets defined in the PostgreSQL server, including multiple-byte character sets, to support storing text any language, and providing character set translation between client and server. </para> + <para> + Using UTF-8 database charset is recommended as it will allow any-to-any conversations and make this issue transparent for the JCR. + </para> </listitem> - </itemizedlist> - </para> + </orderedlist> + <para> - Create database with UTF-8 encoding and use PgSQL dialect for Workspace Container: -<programlisting>&lt;workspace name="collaboration"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr" /&gt; - &lt;property name="dialect" value="pgsql" /&gt; - &lt;property name="multi-db" value="false" /&gt; - &lt;property name="max-buffer-size" value="200k" /&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws" /&gt; - &lt;/properties&gt; - ..... -</programlisting> + Example of a database with UTF-8 encoding using PgSQL dialect for the Workspace Container: </para> + +<programlisting language="XML" role="XML"><![CDATA[<workspace name="collaboration"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="source-name" value="jdbcjcr" /> + <property name="dialect" value="pgsql" /> + <property name="multi-db" value="false" /> + <property name="max-buffer-size" value="200k" /> + <property name="swap-directory" value="target/temp/swap/ws" /> + </properties> + .....]]></programlisting> + </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-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/query-handler-config.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -5,8 +5,6 @@ ]> <section id="sect-Reference_Guide-QueryHandler_configuration"> <title>QueryHandler configuration</title> - <section id="sect-Reference_Guide-QueryHandler_configuration-How_does_it_work"> - <title>How does it work?</title> <para> Lets talk about indexing content in cluster. </para> @@ -48,14 +46,15 @@ </imageobject> </mediaobject> </para> - </section> <section id="sect-Reference_Guide-QueryHandler_configuration-Configuration"> <title>Configuration</title> - <section id="sect-Reference_Guide-Configuration-Common_requirements"> + <formalpara> <title>Common requirements</title> <para> Now, lets see what we need to run Search engine in cluster environment. + </para> + </formalpara> <itemizedlist> <listitem> <para> @@ -78,13 +77,13 @@ </para> </listitem> </itemizedlist> - </para> - </section> - <section id="sect-Reference_Guide-Configuration-Query_handler_configuration"> + <formalpara> <title>Query-handler configuration</title> <para> Configuration example: + </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; @@ -165,14 +164,13 @@ </tbody> </tgroup> </table> - </para> - </section> - <section id="sect-Reference_Guide-Configuration-JBoss_Cache_template_configuration"> + <formalpara> <title>JBoss-Cache template configuration</title> <para> JBoss-Cache template configuration for query handler. </para> + </formalpara> <para> jbosscache-indexer.xml <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; @@ -202,7 +200,6 @@ <para> See more about template configurations in <xref linkend="sect-Reference_Guide-JBoss_Cache_configuration"/>. </para> - </section> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -5,41 +5,38 @@ ]> <section id="sect-Reference_Guide-Search_Configuration"> <title>Search Configuration</title> - <section id="sect-Reference_Guide-Search_Configuration-XML_Configuration"> - <title>XML Configuration</title> <para> - JCR index configuration. You can find this file here: <filename>.../portal/WEB-INF/conf/jcr/repository-configuration.xml</filename> + The JCR index configuration file is located at <filename>/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> + <para> + A code example is included below with a list of the configuration parameters shown below that. + </para> -<programlisting>&lt;repository-service default-repository="db1"&gt; - &lt;repositories&gt; - &lt;repository name="db1" system-workspace="ws" default-workspace="ws"&gt; +<programlisting language="XML" role="XML"><![CDATA[<repository-service default-repository="db1"> + <repositories> + <repository name="db1" system-workspace="ws" default-workspace="ws"> .... - &lt;workspaces&gt; - &lt;workspace name="ws"&gt; + <workspaces> + <workspace name="ws"> .... - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="${java.io.tmpdir}/temp/index/db1/ws" /&gt; - &lt;property name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider" /&gt; - &lt;property name="synonymprovider-config-path" value="/synonyms.properties" /&gt; - &lt;property name="indexing-config-path" value="/indexing-configuration.xml" /&gt; - &lt;property name="query-class" value="org.exoplatform.services.jcr.impl.core.query.QueryImpl" /&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; + <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <properties> + <property name="index-dir" value="${java.io.tmpdir}/temp/index/db1/ws" /> + <property name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider" /> + <property name="synonymprovider-config-path" value="/synonyms.properties" /> + <property name="indexing-config-path" value="/indexing-configuration.xml" /> + <property name="query-class" value="org.exoplatform.services.jcr.impl.core.query.QueryImpl" /> + </properties> + </query-handler> ... - &lt;/workspace&gt; - &lt;/workspaces&gt; - &lt;/repository&gt; - &lt;/repositories&gt; -&lt;/repository-service&gt; -</programlisting> - </section> - - <section id="sect-Reference_Guide-Search_Configuration-Configuration_parameters"> + </workspace> + </workspaces> + </repository> + </repositories> +</repository-service>]]></programlisting> + + <table pgwide="0"> <title>Configuration parameters</title> - <table> - <title></title> <tgroup cols="4"> <thead> <row> @@ -53,7 +50,7 @@ Description </entry> <entry> - Since + Version </entry> </row> </thead> @@ -66,7 +63,7 @@ none </entry> <entry> - The location of the index directory. This parameter is mandatory. Up to 1.9 this parameter called "indexDir" + The location of the index directory. This parameter is mandatory. It is called "<literal>indexDir</literal>" in versions prior to version 1.9. </entry> <entry> 1.0 @@ -94,7 +91,7 @@ 100 </entry> <entry> - Minimum number of nodes in an index until segments are merged. + The minimum number of nodes in an index until segments are merged. </entry> <entry> 1.9 @@ -108,7 +105,7 @@ 3 </entry> <entry> - Idle time in seconds until the volatile index part is moved to a persistent index even though minMergeDocs is not reached. + Idle time in seconds until the volatile index part is moved to a persistent index even though <literal>minMergeDocs</literal> is not reached. </entry> <entry> 1.9 @@ -122,7 +119,7 @@ Integer.MAX_VALUE </entry> <entry> - Maximum number of nodes in segments that will be merged. The default value changed in JCR 1.9 to Integer.MAX_VALUE. + The maximum number of nodes in segments that will be merged. The default value changed to <literal>Integer.MAX_VALUE</literal> in JCR version 1.9. </entry> <entry> 1.9 @@ -220,7 +217,7 @@ true </entry> <entry> - If true and the query does not contain an 'order by' clause, result nodes will be in document order. For better performance when queries return a lot of nodes set to 'false'. + If true and the query does not contain an 'order by' clause, result nodes will be in document order. For better performance set to 'false' when queries return many nodes. </entry> <entry> 1.9 @@ -234,7 +231,7 @@ Integer.MAX_VALUE </entry> <entry> - The number of results when a query is executed. Default value: Integer.MAX_VALUE (-&gt; all). + The number of results when a query is executed. Default value: <literal>Integer.MAX_VALUE</literal>. </entry> <entry> 1.9 @@ -248,7 +245,7 @@ DefaultXMLExcerpt </entry> <entry> - The name of the class that implements org.exoplatform.services.jcr.impl.core.query.lucene.ExcerptProvider and should be used for the rep:excerpt() function in a query. + The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core.query.lucene.ExcerptProvider</literal>. This should be used for the <literal>rep:excerpt()</literal> function in a query. </entry> <entry> 1.9 @@ -262,7 +259,7 @@ false </entry> <entry> - If set to true additional information is stored in the index to support highlighting using the rep:excerpt() function. + If set to true additional information is stored in the index to support highlighting using the <literal>rep:excerpt()</literal> function. </entry> <entry> 1.9 @@ -276,7 +273,7 @@ none </entry> <entry> - The name of a class that implements org.exoplatform.services.jcr.impl.core.query.lucene.SynonymProvider. The default value is null (-&gt; not set). + The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core.query.lucene.SynonymProvider</literal>. The default value is null. </entry> <entry> 1.9 @@ -290,7 +287,7 @@ none </entry> <entry> - The path to the synonym provider configuration file. This path interpreted relative to the path parameter. If there is a path element inside the SearchIndex element, then this path is interpreted relative to the root path of the path. Whether this parameter is mandatory depends on the synonym provider implementation. The default value is null (-&gt; not set). + The path to the synonym provider configuration file. This path is interpreted relative to the path parameter. If there is a path element inside the <literal>SearchIndex</literal> element, then this path is interpreted relative to the root path of the path. Whether this parameter is mandatory depends on the synonym provider implementation. The default value is null. </entry> <entry> 1.9 @@ -318,7 +315,7 @@ IndexingConfigurationImpl </entry> <entry> - The name of the class that implements org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfiguration. + The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfiguration</literal>. </entry> <entry> 1.9 @@ -332,7 +329,7 @@ false </entry> <entry> - If set to true a consistency check is performed depending on the parameter forceConsistencyCheck. If set to false no consistency check is performed on startup, even if a redo log had been applied. + If set to true a consistency check is performed depending on the parameter <literal>forceConsistencyCheck</literal>. If set to false no consistency check is performed on startup, even if a redo log had been applied. </entry> <entry> 1.9 @@ -346,7 +343,7 @@ none </entry> <entry> - The name of a class that implements org.exoplatform.services.jcr.impl.core.query.lucene.SpellChecker. + The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core.query.lucene.SpellChecker</literal>. </entry> <entry> 1.9 @@ -374,7 +371,24 @@ false </entry> <entry> - Allows JCR to convert an existing index into the new format. Also it is possible to set this property via system property, for example: -Dupgrade-index=true Indexes before JCR 1.12 will not run with JCR 1.12. Hence you have to run an automatic migration: Start JCR with -Dupgrade-index=true. The old index format is then converted in the new index format. After the conversion the new format is used. On the next start you don't need this option anymore. The old index is replaced and a back conversion is not possible - therefore better take a backup of the index before. (Only for migrations from JCR 1.9 and later.) + <para> + Allows JCR to convert an existing index into the new format. It is also possible to set this property via system property. + </para> + <para> + For example: <command>-Dupgrade-index=true</command> + </para> + <para> + Indexes before JCR 1.12 will not run with JCR 1.12. Hence you have to run an automatic migration: Start JCR with -Dupgrade-index=true. + </para> + <para> + The old index format is then converted in the new index format. After the conversion the new format is used. + </para> + <para> + On subsequent starts this option is no longer needed. The old index is replaced and a back conversion is not possible + </para> + <para> + It is reccommended that a backup of the index be made before conversion. (Only for migrations from JCR 1.9 and later.) + </para> </entry> <entry> 1.12 @@ -397,179 +411,194 @@ </tbody> </tgroup> </table> - </section> - - <section id="sect-Reference_Guide-Search_Configuration-Global_Search_Index"> - <title>Global Search Index</title> - <section id="sect-Reference_Guide-Global_Search_Index-Global_Search_Index_Configuration"> - <title>Global Search Index Configuration</title> - <para> - The global search index is configured in the above-mentioned configuration file (<filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>) in the tag "query-handler". - </para> + + <section id="sect-Reference_Guide-Search_Configuration-Global_Search_Index"> + <title>Global Search Index</title> + <para> + The global search index is configured in the <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the "query-handler" tag. + </para> <programlisting>&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; </programlisting> - <para> - In fact when using Lucene you always should use the same analyzer for indexing and for querying - otherwise the results are unpredictable. You don't have to worry about this, eXo JCR does this for you automatically. If you don't like the StandardAnalyzer configured by default just replace it by your own. - </para> - <para> - If you don't have a handy QueryHandler you will learn how create a customized Handler in 5 minutes. - </para> - </section> - - <section id="sect-Reference_Guide-Global_Search_Index-Customized_Search_Indexes_and_Analyzers"> - <title>Customized Search Indexes and Analyzers</title> - <para> - By default Exo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content: -<programlisting>public TokenStream tokenStream(String fieldName, Reader reader) { + <para> + The same analyzer should always used be for indexing and for querying in Lucene. Results may be unpredictable in other instances. eXo JCR does this automatically. The StandardAnalyzer (configured by default) can, however, be replaced with another. + </para> + <para> + A customized QueryHandler can also be easily created. + </para> + <formalpara> + <title>Customized Search Indexes and Analyzers</title> + <para> + By default eXo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content: + </para> + </formalpara> + <programlistingco> + <areaspec> + <area coords="4" id="Reference_Guide-Search_Configuration-Global_Search_Index-StandardFilter"/> + <area coords="5" id="Reference_Guide-Search_Configuration-Global_Search_Index-LowerCaseFilter"/> + <area coords="6" id="Reference_Guide-Search_Configuration-Global_Search_Index-StopFilter"/> + </areaspec> + +<programlisting language="Java" role="JAVA"><![CDATA[public TokenStream tokenStream(String fieldName, Reader reader) { StandardTokenizer tokenStream = new StandardTokenizer(reader, replaceInvalidAcronym); tokenStream.setMaxTokenLength(maxTokenLength); TokenStream result = new StandardFilter(tokenStream); result = new LowerCaseFilter(result); result = new StopFilter(result, stopSet); return result; - } -</programlisting> - <itemizedlist> - <listitem> + }]]></programlisting> + <calloutlist> + <callout arearefs="Reference_Guide-Search_Configuration-Global_Search_Index-StandardFilter"> <para> - The first one (StandardFilter) removes 's (as 's in "Peter's") from the end of words and removes dots from acronyms. + The first filter (StandardFilter) removes possessive apostrophes (<emphasis role="bold">'s</emphasis>) from the end of words and removes periods (<emphasis role="bold">.</emphasis>) from acronyms. </para> - </listitem> - <listitem> + </callout> + <callout arearefs="Reference_Guide-Search_Configuration-Global_Search_Index-LowerCaseFilter"> <para> - The second one (LowerCaseFilter) normalizes token text to lower case. + The second filter (LowerCaseFilter) normalizes token text to lower case. </para> - </listitem> - <listitem> - <para> - The last one (StopFilter) removes stop words from a token stream. The stop set is defined in the analyzer. - </para> - </listitem> - </itemizedlist> + </callout> + <callout arearefs="Reference_Guide-Search_Configuration-Global_Search_Index-StopFilter"> + <para> + The last filter (StopFilter) removes stop words from a token stream. The stop set is defined in the analyzer. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Additional filters can be used in specific cases. The <phrase>ISOLatin1AccentFilter</phrase> filter, for example, which replaces accented characters in the ISO Latin 1 character set (ISO-8859-1) by their unaccented equivalents. </para> <para> - For specific cases, you may wish to use additional filters like <phrase>ISOLatin1AccentFilter</phrase>, which replaces accented characters in the ISO Latin 1 character set (ISO-8859-1) by their unaccented equivalents. + The <phrase>ISOLatin1AccentFilter</phrase> is not present in the current Lucene version used by Exo. </para> <para> - In order to use a different filter, you have to create a new analyzer, and a new search index to use the analyzer. You put it in a jar, which is deployed with your application. + In order to use a different filter, a new analyzer must be created, as well as new search index to use the analyzer. These are packaged into a jar file, which is then deployed with the application. </para> - <section id="sect-Reference_Guide-Customized_Search_Indexes_and_Analyzers-Create_the_filter"> - <title>Create the filter</title> + + <procedure> + <title>Create a new filter, analyzer and search index</title> + <step> + <para> + Create a new filter with the method: + </para> +<programlisting language="Java" role="JAVA">public final Token next(final Token reusableToken) throws java.io.IOException +</programlisting> + <para> + This defines how characters are read and used by the filter. + </para> + </step> + <step> <para> - The ISOLatin1AccentFilter is not present in the current Lucene version used by Exo. You can use the attached file. You can also create your own filter, the relevant method is -<programlisting>public final Token next(final Token reusableToken) throws java.io.IOException -</programlisting> - which defines how chars are read and used by the filter. + Create the analyzer. </para> - </section> - - <section id="sect-Reference_Guide-Customized_Search_Indexes_and_Analyzers-Create_the_analyzer"> - <title>Create the analyzer</title> <para> - The analyzer have to extends org.apache.lucene.analysis.standard.StandardAnalyzer, and overload the method -<programlisting>public TokenStream tokenStream(String fieldName, Reader reader) -</programlisting> - to put your own filters. You can have a glance at the example analyzer attached to this article. + The analyzer must extend <literal>org.apache.lucene.analysis.standard.StandardAnalyzer</literal> and overload the method. </para> - </section> - - <section id="sect-Reference_Guide-Customized_Search_Indexes_and_Analyzers-Create_the_search_index"> - <title>Create the search index</title> <para> - Now, we have the analyzer, we have to write the SearchIndex, which will use the analyzer. Your have to extends org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex. You have to write the constructor, to set the right analyzer, and the method -<programlisting>public Analyzer getAnalyzer() { + Use the following to use new filters. + </para> + +<programlisting language="Java" role="JAVA">public TokenStream tokenStream(String fieldName, Reader reader) +</programlisting> + + + </step> + <step> + <para> + To create the new search index, extend <literal>org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex</literal> and write the constructor to set the correct analyzer. + </para> + <para> + Use the method below to return your analyzer: + </para> + +<programlisting language="Java" role="JAVA">public Analyzer getAnalyzer() { return MyAnalyzer; } </programlisting> - to return your analyzer. You can see the attached SearchIndex. + + </step> + </procedure> + + <note> + <para> + In JCR version 1.12 (and later) the Analyzer can be directly set in the configuration. For users with this version the creation of a new SearchIndex for new Analyzers is redundant. </para> - <note> - <para> - Since 1.12 version we can set Analyzer directly in configuration. So, creation new SearchIndex only for new Analyzer is redundant. - </para> - </note> - </section> + </note> - <section id="sect-Reference_Guide-Customized_Search_Indexes_and_Analyzers-Configure_your_application_to_use_your_SearchIndex"> - <title>Configure your application to use your SearchIndex</title> - <para> - In <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>, you have to replace each + <para> + To configure an application to use a new <literal>SearchIndex</literal> replace the following code: + </para> + <programlisting>&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; </programlisting> - by your own class -<programlisting>&lt;query-handler class="mypackage.indexation.MySearchIndex"&gt; + + <para> + ...in <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename> with the new class + </para> + +<programlisting>&lt;query-handler class="<replaceable>mypackage.indexation.MySearchIndex</replaceable>"&gt; </programlisting> - </para> - </section> - <section id="sect-Reference_Guide-Customized_Search_Indexes_and_Analyzers-Configure_your_application_to_use_your_Analyzer"> - <title>Configure your application to use your Analyzer</title> - <para> - In <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>, you have to add parameter "analyzer" to each query-handler config: -<programlisting>&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; + <para> + To configure an application to use a new Analyzer add the "<parameter>analyzer</parameter>" parameter to each query-handler configuration in <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>: + </para> + +<programlisting language="Java" role="JAVA"><![CDATA[<query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <properties> ... - &lt;property name="analyzer" value="org.exoplatform.services.jcr.impl.core.MyAnalyzer"/&gt; + <property name="analyzer" value="org.exoplatform.services.jcr.impl.core.MyAnalyzer"/> ... - &lt;/properties&gt; -&lt;/query-handler&gt; -</programlisting> - </para> + </properties> +</query-handler>]]></programlisting> + <para> - When you start exo, your SearchIndex will start to index contents with the specified filters. + The new <literal>SearchIndex</literal> will start to index contents with the specified filters when the JCR is next started. </para> - </section> </section> - </section> - - <section id="sect-Reference_Guide-Search_Configuration-Index_Adjustments"> - <title>Index Adjustments</title> <section id="sect-Reference_Guide-Index_Adjustments-IndexingConfiguration"> <title>IndexingConfiguration</title> - <para> - Starting with version 1.9, the default search index implementation in JCR allows you to control which properties of a node are indexed. You also can define different analyzers for different nodes. - </para> - <para> - The configuration parameter is called indexingConfiguration and per default is not set. This means all properties of a node are indexed. - </para> - <para> - If you wish to configure the indexing behavior you need to add a parameter to the query-handler element in your configuration file. - </para> + <para> + From version 1.9, the default search index implementation in JCR allows user control over which properties of a node are indexed. Different analyzers can also be set for different nodes. + </para> + <para> + The configuration parameter is called <literal>indexingConfiguration</literal> and is not set by default. This means all properties of a node are indexed. + </para> + <para> + To configure the indexing behavior add a parameter to the query-handler element in your configuration file. + </para> <programlisting>&lt;param name="indexing-configuration-path" value="/indexing_configuration.xml"/&gt; </programlisting> - </section> + - <section id="sect-Reference_Guide-Index_Adjustments-Index_rules"> - <title>Index rules</title> - <section id="sect-Reference_Guide-Index_rules-Node_Scope_Limit"> - <title>Node Scope Limit</title> + <formalpara> + <title>Node Scope Limit</title> + <para> + The node scope can be limited so that only certain properties of a node type are indexed. This can optimize the index size. + </para> + </formalpara> <para> - To optimize the index size you can limit the node scope so that <phrase>only certain properties</phrase> of a node type are indexed. + With the below configuration only properties named <parameter>Text</parameter> are indexed for <parameter>nt:unstructured</parameter> node types. This configuration also applies to all nodes whose type extends from <parameter>nt:unstructured</parameter>. </para> - <para> - With the below configuration only properties named Text are indexed for nodes of type nt:unstructured. This configuration also applies to all nodes whose type extends from nt:unstructured. - </para> -<programlisting>&lt;?xml version="1.0"?&gt; -&lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; -&lt;configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; - &lt;index-rule nodeType="nt:unstructured"&gt; - &lt;property&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; -&lt;/configuration&gt; -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"> +<configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"> + <index-rule nodeType="nt:unstructured"> + <property>Text</property> + </index-rule> +</configuration>]]></programlisting> + <note> + <title>Namespace Prefixes</title> + <para> + The <phrase>namespace prefixes</phrase> must be declared throughout the XML file in the configuration element that is being used. + </para> + </note> + <para> - Please note that you have to declare the <phrase>namespace prefixes</phrase> in the configuration element that you are using throughout the XML file! - </para> - </section> - - <section id="sect-Reference_Guide-Index_rules-Index_Boost_Value"> - <title>Index Boost Value</title> - <para> It is also possible to configure a <phrase>boost value</phrase> for the nodes that match the index rule. The default boost value is 1.0. Higher boost values (a reasonable range is 1.0 - 5.0) will yield a higher score value and appear as more relevant. </para> @@ -584,6 +613,8 @@ </programlisting> <para> If you do not wish to boost the complete node but only certain properties you can also provide a boost value for the listed properties: + </para> + <programlisting>&lt;?xml version="1.0"?&gt; &lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; &lt;configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; @@ -593,230 +624,251 @@ &lt;/index-rule&gt; &lt;/configuration&gt; </programlisting> - </para> - </section> - - <section id="sect-Reference_Guide-Index_rules-Conditional_Index_Rules"> + + <formalpara> <title>Conditional Index Rules</title> <para> You may also add a <phrase>condition</phrase> to the index rule and have multiple rules with the same nodeType. The first index rule that matches will apply and all remaining ones are ignored: -<programlisting>&lt;?xml version="1.0"?&gt; -&lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; -&lt;configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; - &lt;index-rule nodeType="nt:unstructured" - boost="2.0" - condition="@priority = 'high'"&gt; - &lt;property&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; - &lt;index-rule nodeType="nt:unstructured"&gt; - &lt;property&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; -&lt;/configuration&gt; -</programlisting> </para> - <para> - In the above example the first rule only applies if the nt:unstructured node has a priority property with a value 'high'. The condition syntax supports only the equals operator and a string literal. - </para> - <para> - You may also reference properties in the condition that are not on the current node: -<programlisting>&lt;?xml version="1.0"?&gt; -&lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; -&lt;configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; - &lt;index-rule nodeType="nt:unstructured" + </formalpara> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"> +<configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"> + <index-rule nodeType="nt:unstructured" boost="2.0" - condition="ancestor::*/@priority = 'high'"&gt; - &lt;property&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; - &lt;index-rule nodeType="nt:unstructured" + condition="@priority = 'high'"> + <property>Text</property> + </index-rule> + <index-rule nodeType="nt:unstructured"> + <property>Text</property> + </index-rule> +</configuration>]]></programlisting> + + <para> + In the above example the first rule only applies if the <parameter>nt:unstructured</parameter> node has a priority property with a value '<parameter>high</parameter>'. The condition syntax only supports the equals operator and a string literal. + </para> + <para> + Properties may also be referenced on the condition that are not on the current node: + </para> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"> +<configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"> + <index-rule nodeType="nt:unstructured" + boost="2.0" + condition="ancestor::*/@priority = 'high'"> + <property>Text</property> + </index-rule> + <index-rule nodeType="nt:unstructured" boost="0.5" - condition="parent::foo/@priority = 'low'"&gt; - &lt;property&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; - &lt;index-rule nodeType="nt:unstructured" + condition="parent::foo/@priority = 'low'"> + <property>Text</property> + </index-rule> + <index-rule nodeType="nt:unstructured" boost="1.5" - condition="bar/@priority = 'medium'"&gt; - &lt;property&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; - &lt;index-rule nodeType="nt:unstructured"&gt; - &lt;property&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; -&lt;/configuration&gt; -</programlisting> - </para> - <para> - The indexing configuration also allows you to specify the type of a node in the condition. Please note however that the type match must be exact. It does not consider sub types of the specified node type. - </para> - -<programlisting>&lt;?xml version="1.0"?&gt; -&lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; -&lt;configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; - &lt;index-rule nodeType="nt:unstructured" + condition="bar/@priority = 'medium'"> + <property>Text</property> + </index-rule> + <index-rule nodeType="nt:unstructured"> + <property>Text</property> + </index-rule> +</configuration>]]></programlisting> + + <para> + The indexing configuration allows the type of a node in the condition to be specified. Please note however that the type match must be exact. It does not consider sub types of the specified node type. + </para> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"> +<configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"> + <index-rule nodeType="nt:unstructured" boost="2.0" - condition="element(*, nt:unstructured)/@priority = 'high'"&gt; - &lt;property&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; -&lt;/configuration&gt; -</programlisting> - </section> - - <section id="sect-Reference_Guide-Index_rules-Exclusion_from_the_Node_Scope_Index"> + condition="element(*, nt:unstructured)/@priority = 'high'"> + <property>Text</property> + </index-rule> +</configuration>]]></programlisting> + + <formalpara> <title>Exclusion from the Node Scope Index</title> <para> - Per default all configured properties are fulltext indexed if they are of type STRING and included in the node scope index. A node scope search finds normally all nodes of an index. That is, the select jcr:contains(., 'foo') returns all nodes that have a string property containing the word 'foo'. You can exclude explicitly a property from the node scope index: -<programlisting>&lt;?xml version="1.0"?&gt; -&lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; -&lt;configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; - &lt;index-rule nodeType="nt:unstructured"&gt; - &lt;property nodeScopeIndex="false"&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; -&lt;/configuration&gt; -</programlisting> + All configured properties are fulltext indexed by default (if they are of type STRING and included in the node scope index). </para> - </section> - - </section> - - <section id="sect-Reference_Guide-Index_Adjustments-Index_Aggregates"> - <title>Index Aggregates</title> + </formalpara> <para> - Sometimes it is useful to include the contents of descendant nodes into a single node to easier search on content that is scattered across multiple nodes. + A node scope search normally finds all nodes of an index. That is to say; <literal>jcr:contains(., 'foo')</literal> returns all nodes that have a string property containing the word '<replaceable>foo</replaceable>'. </para> <para> - JCR allows you to define index aggregates based on relative path patterns and primary node types. + Properties can be explicitly excluded from the node scope index with: </para> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"> +<configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"> + <index-rule nodeType="nt:unstructured"> + <property nodeScopeIndex="false">Text</property> + </index-rule> +</configuration>]]></programlisting> + + <formalpara> + <title>Index Aggregates</title> + <para> + Sometimes it is useful to include the contents of descendant nodes into a single node to more easily search on content that is scattered across multiple nodes. + </para> + </formalpara> <para> - The following example creates an index aggregate on nt:file that includes the content of the jcr:content node: -<programlisting>&lt;?xml version="1.0"?&gt; -&lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; -&lt;configuration xmlns:jcr="http://www.jcp.org/jcr/1.0" - xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; - &lt;aggregate primaryType="nt:file"&gt; - &lt;include&gt;jcr:content&lt;/include&gt; - &lt;/aggregate&gt; -&lt;/configuration&gt; -</programlisting> + JCR allows the definition of index aggregates based on relative path patterns and primary node types. </para> <para> - You can also restrict the included nodes to a certain type: -<programlisting>&lt;?xml version="1.0"?&gt; -&lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; -&lt;configuration xmlns:jcr="http://www.jcp.org/jcr/1.0" - xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; - &lt;aggregate primaryType="nt:file"&gt; - &lt;include primaryType="nt:resource"&gt;jcr:content&lt;/include&gt; - &lt;/aggregate&gt; -&lt;/configuration&gt; -</programlisting> + The following example creates an index aggregate on <literal>nt:file</literal> that includes the content of the jcr:content node: </para> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"> +<configuration xmlns:jcr="http://www.jcp.org/jcr/1.0" + xmlns:nt="http://www.jcp.org/jcr/nt/1.0"> + <aggregate primaryType="nt:file"> + <include>jcr:content</include> + </aggregate> +</configuration>]]></programlisting> + <para> - You may also use the * to match all child nodes: -<programlisting>&lt;?xml version="1.0"?&gt; -&lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; -&lt;configuration xmlns:jcr="http://www.jcp.org/jcr/1.0" - xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; - &lt;aggregate primaryType="nt:file"&gt;http://wiki.exoplatform.com/xwiki/... - &lt;include primaryType="nt:resource"&gt;*&lt;/include&gt; - &lt;/aggregate&gt; -&lt;/configuration&gt; -</programlisting> + Included nodes can also be restricted to a certain type: </para> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"> +<configuration xmlns:jcr="http://www.jcp.org/jcr/1.0" + xmlns:nt="http://www.jcp.org/jcr/nt/1.0"> + <aggregate primaryType="nt:file"> + <include primaryType="nt:resource">jcr:content</include> + </aggregate> +</configuration>]]></programlisting> + <para> - If you wish to include nodes up to a certain depth below the current node you can add multiple include elements. E.g. the nt:file node may contain a complete XML document under jcr:content: -<programlisting>&lt;?xml version="1.0"?&gt; -&lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; -&lt;configuration xmlns:jcr="http://www.jcp.org/jcr/1.0" - xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; - &lt;aggregate primaryType="nt:file"&gt; - &lt;include&gt;*&lt;/include&gt; - &lt;include&gt;*/*&lt;/include&gt; - &lt;include&gt;*/*/*&lt;/include&gt; - &lt;/aggregate&gt; -&lt;/configuration&gt; -</programlisting> + The <emphasis role="bold">*</emphasis> wildcard can be used to match all child nodes: </para> - </section> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"> +<configuration xmlns:jcr="http://www.jcp.org/jcr/1.0" + xmlns:nt="http://www.jcp.org/jcr/nt/1.0"> + <aggregate primaryType="nt:file">http://wiki.exoplatform.com/xwiki/bin/... + <include primaryType="nt:resource">*</include> + </aggregate> +</configuration>]]></programlisting> + + <para> + Nodes to a certain depth below the current node can be included by adding multiple include elements. The <parameter>nt:file</parameter> node may contain a complete XML document under jcr:content for example: + </para> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"> +<configuration xmlns:jcr="http://www.jcp.org/jcr/1.0" + xmlns:nt="http://www.jcp.org/jcr/nt/1.0"> + <aggregate primaryType="nt:file"> + <include>*</include> + <include>*/*</include> + <include>*/*/*</include> + </aggregate> +</configuration>]]></programlisting> + - <section id="sect-Reference_Guide-Index_Adjustments-Property_Level_Analyzers"> + <formalpara> <title>Property-Level Analyzers</title> - <section id="sect-Reference_Guide-Property_Level_Analyzers-Example"> - <title>Example</title> + <para> + How a property has to be analyzed can be defined in the following configuration section. If there is an analyzer configuration for a property, this analyzer is used for indexing and searching of this property. For example: + </para> + </formalpara> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"> +<configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"> + <analyzers> + <analyzer class="org.apache.lucene.analysis.KeywordAnalyzer"> + <property>mytext</property> + </analyzer> + <analyzer class="org.apache.lucene.analysis.WhitespaceAnalyzer"> + <property>mytext2</property> + </analyzer> + </analyzers> +</configuration>]]></programlisting> + + <para> + The configuration above sets Lucene <emphasis role="bold">KeywordAnalyzer</emphasis> to index and search the property "<replaceable>mytext</replaceable>" across the entire workspace while the "<replaceable>mytext2</replaceable>" property is searched with the <emphasis role="bold">WhitespaceAnalyzer</emphasis>. + </para> + <para> + The <emphasis role="bold">WhitespaceAnalyzer</emphasis> tokenizes a property, the <emphasis role="bold">KeywordAnalyzer</emphasis> takes the property as a whole. + </para> + <para> + Using different analyzers for different languages can be particularly useful. + </para> + + <formalpara> + <title>Characteristics of Node Scope Searches</title> <para> - In this configuration section you define how a property has to be analyzed. If there is an analyzer configuration for a property, this analyzer is used for indexing and searching of this property. For example: -<programlisting>&lt;?xml version="1.0"?&gt; -&lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.0.dtd"&gt; -&lt;configuration xmlns:nt="http://www.jcp.org/jcr/nt/1.0"&gt; - &lt;analyzers&gt; - &lt;analyzer class="org.apache.lucene.analysis.KeywordAnalyzer"&gt; - &lt;property&gt;mytext&lt;/property&gt; - &lt;/analyzer&gt; - &lt;analyzer class="org.apache.lucene.analysis.WhitespaceAnalyzer"&gt; - &lt;property&gt;mytext2&lt;/property&gt; - &lt;/analyzer&gt; - &lt;/analyzers&gt; -&lt;/configuration&gt; -</programlisting> + Unexpected behavior may be encountered when using analyzers to search within a <emphasis>property</emphasis> compared to searching within a <emphasis>node scope</emphasis>. This is because the node scope always uses the global analyzer. </para> + </formalpara> <para> - The configuration above means that the property "mytext" for the entire workspace is indexed (and searched) with the Lucene KeywordAnalyzer, and property "mytext2" with the WhitespaceAnalyzer. Using different analyzers for different languages is particularly useful. + For example: the property "<parameter>mytext</parameter>" contains the text; "<emphasis>testing my analyzers</emphasis>" but no analyzers have been configured for this property (and the default analyzer in SerachIndex has not been changed). </para> <para> - The WhitespaceAnalyzer tokenizes a property, the KeywordAnalyzer takes the property as a whole. + If the query is: </para> - </section> - - <section id="sect-Reference_Guide-Property_Level_Analyzers-Characteristics_of_Node_Scope_Searches"> - <title>Characteristics of Node Scope Searches</title> +<programlisting>xpath = "//*[jcr:contains(mytext,'analyzer')]" +</programlisting> + <para> - When using analyzers, you may encounter an unexpected behavior when searching within a property compared to searching within a node scope. The reason is that the node scope always uses the global analyzer. + The <literal>xpath</literal> does not return a result in the node with the property above and default analyzers. </para> <para> - Let's suppose that the property "mytext" contains the text : "testing my analyzers" and that you haven't configured any analyzers for the property "mytext" (and not changed the default analyzer in SearchIndex). + Also, if a search is done on the node scope as follows: </para> +<programlisting>xpath = "//*[jcr:contains(.,'analyzer')]" +</programlisting> <para> - If your query is for example: -<programlisting>xpath = "//*[jcr:contains(mytext,'analyzer')]" -</programlisting> + No result will be returned. </para> <para> - This xpath does not return a hit in the node with the property above and default analyzers. + Only specific analyzers can be set on a node property, and the node scope indexing and analyzing is always done with the globally defined analyzer in the SearchIndex element. </para> <para> - Also a search on the node scope -<programlisting>xpath = "//*[jcr:contains(.,'analyzer')]" -</programlisting> - won't give a hit. Realize, that you can only set specific analyzers on a node property, and that the node scope indexing/analyzing is always done with the globally defined analyzer in the SearchIndex element. + If the analyzer used to index the "mytext" property above is changed to: </para> - <para> - Now, if you change the analyzer used to index the "mytext" property above to <programlisting>&lt;analyzer class="org.apache.lucene.analysis.Analyzer.GermanAnalyzer"&gt; &lt;property&gt;mytext&lt;/property&gt; &lt;/analyzer&gt; </programlisting> - and you do the same search again, then for + <para> + The search below would return a result because of the word stemming (analyzers - analyzer). + </para> + <programlisting>xpath = "//*[jcr:contains(mytext,'analyzer')]" </programlisting> - you would get a hit because of the word stemming (analyzers - analyzer). + + <para> + The second search in the example: </para> - <para> - The other search, + <programlisting>xpath = "//*[jcr:contains(.,'analyzer')]" </programlisting> - still would not give a result, since the node scope is indexed with the global analyzer, which in this case does not take into account any word stemming. + <para> + Would still not give a result, since the node scope is indexed with the global analyzer, which in this case does not take into account any word stemming. </para> + <para> - In conclusion, be aware that when using analyzers for specific properties, you might find a hit in a property for some search text, and you do not find a hit with the same search text in the node scope of the property! + Be aware that when using analyzers for specific properties, a result may be found in a property for certain search text, but the same search text in the node scope of the property may not find a result. </para> <note> <para> - Both index rules and index aggregates influence how content is indexed in JCR. If you change the configuration the existing content is not automatically re-indexed according to the new rules. You therefore have to manually re-index the content when you change the configuration! + Both index rules and index aggregates influence how content is indexed in JCR. If the configuration is changed, the existing content is not automatically re-indexed according to the new rules. </para> + <para> + Content must be manually re-indexed when the configuration is changed. + </para> </note> </section> - - </section> - </section> -</section> - Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -6,19 +6,19 @@ <chapter id="chap-Reference_Guide-eXoJCR"> <title>eXoJCR</title> <xi:include href="JCR/intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="JCR/architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- common configs --><xi:include href="JCR/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- Triaged <xi:include href="JCR/architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> +<!-- common configs --><xi:include href="JCR/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/jdbc-data-container-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/external-value-storages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/search-configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/multilanguage-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/configuration-persister.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- cluster configs --><xi:include href="JCR/cluster-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- cluster configs --><xi:include href="JCR/cluster-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/jbosscache-configuration-templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/lock-manager-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/query-handler-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/jbossts-transaction-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/transaction-manager-lookup.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- statistics configs --><xi:include href="JCR/statistics.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- statistics configs --><xi:include href="JCR/statistics.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </chapter> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -460,7 +460,7 @@ </step> <step> <para> - Copy the <filename>GATEIN_SSO_HOME/josso/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename> file into the <filename>gatein.ear/02portal.war/WEB-INF/classes</filename> directory. + Copy the <filename>GATEIN_SSO_HOME/josso/gatein.ear/02portal.war/WEB-INF/classes/josso-agent-config.xml</filename> file into the <filename>gatein.ear/02portal.war/WEB-INF/classes</filename> directory. </para> </step> <step> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Introduction.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Introduction.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Introduction.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -26,7 +26,7 @@ <term>Tecnical documentation</term> <listitem> <para> - Other technical documentation, including an <emphasis role="bold">Installation Guide</emphasis>, and a <emphasis role="bold">User Guide</emphasis> can be found at <ulink type="http" url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Platform_Port... + Other technical documentation, including an <emphasis role="bold">Installation Guide</emphasis>, and a <emphasis role="bold">User Guide</emphasis> can be found at <ulink type="http" url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platfo... </para> </listitem> </varlistentry> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -118,9 +118,9 @@ <listitem> <para> This file describes the layout and portlets that will be shown on all pages. Usually the layout contains the banner, footer, menu and breadcrumbs portlets. &PRODUCT; is extremely configurable as every view element (even the banner and footer) is a portlet. - </para> - + </para><!-- <programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?> + <portal-config> <portal-name>classic</portal-name> <locale>en</locale> @@ -154,6 +154,8 @@ </portal-layout> </portal-config>]]></programlisting> +--> +<programlisting role="XML" language="XML"><xi:include href="portal.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting> <para> It is also possible to apply a nested container that can also contain portlets. Row, column or tab containers are then responsible for the layout of their child portlets. @@ -515,7 +517,7 @@ The group navigation menu is configured by three XML files (<filename>navigation.xml</filename>, <filename>pages.xml</filename> and <filename>portlet-preferences.xml</filename>). The syntax used in these files is the same as those covered in <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation" />. </para> <para> - They are located in <filename>portal.war/WEB-INF/conf/portal/group<replaceable>/group-name-path/</replaceable></filename> directory (For example; <filename>portal.war/WEB-INF/conf/portal/group/platform/administrators/</filename>). + They are located in <filename>02portal.war/WEB-INF/conf/portal/group<replaceable>/group-name-path/</replaceable></filename> directory (For example; <filename>02portal.war/WEB-INF/conf/portal/group/platform/administrators/</filename>). </para> </section> @@ -525,15 +527,15 @@ User navigation is the set of nodes and pages that are owned by a user. They are part of the user's dashboard. </para> <para> - Three files configure the user navigation (<filename>navigation.xml</filename>, <filename>pages.xml</filename> and <filename>portlet-preferences.xml</filename>). They are located in the directory "<filename>portal.war/WEB-INF/conf/portal/users/{userName}</filename>". + Three files configure the user navigation (<filename>navigation.xml</filename>, <filename>pages.xml</filename> and <filename>portlet-preferences.xml</filename>). They are located in the directory "<filename>02portal.war/WEB-INF/conf/portal/users/{userName}</filename>". </para> <para> - This directory also contains a <filename>gadgets.xml</filename> file (formerly called <filename>widgets.xml</filename>). This file defines the gadgets located in the user's workspace. + This <filename>eXoGadgets.war/WEB-INF/</filename>directory also contains a <filename>gadgets.xml</filename> file (formerly called <filename>widgets.xml</filename>). This file defines the gadgets located in the user's workspace. </para> <para> The user's workspace is located at the left hand side of the page and access is restricted to some privileged users, see <xref linkend="sect-Reference_Guide-Predefined_User_Configuration" /> </para> - + <!-- <programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?> <widgets> <owner-type>user</owner-type> @@ -568,12 +570,14 @@ </container> </widgets>]]></programlisting> +--> + <programlisting role="XML" language="XML"><xi:include href="gadgets.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting> <!-- <para> Note that when you develop a portal, we advise you to use the XML instead of the User Interface as XML will allow you to provide a preconfigured package to your customer. But as each time you start the server the first time, the XML files are stored in the JCR, it will be necessary to remove the database (the jcr leverages a database). During the development phase using tomcat it simply means to delete the directory: exo-tomcat/temp </para> --> </section> - + <!-- <section id="sect-Reference_Guide-Portal_Navigation_Configuration-Tips"> <title>Tips</title> <section id="sect-Reference_Guide-Tips-Direct_External_Links"> @@ -585,8 +589,8 @@ <varlistentry> <term>pages.xml</term> <listitem> - <para> - + <para>--> + <!-- <programlisting language="XML" role="XML"><![CDATA[<page> <owner-type>portal</owner-type> <owner-id>website</owner-id> @@ -594,21 +598,25 @@ <title>Documentation</title> <access-permissions>Everyone</access-permissions> <edit-permission>*:/platform/administrators</edit-permission> -</page>]]></programlisting> +</page>]]></programlisting>--><!-- + <programlisting role="XML" language="XML"><xi:include href="extras/pages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting> + </para> </listitem> </varlistentry> <varlistentry> <term>navigation.xml</term> <listitem> - <para> - + <para>--> +<!-- <programlisting language="XML" role="XML"><![CDATA[<node> <uri>http://wiki.exoplatform.com/xwiki/bin/view/Main/WebHome</uri> <name>documentation</name> <label>#{portal.classic.documentation}</label> <page-reference>portal::website::documentation</page-reference> </node>]]></programlisting> +--><!-- +<programlisting role="XML" language="XML"><xi:include href="extras/navigation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>--><!-- </para> </listitem> </varlistentry> @@ -619,9 +627,11 @@ Currently you cannot modify the URL using the portal interface, you must change it in the configuration files or modify the underlying database table. </para> </warning> - </section> + + </section> + </section> - +--> </chapter> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -91,7 +91,7 @@ <section id="sect-Reference_Guide-Portal_Lifecycle-The_Command_Servlet"> <title>The Command Servlet</title> <para> - The servlet is the main entry point for incoming requests, it also includes some <literal>init</literal> code when the portal is launched. This servlet (<literal>org.gatein.wci.command.CommandServlet</literal>) is automatically added during deployment and mapped to <literal>/tomcatgateinservlet</literal>. + The servlet is the main entry point for incoming requests, it also includes some <literal>init</literal> code when the portal is launched. This servlet (<literal>org.gatein.wci.command.CommandServlet</literal>) is automatically added during deployment and mapped to <literal>/gateinservlet</literal>. </para> <para> This is equivalent to adding the following into <filename>web.xml</filename>. @@ -104,14 +104,14 @@ </note> <programlisting language="XML" role="XML"><![CDATA[<servlet> - <servlet-name>TomcatGateInServlet</servlet-name> + <servlet-name>GateInServlet</servlet-name> <servlet-class>org.gatein.wci.command.CommandServlet</servlet-class> <load-on-startup>0</load-on-startup> </servlet> <servlet-mapping> - <servlet-name>TomcatGateInServlet</servlet-name> - <url-pattern>/tomcatgateinservlet</url-pattern> + <servlet-name>GateInServlet</servlet-name> + <url-pattern>/gateinservlet</url-pattern> </servlet-mapping>]]></programlisting> <para> @@ -174,7 +174,7 @@ <filter-mapping> <filter-name>MyFilter</filter-name> - <url-pattern>/tomcatgateinservlet</url-pattern> + <url-pattern>/gateinservlet</url-pattern> <dispatcher>INCLUDE</dispatcher> </filter-mapping> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -639,7 +639,7 @@ <itemizedlist> <listitem> <para> - <filename>skin/DefaultSkin/portletIcons/<replaceable>icon_name.png</replaceable></filename>. + <filename>skin/DefaultSkin/skinIcons/<replaceable>icon_size</replaceable>/<replaceable>icon_name.png</replaceable></filename>. </para> </listitem> </itemizedlist> Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/gadgets.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/gadgets.xml (rev 0) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/gadgets.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -0,0 +1,47 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + + Copyright (C) 2009 eXo Platform SAS. + + This is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as + published by the Free Software Foundation; either version 2.1 of + the License, or (at your option) any later version. + + This software is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this software; if not, write to the Free + Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + 02110-1301 USA, or see the FSF site: http://www.fsf.org. + +--> + +<gadgets + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gadgets_1_0" + xmlns="http://www.gatein.org/xml/ns/gadgets_1_0"> + + <gadget name="Todo"> + <path>/gadgets/Todo/Todo.xml</path> + </gadget> + + <gadget name="Calendar"> + <path>/gadgets/Calendar/Calendar.xml</path> + </gadget> + + <gadget name="Calculator"> + <path>/gadgets/Calculator/Calculator.xml</path> + </gadget> + + <gadget name="rssAggregator"> + <path>/gadgets/rssAggregator/rssAggregator.xml</path> + </gadget> + + <gadget name="Currency"> + <url>http://www.donalobrien.net/apps/google/currency.xml</url> + </gadget> +</gadgets> Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/navigation.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/navigation.xml (rev 0) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/navigation.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -0,0 +1,71 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + + Copyright (C) 2009 eXo Platform SAS. + + This is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as + published by the Free Software Foundation; either version 2.1 of + the License, or (at your option) any later version. + + This software is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this software; if not, write to the Free + Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + 02110-1301 USA, or see the FSF site: http://www.fsf.org. + +--> + +<node-navigation + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0" + xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0"> + <priority>1</priority> + <page-nodes> + <node> + <uri>home</uri> + <name>home</name> + <label>#{portal.classic.home}</label> + <page-reference>portal::classic::homepage</page-reference> + </node> + <node> + <uri>sitemap</uri> + <name>sitemap</name> + <label>#{portal.classic.sitemap}</label> + <visibility>DISPLAYED</visibility> + <page-reference>portal::classic::sitemap</page-reference> + </node> + <node> + <uri>groupnavigation</uri> + <name>groupnavigation</name> + <label>#{portal.classic.groupnavigation}</label> + <visibility>SYSTEM</visibility> + <page-reference>portal::classic::groupnavigation</page-reference> + </node> + <node> + <uri>portalnavigation</uri> + <name>portalnavigation</name> + <label>#{portal.classic.portalnavigation}</label> + <visibility>SYSTEM</visibility> + <page-reference>portal::classic::portalnavigation</page-reference> + </node> + <node> + <uri>register</uri> + <name>register</name> + <label>#{portal.classic.register}</label> + <visibility>SYSTEM</visibility> + <page-reference>portal::classic::register</page-reference> + </node> + <!-- NOT FOUND node --> + <node> + <uri>notfound</uri> + <name>notfound</name> + <label>NotFound</label> + <visibility>SYSTEM</visibility> + </node> + </page-nodes> +</node-navigation> Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/pages.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/pages.xml (rev 0) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/pages.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -0,0 +1,115 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + + Copyright (C) 2009 eXo Platform SAS. + + This is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as + published by the Free Software Foundation; either version 2.1 of + the License, or (at your option) any later version. + + This software is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this software; if not, write to the Free + Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + 02110-1301 USA, or see the FSF site: http://www.fsf.org. + +--> + +<page-set + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0" + xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0"> + + <page> + <name>homepage</name> + <title>Home Page</title> + <access-permissions>Everyone</access-permissions> + <edit-permission>*:/platform/administrators</edit-permission> + <portlet-application> + <portlet> + <application-ref>web</application-ref> + <portlet-ref>HomePagePortlet</portlet-ref> + <preferences> + <preference> + <name>template</name> + <value>system:/templates/groovy/webui/component/UIHomePagePortlet.gtmpl</value> + <read-only>false</read-only> + </preference> + </preferences> + </portlet> + <title>Home Page portlet</title> + <access-permissions>Everyone</access-permissions> + <show-info-bar>false</show-info-bar> + <show-application-state>false</show-application-state> + <show-application-mode>false</show-application-mode> + </portlet-application> + </page> + + <page> + <name>groupnavigation</name> + <title>Group Navigation</title> + <access-permissions>*:/platform/users</access-permissions> + <edit-permission>*:/platform/administrators</edit-permission> + <portlet-application> + <portlet> + <application-ref>exoadmin</application-ref> + <portlet-ref>GroupNavigationPortlet</portlet-ref> + </portlet> + <title>Group Navigation</title> + <access-permissions>Everyone</access-permissions> + <show-info-bar>false</show-info-bar> + </portlet-application> + </page> + + <page> + <name>portalnavigation</name> + <title>Portal Navigation</title> + <access-permissions>*:/platform/users</access-permissions> + <edit-permission>*:/platform/administrators</edit-permission> + <portlet-application> + <portlet> + <application-ref>exoadmin</application-ref> + <portlet-ref>PortalNavigationPortlet</portlet-ref> + </portlet> + <title>Portal Navigation</title> + <access-permissions>Everyone</access-permissions> + <show-info-bar>false</show-info-bar> + </portlet-application> + </page> + + <page> + <name>register</name> + <title>Register</title> + <access-permissions>*:/platform/guests</access-permissions> + <edit-permission>*:/platform/administrators</edit-permission> + <portlet-application> + <portlet> + <application-ref>exoadmin</application-ref> + <portlet-ref>RegisterPortlet</portlet-ref> + </portlet> + <title>Register Account</title> + <access-permissions>*:/platform/guests</access-permissions> + <show-info-bar>false</show-info-bar> + </portlet-application> + </page> + <page> + <name>sitemap</name> + <title>Site Map</title> + <access-permissions>Everyone</access-permissions> + <edit-permission>*:/platform/administrators</edit-permission> + <portlet-application> + <portlet> + <application-ref>web</application-ref> + <portlet-ref>SiteMapPortlet</portlet-ref> + </portlet> + <title>SiteMap</title> + <access-permissions>Everyone</access-permissions> + <show-info-bar>false</show-info-bar> + </portlet-application> + </page> +</page-set> Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/portal.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/portal.xml (rev 0) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortalDevelopment/portal.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -0,0 +1,91 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + + Copyright (C) 2009 eXo Platform SAS. + + This is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as + published by the Free Software Foundation; either version 2.1 of + the License, or (at your option) any later version. + + This software is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this software; if not, write to the Free + Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + 02110-1301 USA, or see the FSF site: http://www.fsf.org. + +--> + +<portal-config + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0" + xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0"> + <portal-name>classic</portal-name> + <locale>en</locale> + <access-permissions>Everyone</access-permissions> + <edit-permission>*:/platform/administrators</edit-permission> + <skin>NewSkin</skin> + <properties> + <entry key="sessionAlive">onDemand</entry> + </properties> + + <portal-layout> + <portlet-application> + <portlet> + <application-ref>web</application-ref> + <portlet-ref>BannerPortlet</portlet-ref> + <preferences> + <preference> + <name>template</name> + <value>par:/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</value> + <read-only>false</read-only> + </preference> + </preferences> + </portlet> + <access-permissions>Everyone</access-permissions> + <show-info-bar>false</show-info-bar> + </portlet-application> + + <portlet-application> + <portlet> + <application-ref>web</application-ref> + <portlet-ref>NavigationPortlet</portlet-ref> + </portlet> + <access-permissions>Everyone</access-permissions> + <show-info-bar>false</show-info-bar> + </portlet-application> + + <portlet-application> + <portlet> + <application-ref>web</application-ref> + <portlet-ref>BreadcumbsPortlet</portlet-ref> + </portlet> + <access-permissions>Everyone</access-permissions> + <show-info-bar>false</show-info-bar> + </portlet-application> + + <page-body> </page-body> + + <portlet-application> + <portlet> + <application-ref>web</application-ref> + <portlet-ref>FooterPortlet</portlet-ref> + <preferences> + <preference> + <name>template</name> + <value>par:/groovy/groovy/webui/component/UIFooterPortlet.gtmpl</value> + <read-only>false</read-only> + </preference> + </preferences> + </portlet> + <access-permissions>Everyone</access-permissions> + <show-info-bar>false</show-info-bar> + </portlet-application> + + </portal-layout> + +</portal-config> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml 2010-05-18 10:03:25 UTC (rev 3112) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml 2010-05-18 20:31:43 UTC (rev 3113) @@ -32,7 +32,9 @@ More information on WSRP can be found on the official <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp...;. </para> <para> - The <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... is suggested reading for a comprehensive overview of WSRP. + The <ulink url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr..., not http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp + ----------------- +">primer</ulink> is suggested reading for a comprehensive overview of WSRP. </para> </section> @@ -61,12 +63,14 @@ As of version &PRODUCT_VERSION; of &PRODUCT_NAME;, WSRP is only activated and supported when &PRODUCT_NAME; is deployed on JBoss Application Server. </para> </note> + <!-- <warning> <title>DOC TODO</title> <para> Replaced all references to <emphasis role="bold">we</emphasis> in this file with either references to WSRP component or EPP. Does this break the meaning? </para> </warning> + --> </section> <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Deploying_PRODUCT_NAMEs_WSRP_services"> @@ -295,7 +299,7 @@ <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Configuring_a_remote_producer"> <title>Configuring a remote producer</title> <para> - Let's work through the steps of defining access to a remote producer so that its portlets can be consumed within &PRODUCT_NAME;. the WSRP component will configure access to Oracle's public WSRP producer. the WSRP component will first examine how to do so using the configuration portlet. the WSRP component will then show how the same result can be accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet. + You need to define access to a remote producer so that its portlets can be consumed within &PRODUCT_NAME;. The WSRP component configures access to Oracle's public WSRP producer. First, it determines how to do so using the configuration portlet. It then shows how the same result can be accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet. </para> <section id="sect-Reference_Guide-Configuring_a_remote_producer_walk_through-Using_the_configuration_portlet"> @@ -304,10 +308,10 @@ &PRODUCT_NAME; provides a portlet to configure access (among other functions) to remote WSRP Producers grahically. It isn't, however, installed by default, so the first thing the WSRP component will need to do is to install the WSRP configuration portlet using the Application Registry. </para> <para> - Use the usual procedure to log in as a Portal administrator and go to the Application Registry. With the default install, you can just go to <ulink url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&amp;username=root&amp;password=gtn"> http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... </ulink> Add the WSRP Configuration portlet to the Administration category. If you use the Import Applications functionality, the WSRP Configuration portlet will be automatically added to the Administration category. + Use the usual procedure to log in as a Portal administrator and go to the Application Registry. With the default install, you can just go to <ulink url="http://localhost:8080/portal/private/classic/administration/registry">http://localhost:8080/portal/private/classic/administration/registry</ulink>. Add the WSRP Configuration portlet to the Administration category. If you use the Import Applications functionality, the WSRP Configuration portlet will be automatically added to the Administration category. </para> <para> - Now that the portlet is added to a category, it can be added to a page and used. the WSRP component recommend adding it to the same page as the Application Registry as operations relating to WSRP and adding portlets to categories are somewhat related as the WSRP component will see. Go ahead and add the WSRP Configuration portlet to the page using the standard procedure. + Now that the portlet is added to a category, it can be added to a page and used. The WSRP component recommend adding it to the same page as the Application Registry as operations relating to WSRP and adding portlets to categories are somewhat related as the WSRP component will see. Go ahead and add the WSRP Configuration portlet to the page using the standard procedure. </para> <para> If all went well, you should see something similar to this: @@ -318,10 +322,10 @@ </imageobject> </mediaobject> <para> - This screen presents all the configured producers associated with their status and possible actions on them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. Note also that a Consumer can be marked as requiring refresh meaning that the information held about it might not be up to date and refreshing it from the remote Producer might be a good idea. This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information. + This screen presents all the configured consumers associated with their status and possible actions on them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. Note also that a Consumer can be marked as requiring refresh meaning that the information held about it might not be up to date and refreshing it from the remote Producer might be a good idea. This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information. </para> <para> - Next, the WSRP component create a new Consumer which the WSRP component will call<literal>oracle</literal>. Type "<literal> oracle</literal>" in the "Create a consumer named:" field then click on "Create consumer": + Next, the WSRP component create a new Consumer which the WSRP component will call <literal>oracle</literal>. Type "<literal> oracle</literal>" in the "Create a consumer named:" field then click on "Create consumer": </para> <mediaobject> <imageobject> @@ -372,7 +376,7 @@ <section id="sect-Reference_Guide-Configuring_a_remote_producer_walk_through-Using_XML"> <title>Using XML</title> <para> - While the WSRP component recommend you use the WSRP Configuration portlet to configure Consumers, the WSRP component provide an alternative way to configure consumers by editing the XML file located at <filename>$GATEIN_HOME/lib/wsrp-consumer-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename>. + While the WSRP component recommend you use the WSRP Configuration portlet to configure Consumers, The WSRP component provide an alternative way to configure consumers by editing the XML file located at <filename>$GATEIN_HOME/lib/wsrp-consumer-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename>. </para> <programlisting role="XML"> @@ -404,7 +408,7 @@ The file as shown above specifies access to two producers: <literal>self</literal>, which consumes &PRODUCT_NAME;'s own WSRP producer albeit in a version that assumes that the producer requires a value for an <literal>email</literal> registration property, and <literal>oracle</literal>, which consumes Oracle's public producer, both in configurations as shown in the walk-through above. </para> <para> - the WSRP component will look at the details of the meaning of elements later on. + The WSRP component will look at the details of the meaning of elements later on. </para> </section> @@ -444,14 +448,14 @@ </note> <note> <para> - It is important to note how the XML consumers configuration file is processed. It is read the first time the WSRP service starts and the associated information is then put under control of JCR (Java Content Repository). Subsequent launches of the WSRP service will use the JCR-stored information for all producers are already known to &PRODUCT_NAME;. More specifically, <filename>wsrp-consumers-config.xml</filename> file is scanned for producer identifiers. Any identifier that is already known will be bypassed and the JCR information associated with this remote producer will be used. The information defined at the XML level is only processed for producer definition for which no information is already present in JCR. Therefore, if you wish to delete a producer configuration, you need to delete the associated information in the database (this can be accomplished using the configuration portlet as the WSRP component saw in <xref linkend="sect-Reference_Guide-Configuring_a! _remote_producer_walk_through-Using_the_configuration_portlet" />) <emphasis>AND</emphasis> remove the associated information in <filename>wsrp-consumers-config.xml</filename> (if such information exists) as the producer will be re-created the next time the WSRP is launched if that information is not removed. + It is important to note how the XML consumers configuration file is processed. It is read the first time the WSRP service starts and the associated information is then put under control of JCR (Java Content Repository). Subsequent launches of the WSRP service will use the JCR-stored information for all producers are already known to &PRODUCT_NAME;. More specifically, <filename>wsrp-consumers-config.xml</filename> file is scanned for producer identifiers. Any identifier that is already known will be bypassed and the JCR information associated with this remote producer will be used. The information defined at the XML level is only processed for producer definition for which no information is already present in JCR. Therefore, if you wish to delete a producer configuration, you need to delete the associated information in the database (this can be accomplished using the configuration portlet as the WSRP component saw in <xref linkend="sect-Reference_Guide-Configuring_a! _remote_producer_walk_through-Using_the_configuration_portlet" />) and remove the associated information in <filename>wsrp-consumers-config.xml</filename> (if such information exists) as the producer will be re-created the next time the WSRP is launched if that information is not removed. </para> </note> <section id="sect-Reference_Guide-Configuring_access_to_remote_producers_via_XML-Required_configuration_information"> <title>Required configuration information</title> <para> - Let's now look at which information needs to be provided to configure access to a remote producer. + Some information needs to be provided to configure access to a remote producer. </para> <para> First, the WSRP component need to provide an identifier for the producer the WSRP component are configuring so that the WSRP component can refer to it afterwards. This is accomplished via the mandatory <literal>id</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element. @@ -557,7 +561,7 @@ It is therefore sometimes necessary to modify the registration that concretizes the service agreement between a consumer and a producer. Let's take the example of the producer requiring an email the WSRP component configured in <xref linkend="sect-Reference_Guide-Configuring_a_remote_producer_walk_through-Using_the_configuration_portlet" />. If you recall, the producer was requiring registration and required a value to be provided for the <literal>email</literal> property. </para> <para> - Suppose now that the WSRP component would like to update the email address that the WSRP component provided to the remote producer. the WSRP component will need to tell the producer that our registration data has been modified. Let's see how to do this. Assuming you have configured access to the producer as previously described, please go to the configuration screen for the <literal>self</literal> producer and modify the value of <literal>email</literal> to <literal&gt;foo(a)example.com&lt;/literal&gt; instead of&lt;literal&gt;example(a)example.com&lt;/literal&gt;: + Suppose now that the WSRP component would like to update the email address that the WSRP component provided to the remote producer. The WSRP component will need to tell the producer that our registration data has been modified. Let's see how to do this. Assuming you have configured access to the producer as previously described, please go to the configuration screen for the <literal>self</literal> producer and modify the value of <literal>email</literal> to <literal&gt;foo(a)example.com&lt;/literal&gt; instead of&lt;literal&gt;example(a)example.com&lt;/literal&gt;: </para> <mediaobject> <imageobject> @@ -585,7 +589,7 @@ <section id="sect-Reference_Guide-Modifying_a_currently_held_registration-Registration_modification_on_producer_error"> <title>Registration modification on producer error</title> <para> - It can also happen that a producer administrator decided to change its requirement forregistered consumers. In this case, invoking operations on the producer will fail with an <exceptionname>OperationFailedFault</exceptionname>. &PRODUCT_NAME; will attempt to help you in this situation. Let's walk through an example using the <literal>self</literal> producer. Let's assume that registration is requiring a valid value for an <literal>email</literal> registration property (as the WSRP component have seen so far). If you go to the configuration screen for this producer, you should see: + It can also happen that a producer administrator decided to change its requirement for registered consumers. In this case, invoking operations on the producer will fail with an <exceptionname>OperationFailedFault</exceptionname>. &PRODUCT_NAME; will attempt to help you in this situation. Let's walk through an example using the <literal>self</literal> producer. Let's assume that registration is requiring a valid value for an <literal>email</literal> registration property (as the WSRP component have seen so far). If you go to the configuration screen for this producer, you should see: </para> <mediaobject> <imageobject> @@ -593,7 +597,7 @@ </imageobject> </mediaobject> <para> - Now suppose that the administrator of the producer now additionaly requires a value to be provided for a <literal>name</literal> registration property. the WSRP component will actually see how to do perform this operation in &PRODUCT_NAME; when the WSRP component examine how to configure &PRODUCT_NAME;'s producer in <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Configuring_PRODUCT_NAMEs_WSRP_Producer" />. Operations with this producer will now fail. If you suspect that a registration modification is required, you should go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing "Refresh &amp; Save": + Now suppose that the administrator of the producer now additionaly requires a value to be provided for a <literal>name</literal> registration property. The WSRP component will actually see how to do perform this operation in &PRODUCT_NAME; when the WSRP component examine how to configure &PRODUCT_NAME;'s producer in <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Configuring_PRODUCT_NAMEs_WSRP_Producer" />. Operations with this producer will now fail. If you suspect that a registration modification is required, you should go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing "Refresh &amp; Save": </para> <mediaobject> <imageobject> @@ -696,7 +700,7 @@ <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Default_configuration"> <title>Default configuration</title> <para> - The default producer configuration is to require that consumers register with it before providing access its services but does not require any specific registration properties (apart from what is mandated by the WSRP standard). It does, however, require consumers to be registered before sending them a full service description. This means that our WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. The producer also uses the default <classname>RegistrationPolicy</classname> paired with the default <classname>RegistrationPropertyValidator</classname>. the WSRP component will look into property validators in greater detail later in<xref linkend="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Registration_configuration" />. Suffice to say for now that this allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not. + The default producer configuration is to require that consumers register with it before providing access its services but does not require any specific registration properties (apart from what is mandated by the WSRP standard). It does, however, require consumers to be registered before sending them a full service description. This means that our WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. The producer also uses the default <classname>RegistrationPolicy</classname> paired with the default <classname>RegistrationPropertyValidator</classname>. The WSRP component will look into property validators in greater detail later in<xref linkend="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Registration_configuration" />. Suffice to say for now that this allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not. </para> <para> &PRODUCT_NAME; provides a web interface to configure the producer's behavior. You can access it by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. Here's what you should see with the default configuration: @@ -722,7 +726,7 @@ </imageobject> </mediaobject> <para> - the WSRP component will allow unregistered consumers to see the list of offered portlets so the WSRP component leave the first checkbox ("Access to full service description requires consumers to be registered.") unchecked. the WSRP component will, however, specify that consumers will need to be registered to be able to interact with our producer. Check the second checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer registrations."). The screen should now refresh and display: + The WSRP component will allow unregistered consumers to see the list of offered portlets so the WSRP component leave the first checkbox ("Access to full service description requires consumers to be registered.") unchecked. The WSRP component will, however, specify that consumers will need to be registered to be able to interact with our producer. Check the second checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer registrations."). The screen should now refresh and display: </para> <mediaobject> <imageobject> @@ -730,7 +734,7 @@ </imageobject> </mediaobject> <para> - You can specify the fully-qualified name for your <classname>RegistrationPolicy</classname> and <classname>RegistrationPropertyValidator</classname> there. the WSRP component will keep the default value. See <xref linkend="sect-Reference_Guide-Registration_configuration-Customization_of_Registration_handling_behavior" /> for more details. Let's add, however, a registration property called <literal>email</literal>. Click "Add property" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to figure out its purpose: + You can specify the fully-qualified name for your <classname>RegistrationPolicy</classname> and <classname>RegistrationPropertyValidator</classname> there. The WSRP component will keep the default value. See <xref linkend="sect-Reference_Guide-Registration_configuration-Customization_of_Registration_handling_behavior" /> for more details. Let's add, however, a registration property called <literal>email</literal>. Click "Add property" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to figure out its purpose: </para> <mediaobject> <imageobject> @@ -747,7 +751,7 @@ </note> <note> <para> - If consumers are already registered with the producer, modifying the configuration of required registration information will trigger the invalidation of held registrations, requiring consumers to modify their registration before being able to access the producer again. the WSRP component saw the consumer side of that process in <xref linkend="sect-Reference_Guide-Modifying_a_currently_held_registration-Registration_modification_on_producer_error" />. + If consumers are already registered with the producer, modifying the configuration of required registration information will trigger the invalidation of held registrations, requiring consumers to modify their registration before being able to access the producer again. The WSRP component saw the consumer side of that process in <xref linkend="sect-Reference_Guide-Modifying_a_currently_held_registration-Registration_modification_on_producer_error" />. </para> </note> <section id="sect-Reference_Guide-Registration_configuration-Customization_of_Registration_handling_behavior"> @@ -775,7 +779,7 @@ <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-WSRP_validation_mode"> <title>WSRP validation mode</title> <para> - The lack of conformance kit and the wording of the WSRP specification leaves room for differing interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when using consumers from different vendors. the WSRP component have experienced such issues and have introduced a way to relax the validation that our WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. Note that the WSRP component only relax our validation algorithm on aspects of the specification that are deemed harmless such as invalid language codes. + The lack of conformance kit and the wording of the WSRP specification leaves room for differing interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when using consumers from different vendors. The WSRP component have experienced such issues and have introduced a way to relax the validation that our WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. Note that the WSRP component only relax our validation algorithm on aspects of the specification that are deemed harmless such as invalid language codes. </para> <para> By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you might want to try to relax the validation mode. This is accomplished by unchecking the "Use strict WSRP compliance." checkbox on the Producer configuration screen.