[exo-jcr-commits] exo-jcr SVN: r1906 - in jcr/trunk/docs/reference/en/src/main/docbook/en-US: modules and 4 other directories.

Author: sergiykarpenko Date: 2010-02-18 11:44:48 -0500 (Thu, 18 Feb 2010) New Revision: 1906 Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/core.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/architecture.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration-persister.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/external-value-storages.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/intro.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jbosscache-configuration-templates.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jdbc-data-container-config.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/lock-manager-config.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/multilanguage-support.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/query-handler-config.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/search-configuration.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/transaction-manager-lookup.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/transaction-service.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/ws.xml Removed: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/architecture.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/cluster-config.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/configuration-persister.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/configuration.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/external-value-storages.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/intro.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jbosscache-configuration-templates.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jdbc-data-container-config.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/lock-manager-config.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/multilanguage-support.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/query-handler-config.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/search-configuration.xml Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/master.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/core/core.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/kernel.xml jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/ws/ws.xml Log: EXOJCR-490: structure updated Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/master.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/master.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/master.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -54,48 +54,21 @@ href="modules/Portal_Manual.xml" /> --> - <xi:include href="modules/intro.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> + - <xi:include href="modules/architecture.xml" + <xi:include href="modules/jcr.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- common configs --> - - <xi:include href="modules/configuration.xml" + <xi:include href="modules/kernel.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="modules/jdbc-data-container-config.xml" + + <xi:include href="modules/core.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="modules/external-value-storages.xml" + <xi:include href="modules/ws.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="modules/search-configuration.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="modules/multilanguage-support.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="modules/configuration-persister.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- cluster configs --> - - <xi:include href="modules/cluster-config.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="modules/jbosscache-configuration-templates.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="modules/lock-manager-config.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="modules/query-handler-config.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - - - - </book> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/architecture.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/architecture.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/architecture.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,14 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="architecture" xreflabel="architectural"> - <?dbhtml filename="architecture.html"?> - <chapterinfo> - <keywordset> - <keyword>JCR</keyword> - <keyword>eXoJCR</keyword> - <keyword>etc</keyword> - </keywordset> - </chapterinfo> - <title>Basic concepts of eXoJCR</title> -</chapter> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/cluster-config.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/cluster-config.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/cluster-config.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,262 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_cluster_configuration"> - <?dbhtml filename="cluster-config.html"?> - - <title>Configuring JBoss AS with eXo JCR in cluster</title> - - <section> - <title>Launching Cluster</title> - - <section> - <title>Deploying eXo JCR to JBoss As</title> - - <para>To deploy eXo JCR to JBoss As follow next steps:</para> - - <orderedlist> - <listitem> - <para>Dowload the latest version of eXo JCR ear distribution from - [LINK THERE]</para> - </listitem> - - <listitem> - <para>Copy &lt;jcr.ear&gt; into - &lt;%jboss_home%/server/default/deploy&gt;</para> - </listitem> - - <listitem> - <para>Put exo-configuration.xml to the root - &lt;%jboss_home%/exo-configuration.xml&gt;</para> - </listitem> - - <listitem> - <para>Configure JAAS by inserting XML fragment shown below into - &lt;%jboss_home%/server/default/conf/login-config.xml&gt;</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> - <para>Start server:</para> - - <itemizedlist> - <listitem> - <para>bin/run.sh for Unix</para> - </listitem> - - <listitem> - <para>bin/run.bat for Windows</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Try accessing <uri>http://localhost:8080/browser</uri> with - root/exo as login/password if you have done everything right, you'll - get access to repository browser.</para> - </listitem> - </orderedlist> - </section> - - <section id="sect_conf_cluster_jcr"> - <title>Configuring JCR to use external configuration</title> - - <itemizedlist> - <listitem> - <para>To manually configure repository create a new configuration - file (f.e. exo-jcr-configuration.xml). For details see <link - linkend="ch_configuration">JCR Configuration</link>. Your - configuration must look like:</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; - see "<link linkend="conf_value_storage">Value storage configuration</link>" part. - &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; - see "<link linkend="conf_cache">Cache configuration</link>" part. - &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - see "<link linkend="conf_indexer">Indexer configuration</link>" part. - &lt;/query-handler&gt; - &lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; - see "<link linkend="conf_lock_manager">Lock Manager configuration</link>" part. - &lt;/lock-manager&gt; - &lt;/workspace&gt; - &lt;workspace name="ws2"&gt; - ... - &lt;/workspace&gt; - &lt;workspace name="wsN"&gt; - ... - &lt;/workspace&gt; - &lt;/workspaces&gt; - &lt;/repository&gt; - &lt;/repositories&gt; -&lt;/repository-service&gt; </programlisting> - </listitem> - - <listitem> - <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></para> - </listitem> - </itemizedlist> - </section> - </section> - - <section> - <title>Requirements</title> - - <section> - <title>Enviorenment requirements</title> - - <itemizedlist> - <listitem> - <para>Every node of cluster MUST have the same mounted Network File - System with read and write permissions on it.</para> - - <para>"/mnt/tornado" - path to the mounted Network File System (all - cluster nodes must use the same NFS)</para> - </listitem> - - <listitem> - <para>Every node of cluster MUST use the same database</para> - </listitem> - - <listitem> - <para>Same Clusters on different nodes MUST have the same cluster - names (f.e if Indexer cluster in workspace production on the first - node has name "production_indexer_cluster", then indexer clusters in - workspace production on all other nodes MUST have the same name - "production_indexer_cluster" )</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Enviorenment requirements</title> - - <para>Configuration of every workspace in repository must contains of - such parts:</para> - - <itemizedlist> - <listitem id="conf_value_storage"> - <para>Value Storage configuration:</para> - - <programlisting>&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> - - <para>See more about <link - linkend="ch_external_value_storages">ValueStorage - configuration</link>.</para> - </listitem> - - <listitem id="conf_cache"> - <para>Cache configuration:</para> - - <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> - - <para>See more about <link - linkend="ch_jbosscache_config_templates">Cache - configuration</link>.</para> - </listitem> - - <listitem id="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> - - <para>See more about <link - linkend="ch_query_handler_config">QueryHandler - configuration</link>.</para> - </listitem> - - <listitem id="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; - - &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> - - <para>See more about <link - linkend="ch_lock_manager_config">LockManager - configuration</link>.</para> - </listitem> - </itemizedlist> - </section> - </section> -</chapter> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/configuration-persister.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/configuration-persister.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/configuration-persister.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,124 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_configuration_persister"> - <?dbhtml filename="configuration-persister.html"?> - <title>JCR Configuration persister</title> - - <section> - <title>Idea</title> - - <para>JCR Repository Service uses - <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> - - <para>In the example 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.</para> - - <para>In this case we have to use the configuration persister feature - which allows to store the configuration in different locations.</para> - </section> - - <section> - <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.</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></para> - - <para>Where:<itemizedlist> - <listitem> - <para><parameter>source-name</parameter> - JNDI source name - configured in <classname>InitialContextInitializer</classname> - component. (<parameter>sourceName</parameter> prior v.1.9.) Find - more in <link linkend="ch_configuration">database - configuration</link>.</para> - </listitem> - - <listitem> - <para><parameter>dialect</parameter> - SQL dialect which will be - used with database from <parameter>source-name</parameter>. Find - more in <link linkend="ch_configuration">database - configuration</link>.</para> - </listitem> - - <listitem> - <para><parameter>persister-class-name</parameter> - class name of - <classname>ConfigurationPersister</classname> interface - implementation. (<parameter>persisterClassName</parameter> prior - v.1.9.)</para> - </listitem> - </itemizedlist></para> - - <para>ConfigurationPersister interface:<programlisting>/** - * Init persister. - * Used by RepositoryServiceConfiguration on init. - * @return - config data stream - */ - void init(PropertiesParam params) throws RepositoryConfigurationException; - - /** - * Read config data. - * @return - config data stream - */ - InputStream read() throws RepositoryConfigurationException; - - /** - * Create table, write data. - * @param confData - config data stream - */ - void write(InputStream confData) throws RepositoryConfigurationException; - - /** - * Tell if the config exists. - * @return - flag - */ - 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>.</para> - - <para>The implementation will crate and use table JCR_CONFIG in the - provided database.</para> - - <para>But the developer can implement his own persister for his particular - usecase.</para> - </section> -</chapter> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/configuration.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/configuration.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/configuration.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,436 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_configuration"> - <?dbhtml filename="configuration.html"?> - - <title>eXo JCR configuration</title> - - <section> - <title>Related documents</title> - - <itemizedlist> - <listitem> - <para><link linkend="ch_search_configuration">Search - Configuration</link></para> - </listitem> - - <listitem> - <para><link linkend="ch_jdbc_data_container">JDBC Data Container - config</link></para> - </listitem> - - <listitem> - <para><link linkend="ch_external_value_storages">External Value - Storages</link></para> - </listitem> - </itemizedlist> - </section> - - <section> - <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 and the second option is to use a Standalone container. The main - difference between these container types is that the first one is intended - to be used in a Portal (Web) environment, while the second one can be used - standalone (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 (TODO find more in Container configuration):</para> - - <itemizedlist> - <listitem> - <para>Configuration that is set explicitly using - StandaloneContainer.addConfigurationURL(String url) or - StandaloneContainer.addConfigurationPath(String path) before - getInstance()</para> - </listitem> - - <listitem> - <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> - </listitem> - - <listitem> - <para>/conf/exo-configuration.xml in the current classloader (e.g. - war, ear archive)</para> - </listitem> - - <listitem> - <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> - </listitem> - </itemizedlist> - - <para>JCR service configuration looks like:</para> - - <programlisting>&lt;component&gt; - &lt;key&gt;org.exoplatform.services.jcr.RepositoryService&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.jcr.impl.RepositoryServiceImpl&lt;/type&gt; - &lt;/component&gt; - &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 repositories configuration file&lt;/description&gt; - &lt;value&gt;jar:/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="hsqldb" /&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> - - <para>conf-path : a path to a RepositoryService JCR Configuration</para> - - <para>working-conf : optional; JCR configuration persister configuration. - If there isn't a working-conf the persister will be disabled</para> - - <section> - <title>JCR Configuration</title> - - <para>The Configuration is defined in an XML file (see DTD - below).</para> - - <para>JCR Service can use multiple Repositories and each repository can - have multiple Workspaces.</para> - - <para>Repositories configuration parameters support human-readable - formats of values. They are all case-insensitive:</para> - - <itemizedlist> - <listitem> - <para>Numbers formats: K,KB - kilobytes, M,MB - megabytes, G,GB - - gigabytes, T,TB - terabytes.</para> - - <para>Examples: 100.5 - digit 100.5, 200k - 200 Kbytes, 4m - 4 - Mbytes, 1.4G - 1.4 Gbytes, 10T - 10 Tbytes</para> - </listitem> - - <listitem> - <para>Time format endings: ms - milliseconds, s - seconds, m - - minutes, h - hours, d - days, w - weeks, if no ending - - seconds.</para> - - <para>Examples: 500ms - 500 milliseconds, 20 or 20s - 20 seconds, - 30m - 30 minutes, 12h - 12 hours, 5d - 5 days, 4w - 4 weeks.</para> - </listitem> - </itemizedlist> - - <para></para> - </section> - - <section id="sect_repository_service_configuration"> - <title>Repository service configuration</title> - - <para>Default configuration of the Repository Service located in - jar:/conf/portal/exo-jcr-config.xml, it will be available for portal and - standalone modes.</para> - - <para>In portal mode it is overriden and located in the portal web - application portal/WEB-INF/conf/jcr/repository-configuration.xml.</para> - - <para>Example of Repository Service configuration for standalone - mode:</para> - - <programlisting>&lt;repository-service default-repository="repository"&gt; - &lt;repositories&gt; - &lt;repository name="db1" system-workspace="ws" default-workspace="ws"&gt; - &lt;security-domain&gt;exo-domain&lt;/security-domain&gt; - &lt;access-control&gt;optional&lt;/access-control&gt; - &lt;session-max-age&gt;1h&lt;/session-max-age&gt; - &lt;authentication-policy&gt;org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator&lt;/authentication-policy&gt; - &lt;workspaces&gt; - &lt;workspace name="production"&gt; - &lt;!-- for system storage --&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="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; - &lt;value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; - &lt;properties&gt; - &lt;property name="path" value="../temp/values/production" /&gt; - &lt;/properties&gt; - &lt;filters&gt; - &lt;filter property-type="Binary" /&gt; - &lt;/filters&gt; - &lt;/value-storage&gt; - &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.LinkedWorkspaceStorageCacheImpl"&gt; - &lt;properties&gt; - &lt;property name="max-size" value="10k" /&gt; - &lt;property name="live-time" value="1h" /&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="../temp/jcrlucenedb/production" /&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; - &lt;lock-manager&gt; - &lt;time-out&gt;15m&lt;/time-out&gt; - &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; - &lt;properties&gt; - &lt;property name="path" value="../temp/lock/system" /&gt; - &lt;/properties&gt; - &lt;/persister&gt; - &lt;/lock-manager&gt; - &lt;/workspace&gt; - - &lt;workspace name="backup"&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="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/backup" /&gt; - &lt;/properties&gt; - &lt;value-storages&gt; - &lt;value-storage id="draft" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; - &lt;properties&gt; - &lt;property name="path" value="../temp/values/backup" /&gt; - &lt;/properties&gt; - &lt;filters&gt; - &lt;filter property-type="Binary" /&gt; - &lt;/filters&gt; - &lt;/value-storage&gt; - &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.LinkedWorkspaceStorageCacheImpl"&gt; - &lt;properties&gt; - &lt;property name="max-size" value="10k" /&gt; - &lt;property name="live-time" value="1h" /&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="../temp/jcrlucenedb/backup" /&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; - &lt;/workspace&gt; - &lt;/workspaces&gt; - &lt;/repository&gt; - &lt;/repositories&gt; -&lt;/repository-service&gt; -</programlisting> - - <para>Repository Service configuration:</para> - - <para>default-repository - the name of a default repository (one - returned by RepositoryService.getRepository())</para> - - <para>repositories - the list of repositories</para> - - <para>Repository configuration:</para> - - <para>name - the name of a repository</para> - - <para>default-workspace - the name of a workspace obtained using - Session's login() or login(Credentials) methods (ones without an - explicit workspace name)</para> - - <para>system-workspace - name of workspace where /jcr:system node is - placed</para> - - <para>security-domain - the name of a security domain for JAAS - authentication</para> - - <para>access-control - 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> - - <para>authentication-policy - the name of an authentication policy - class</para> - - <para>workspaces - the list of workspaces</para> - - <para>session-max-age - the time after which an idle session will be - removed (called logout). If not set, the idle session will never be - removed.</para> - - <para>Workspace configuration:</para> - - <para>name - the name of a workspace</para> - - <para>auto-init-root-nodetype - DEPRECATED in JCR 1.9 (use initializer). - The node type for root node initialization</para> - - <para>container - workspace data container (physical storage) - configuration</para> - - <para>initializer - workspace initializer configuration</para> - - <para>cache - workspace storage cache configuration</para> - - <para>query-handler - query handler configuration</para> - - <para>Workspace data container configuration:</para> - - <para>class - A workspace data container class name</para> - - <para>properties - the list of properties (name-value pairs) for the - concrete Workspace data container</para> - - <para>value-storages - the list of value storage plugins</para> - - <para>Value Storage plugin configuration (optional feature):</para> - - <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> - - <para>value-storage - Optional value Storage plugin definition</para> - - <para>class- a value storage plugin class name (attribute)</para> - - <para>properties - the list of properties (name-value pairs) for a - concrete Value Storage plugin</para> - - <para>filters - the list of filters defining conditions when this plugin - is applicable</para> - - <para>Initializer configuration (optional):</para> - - <para>class - initializer implementation class.</para> - - <para>properties - the list of properties (name-value pairs). Properties - are supported:</para> - - <para>root-nodetype - The node type for root node initialization</para> - - <para>root-permissions - 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.</para> - - <para>Configurable initializer adds a capability to override workspace - initial startup procedure.</para> - - <para>Cache configuration:</para> - - <para>enabled - if workspace cache is enabled</para> - - <para>class - cache implementation class, optional from 1.9. Default - value is - org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl.</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> - - <para>properties - the list of properties (name-value pairs) for - Workspace cache:</para> - - <para>max-size - cache maximum size.</para> - - <para>live-time - cached item live time.</para> - - <para>LinkedWorkspaceStorageCacheImpl supports additional optional - parameters TODO</para> - - <para>Query Handler configuration:</para> - - <para>class - A Query Handler class name</para> - - <para>properties - the list of properties (name-value pairs) for a Query - Handler (indexDir) properties and advanced features described in *Search - Configuration*</para> - - <para>Lock Manager configuration:</para> - - <para>time-out - time after which the unused global lock will be - removed.</para> - - <para>persister - a class for storing lock information for future use. - For example, remove lock after jcr restart.</para> - - <para>path - a lock folder, each workspace has its own.</para> - - <para></para> - - <para>Configuration definition:</para> - - <programlisting>&lt;!ELEMENT repository-service (repositories)&gt; - &lt;!ATTLIST repository-service default-repository NMTOKEN #REQUIRED&gt; - &lt;!ELEMENT repositories (repository)&gt; - &lt;!ELEMENT repository (security-domain,access-control,session-max-age,authentication-policy,workspaces)&gt; - &lt;!ATTLIST repository - default-workspace NMTOKEN #REQUIRED - name NMTOKEN #REQUIRED - system-workspace NMTOKEN #REQUIRED - &gt; - &lt;!ELEMENT security-domain (#PCDATA)&gt; - &lt;!ELEMENT access-control (#PCDATA)&gt; - &lt;!ELEMENT session-max-age (#PCDATA)&gt; - &lt;!ELEMENT authentication-policy (#PCDATA)&gt; - &lt;!ELEMENT workspaces (workspace+)&gt; - &lt;!ELEMENT workspace (container,initializer,cache,query-handler)&gt; - &lt;!ATTLIST workspace name NMTOKEN #REQUIRED&gt; - &lt;!ELEMENT container (properties,value-storages)&gt; - &lt;!ATTLIST container class NMTOKEN #REQUIRED&gt; - &lt;!ELEMENT value-storages (value-storage+)&gt; - &lt;!ELEMENT value-storage (properties,filters)&gt; - &lt;!ATTLIST value-storage class NMTOKEN #REQUIRED&gt; - &lt;!ELEMENT filters (filter+)&gt; - &lt;!ELEMENT filter EMPTY&gt; - &lt;!ATTLIST filter property-type NMTOKEN #REQUIRED&gt; - &lt;!ELEMENT initializer (properties)&gt; - &lt;!ATTLIST initializer class NMTOKEN #REQUIRED&gt; - &lt;!ELEMENT cache (properties)&gt; - &lt;!ATTLIST cache - enabled NMTOKEN #REQUIRED - class NMTOKEN #REQUIRED - &gt; - &lt;!ELEMENT query-handler (properties)&gt; - &lt;!ATTLIST query-handler class NMTOKEN #REQUIRED&gt; - &lt;!ELEMENT access-manager (properties)&gt; - &lt;!ATTLIST access-manager class NMTOKEN #REQUIRED&gt; - &lt;!ELEMENT lock-manager (time-out,persister)&gt; - &lt;!ELEMENT time-out (#PCDATA)&gt; - &lt;!ELEMENT persister (properties)&gt; - &lt;!ELEMENT properties (property+)&gt; - &lt;!ELEMENT property EMPTY&gt;</programlisting> - </section> - </section> -</chapter> Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/core/core.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/core/core.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/core/core.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,18 +1,20 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter> - <title>eXo Core</title> - - <section> - <title>eXo Core introduction</title> - - <para>The eXo Core is a set of common services that are used by eXo - products and modules, it also can be used in the business logic.</para> - - <para>It's Authentication and Security, Organization, Database, Logging, - JNDI, LDAP, Document reader and other services. Find more on <ulink - url="http://wiki.exoplatform.org/xwiki/bin/view/Core/">eXo - site</ulink></para> - </section> -</chapter> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter> + <?dbhtml filename="ch-core.html"?> + + <title>eXo Core</title> + + <section> + <title>eXo Core introduction</title> + + <para>The eXo Core is a set of common services that are used by eXo + products and modules, it also can be used in the business logic.</para> + + <para>It's Authentication and Security, Organization, Database, Logging, + JNDI, LDAP, Document reader and other services. Find more on <ulink + url="http://wiki.exoplatform.org/xwiki/bin/view/Core/">eXo + site</ulink></para> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/core.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/core.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/core.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<part> + <?dbhtml filename="part-core.html"?> + + <title>eXoCore</title> + + <xi:include href="core/core.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> +</part> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/external-value-storages.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/external-value-storages.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/external-value-storages.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,247 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_external_value_storages"> - <?dbhtml filename="external-value-storages.html"?> - <title>External Value Storages</title> - - <section> - <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 (see [TODOBinary values processing link]).</para> - - <para>Value storage configuration is a part of Repository configuration, - find more details <link - linkend="sect_repository_service_configuration">there</link>.</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.</para> - </section> - - <section> - <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.</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.</para> - - <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> - - <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></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.</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".</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> - </section> - - <section> - <title>S3 File Value Storage</title> - - <para>Holds Values at Amazon S3 storage. For more about S3 see <ulink - url="http://www.amazon.com/S3-AWS-home-page-Money/b/ref=sc_fe_l_2/10... - - <para>This type of storage saves all matching Values on Amazon S3 service. - That is very useful for <phrase>cloud computing</phrase> (like Amazon EC2 - hosted repositories). But can be used in any environment and storages - combinations. It's often used in combined with Workspace Simple DB storage - [TODO Workspace Simple DB storage].</para> - - <para>It's networked storage with RESTbased access (via HTTP) that makes a - footprint on performance of the Repository.</para> - - <programlisting>&lt;value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.s3.SimpleS3ValueStorage"&gt; - &lt;properties&gt; - &lt;property name="bucket" value="BUCKET NAME HERE"/&gt; - &lt;property name="aws-access-key" value="INSERT YOUR AWS ACCESS KEY ID HERE"/&gt; - &lt;property name="aws-secret-access-key" value="INSERT YOUR AWS SECRET ACCESS KEY HERE"/&gt; - &lt;property name="s3-swap-directory" value="s3swap_directory_name"/&gt; - &lt;/properties&gt; - &lt;filters&gt; - &lt;filter property-type="Binary"/&gt; - &lt;/filters&gt; -&lt;/value-storage&gt;</programlisting> - </section> - - <section> - <title>Simple File Value Storage</title> - - <note> - <para>Not recommended to use in production due to low capacity - capabilities on most file systems.</para> - - <para>But if you're sure in your file-system or data amount is small it - may be useful for you as haves a faster speed of Value removal.</para> - </note> - - <para>Holds Values in flat FileSystem files. <property>path</property> - property points to root directory in order to store files</para> - - <programlisting>&lt;value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.SimpleFileValueStorage"&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> - </section> - - <section> - <title>Content Addressable Value storage (CAS) support</title> - - <remark>Available from version 1.9.3</remark> - - <para>eXo JCR supports <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 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.</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.</para> - - <para>Content address calculation based on java.security.MessageDigest - hash computation and tested with <abbrev>MD5</abbrev> and - <abbrev>SHA1</abbrev> 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.</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.</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> - </section> -</chapter> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/intro.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/intro.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/intro.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,70 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter> - <?dbhtml filename="intro.html"?> - - <title>Introduction in eXoJCR</title> - - <section> - <title>JCR (JSR-170) API main concepts</title> - - <para>Java Content Repository API as well as other Java language related - standards is created within the Java Community Process http://jcp.org/ as - a result of collaboration of an expert group and the Java community and - known as JSR-170 (Java Specification Request) - http://www.jcp.org/en/jsr/detail?id=170.</para> - - <section> - <title>Data model</title> - - <para>As the main purpose of content repository is to maintain the data - - the heart of CR is the data model:</para> - - <para><itemizedlist> - <listitem> - <para>The main data storage abstraction of JCR's data model is a - workspace</para> - </listitem> - - <listitem> - <para>Each repository should have one or more workspaces</para> - </listitem> - - <listitem> - <para>The content is stored in a workspace as a hierarchy of - items</para> - </listitem> - - <listitem> - <para>Each workspace has its own hierarchy of items</para> - </listitem> - </itemizedlist></para> - - <figure> - <title>Item hierarchy</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/item-hierarchy.gif" /> - </imageobject> - </mediaobject> - </figure> - - <para>Node is intended to support the data hierarchy. They are typed - using namespaced names which allows the content to be structured - according to standardized constraints. A node may be versioned through - an associated version graph (optional feature)</para> - - <para>Property stored data are values of predefined types (String, - Binary, Long, Boolean, Double, Date, Reference, Path).</para> - - <para>It is important to note that the data model for the interface (the - repository model) is rarely the same as the data models used by the - repository's underlying storage subsystems. The repository knows how to - make the client's changes persistent because that is part of the - repository configuration, rather than part of the application - programming task.</para> - </section> - </section> -</chapter> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jbosscache-configuration-templates.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jbosscache-configuration-templates.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jbosscache-configuration-templates.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,266 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_jbosscache_config_templates"> - - <?dbhtml filename="jbosscache-configuration-templates.html"?> - - <title>JBoss Cache configuration</title> - - <section> - <title>JBoss cache configuration for 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: </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:</para> - - <para>template: </para> - - <programlisting>... -&lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; -...</programlisting> - - <para>and 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> - </section> - - <section> - <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. </para> - - <programlisting>&lt;property name="jgroups-configuration" value="your/path/to/modified-udp.xml" /&gt;</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".</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> - </section> - - <section> - <title>Shipped JBoss Cache configuration 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.</para> - - <section> - <title>Data container template</title> - - <para>Data container template is "jbosscache-data.xml" It's</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.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> - <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> - - <section> - <title>Lock manager template</title> - - <para>It's template name is "jbosscache-lock.xml" </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;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; - cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name} - cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create} - cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop} - cache.jdbc.table.primarykey=${jbosscache-cl-cache.jdbc.table.primarykey} - cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column} - cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type} - cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column} - cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type} - cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column} - cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource} - &lt;/properties&gt; - &lt;/loader&gt; - &lt;/loaders&gt; -&lt;/jbosscache&gt;</programlisting> - - <table> - <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> - - <section> - <title>Query handler (indexer) template</title> - - <para>Have a look at "jbosscache-indexer.xml" </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> - <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> - </section> -</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/architecture.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/architecture.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/architecture.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="architecture" xreflabel="architectural"> + <?dbhtml filename="ch-architecture.html"?> + <chapterinfo> + <keywordset> + <keyword>JCR</keyword> + <keyword>eXoJCR</keyword> + <keyword>etc</keyword> + </keywordset> + </chapterinfo> + <title>Basic concepts of eXoJCR</title> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,262 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="ch_cluster_configuration"> + <?dbhtml filename="ch-cluster-config.html"?> + + <title>Configuring JBoss AS with eXo JCR in cluster</title> + + <section> + <title>Launching Cluster</title> + + <section> + <title>Deploying eXo JCR to JBoss As</title> + + <para>To deploy eXo JCR to JBoss As follow next steps:</para> + + <orderedlist> + <listitem> + <para>Dowload the latest version of eXo JCR ear distribution from + [LINK THERE]</para> + </listitem> + + <listitem> + <para>Copy &lt;jcr.ear&gt; into + &lt;%jboss_home%/server/default/deploy&gt;</para> + </listitem> + + <listitem> + <para>Put exo-configuration.xml to the root + &lt;%jboss_home%/exo-configuration.xml&gt;</para> + </listitem> + + <listitem> + <para>Configure JAAS by inserting XML fragment shown below into + &lt;%jboss_home%/server/default/conf/login-config.xml&gt;</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> + <para>Start server:</para> + + <itemizedlist> + <listitem> + <para>bin/run.sh for Unix</para> + </listitem> + + <listitem> + <para>bin/run.bat for Windows</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>Try accessing <uri>http://localhost:8080/browser</uri> with + root/exo as login/password if you have done everything right, you'll + get access to repository browser.</para> + </listitem> + </orderedlist> + </section> + + <section id="sect_conf_cluster_jcr"> + <title>Configuring JCR to use external configuration</title> + + <itemizedlist> + <listitem> + <para>To manually configure repository create a new configuration + file (f.e. exo-jcr-configuration.xml). For details see <link + linkend="ch_configuration">JCR Configuration</link>. Your + configuration must look like:</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; + see "<link linkend="conf_value_storage">Value storage configuration</link>" part. + &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; + see "<link linkend="conf_cache">Cache configuration</link>" part. + &lt;/cache&gt; + &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + see "<link linkend="conf_indexer">Indexer configuration</link>" part. + &lt;/query-handler&gt; + &lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; + see "<link linkend="conf_lock_manager">Lock Manager configuration</link>" part. + &lt;/lock-manager&gt; + &lt;/workspace&gt; + &lt;workspace name="ws2"&gt; + ... + &lt;/workspace&gt; + &lt;workspace name="wsN"&gt; + ... + &lt;/workspace&gt; + &lt;/workspaces&gt; + &lt;/repository&gt; + &lt;/repositories&gt; +&lt;/repository-service&gt; </programlisting> + </listitem> + + <listitem> + <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></para> + </listitem> + </itemizedlist> + </section> + </section> + + <section> + <title>Requirements</title> + + <section> + <title>Enviorenment requirements</title> + + <itemizedlist> + <listitem> + <para>Every node of cluster MUST have the same mounted Network File + System with read and write permissions on it.</para> + + <para>"/mnt/tornado" - path to the mounted Network File System (all + cluster nodes must use the same NFS)</para> + </listitem> + + <listitem> + <para>Every node of cluster MUST use the same database</para> + </listitem> + + <listitem> + <para>Same Clusters on different nodes MUST have the same cluster + names (f.e if Indexer cluster in workspace production on the first + node has name "production_indexer_cluster", then indexer clusters in + workspace production on all other nodes MUST have the same name + "production_indexer_cluster" )</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Enviorenment requirements</title> + + <para>Configuration of every workspace in repository must contains of + such parts:</para> + + <itemizedlist> + <listitem id="conf_value_storage"> + <para>Value Storage configuration:</para> + + <programlisting>&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> + + <para>See more about <link + linkend="ch_external_value_storages">ValueStorage + configuration</link>.</para> + </listitem> + + <listitem id="conf_cache"> + <para>Cache configuration:</para> + + <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> + + <para>See more about <link + linkend="ch_jbosscache_config_templates">Cache + configuration</link>.</para> + </listitem> + + <listitem id="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> + + <para>See more about <link + linkend="ch_query_handler_config">QueryHandler + configuration</link>.</para> + </listitem> + + <listitem id="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; + + &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> + + <para>See more about <link + linkend="ch_lock_manager_config">LockManager + configuration</link>.</para> + </listitem> + </itemizedlist> + </section> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration-persister.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration-persister.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration-persister.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,124 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="ch_configuration_persister"> + <?dbhtml filename="ch-configuration-persister.html"?> + <title>JCR Configuration persister</title> + + <section> + <title>Idea</title> + + <para>JCR Repository Service uses + <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> + + <para>In the example 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.</para> + + <para>In this case we have to use the configuration persister feature + which allows to store the configuration in different locations.</para> + </section> + + <section> + <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.</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></para> + + <para>Where:<itemizedlist> + <listitem> + <para><parameter>source-name</parameter> - JNDI source name + configured in <classname>InitialContextInitializer</classname> + component. (<parameter>sourceName</parameter> prior v.1.9.) Find + more in <link linkend="ch_configuration">database + configuration</link>.</para> + </listitem> + + <listitem> + <para><parameter>dialect</parameter> - SQL dialect which will be + used with database from <parameter>source-name</parameter>. Find + more in <link linkend="ch_configuration">database + configuration</link>.</para> + </listitem> + + <listitem> + <para><parameter>persister-class-name</parameter> - class name of + <classname>ConfigurationPersister</classname> interface + implementation. (<parameter>persisterClassName</parameter> prior + v.1.9.)</para> + </listitem> + </itemizedlist></para> + + <para>ConfigurationPersister interface:<programlisting>/** + * Init persister. + * Used by RepositoryServiceConfiguration on init. + * @return - config data stream + */ + void init(PropertiesParam params) throws RepositoryConfigurationException; + + /** + * Read config data. + * @return - config data stream + */ + InputStream read() throws RepositoryConfigurationException; + + /** + * Create table, write data. + * @param confData - config data stream + */ + void write(InputStream confData) throws RepositoryConfigurationException; + + /** + * Tell if the config exists. + * @return - flag + */ + 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>.</para> + + <para>The implementation will crate and use table JCR_CONFIG in the + provided database.</para> + + <para>But the developer can implement his own persister for his particular + usecase.</para> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,436 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="ch_configuration"> + <?dbhtml filename="ch-configuration.html"?> + + <title>eXo JCR configuration</title> + + <section> + <title>Related documents</title> + + <itemizedlist> + <listitem> + <para><link linkend="ch_search_configuration">Search + Configuration</link></para> + </listitem> + + <listitem> + <para><link linkend="ch_jdbc_data_container">JDBC Data Container + config</link></para> + </listitem> + + <listitem> + <para><link linkend="ch_external_value_storages">External Value + Storages</link></para> + </listitem> + </itemizedlist> + </section> + + <section> + <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 and the second option is to use a Standalone container. The main + difference between these container types is that the first one is intended + to be used in a Portal (Web) environment, while the second one can be used + standalone (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 (TODO find more in Container configuration):</para> + + <itemizedlist> + <listitem> + <para>Configuration that is set explicitly using + StandaloneContainer.addConfigurationURL(String url) or + StandaloneContainer.addConfigurationPath(String path) before + getInstance()</para> + </listitem> + + <listitem> + <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> + </listitem> + + <listitem> + <para>/conf/exo-configuration.xml in the current classloader (e.g. + war, ear archive)</para> + </listitem> + + <listitem> + <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> + </listitem> + </itemizedlist> + + <para>JCR service configuration looks like:</para> + + <programlisting>&lt;component&gt; + &lt;key&gt;org.exoplatform.services.jcr.RepositoryService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.jcr.impl.RepositoryServiceImpl&lt;/type&gt; + &lt;/component&gt; + &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 repositories configuration file&lt;/description&gt; + &lt;value&gt;jar:/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="hsqldb" /&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> + + <para>conf-path : a path to a RepositoryService JCR Configuration</para> + + <para>working-conf : optional; JCR configuration persister configuration. + If there isn't a working-conf the persister will be disabled</para> + + <section> + <title>JCR Configuration</title> + + <para>The Configuration is defined in an XML file (see DTD + below).</para> + + <para>JCR Service can use multiple Repositories and each repository can + have multiple Workspaces.</para> + + <para>Repositories configuration parameters support human-readable + formats of values. They are all case-insensitive:</para> + + <itemizedlist> + <listitem> + <para>Numbers formats: K,KB - kilobytes, M,MB - megabytes, G,GB - + gigabytes, T,TB - terabytes.</para> + + <para>Examples: 100.5 - digit 100.5, 200k - 200 Kbytes, 4m - 4 + Mbytes, 1.4G - 1.4 Gbytes, 10T - 10 Tbytes</para> + </listitem> + + <listitem> + <para>Time format endings: ms - milliseconds, s - seconds, m - + minutes, h - hours, d - days, w - weeks, if no ending - + seconds.</para> + + <para>Examples: 500ms - 500 milliseconds, 20 or 20s - 20 seconds, + 30m - 30 minutes, 12h - 12 hours, 5d - 5 days, 4w - 4 weeks.</para> + </listitem> + </itemizedlist> + + <para></para> + </section> + + <section id="sect_repository_service_configuration"> + <title>Repository service configuration</title> + + <para>Default configuration of the Repository Service located in + jar:/conf/portal/exo-jcr-config.xml, it will be available for portal and + standalone modes.</para> + + <para>In portal mode it is overriden and located in the portal web + application portal/WEB-INF/conf/jcr/repository-configuration.xml.</para> + + <para>Example of Repository Service configuration for standalone + mode:</para> + + <programlisting>&lt;repository-service default-repository="repository"&gt; + &lt;repositories&gt; + &lt;repository name="db1" system-workspace="ws" default-workspace="ws"&gt; + &lt;security-domain&gt;exo-domain&lt;/security-domain&gt; + &lt;access-control&gt;optional&lt;/access-control&gt; + &lt;session-max-age&gt;1h&lt;/session-max-age&gt; + &lt;authentication-policy&gt;org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator&lt;/authentication-policy&gt; + &lt;workspaces&gt; + &lt;workspace name="production"&gt; + &lt;!-- for system storage --&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="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; + &lt;value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; + &lt;properties&gt; + &lt;property name="path" value="../temp/values/production" /&gt; + &lt;/properties&gt; + &lt;filters&gt; + &lt;filter property-type="Binary" /&gt; + &lt;/filters&gt; + &lt;/value-storage&gt; + &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.LinkedWorkspaceStorageCacheImpl"&gt; + &lt;properties&gt; + &lt;property name="max-size" value="10k" /&gt; + &lt;property name="live-time" value="1h" /&gt; + &lt;/properties&gt; + &lt;/cache&gt; + &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + &lt;properties&gt; + &lt;property name="index-dir" value="../temp/jcrlucenedb/production" /&gt; + &lt;/properties&gt; + &lt;/query-handler&gt; + &lt;lock-manager&gt; + &lt;time-out&gt;15m&lt;/time-out&gt; + &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; + &lt;properties&gt; + &lt;property name="path" value="../temp/lock/system" /&gt; + &lt;/properties&gt; + &lt;/persister&gt; + &lt;/lock-manager&gt; + &lt;/workspace&gt; + + &lt;workspace name="backup"&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="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/backup" /&gt; + &lt;/properties&gt; + &lt;value-storages&gt; + &lt;value-storage id="draft" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; + &lt;properties&gt; + &lt;property name="path" value="../temp/values/backup" /&gt; + &lt;/properties&gt; + &lt;filters&gt; + &lt;filter property-type="Binary" /&gt; + &lt;/filters&gt; + &lt;/value-storage&gt; + &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.LinkedWorkspaceStorageCacheImpl"&gt; + &lt;properties&gt; + &lt;property name="max-size" value="10k" /&gt; + &lt;property name="live-time" value="1h" /&gt; + &lt;/properties&gt; + &lt;/cache&gt; + &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + &lt;properties&gt; + &lt;property name="index-dir" value="../temp/jcrlucenedb/backup" /&gt; + &lt;/properties&gt; + &lt;/query-handler&gt; + &lt;/workspace&gt; + &lt;/workspaces&gt; + &lt;/repository&gt; + &lt;/repositories&gt; +&lt;/repository-service&gt; +</programlisting> + + <para>Repository Service configuration:</para> + + <para>default-repository - the name of a default repository (one + returned by RepositoryService.getRepository())</para> + + <para>repositories - the list of repositories</para> + + <para>Repository configuration:</para> + + <para>name - the name of a repository</para> + + <para>default-workspace - the name of a workspace obtained using + Session's login() or login(Credentials) methods (ones without an + explicit workspace name)</para> + + <para>system-workspace - name of workspace where /jcr:system node is + placed</para> + + <para>security-domain - the name of a security domain for JAAS + authentication</para> + + <para>access-control - 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> + + <para>authentication-policy - the name of an authentication policy + class</para> + + <para>workspaces - the list of workspaces</para> + + <para>session-max-age - the time after which an idle session will be + removed (called logout). If not set, the idle session will never be + removed.</para> + + <para>Workspace configuration:</para> + + <para>name - the name of a workspace</para> + + <para>auto-init-root-nodetype - DEPRECATED in JCR 1.9 (use initializer). + The node type for root node initialization</para> + + <para>container - workspace data container (physical storage) + configuration</para> + + <para>initializer - workspace initializer configuration</para> + + <para>cache - workspace storage cache configuration</para> + + <para>query-handler - query handler configuration</para> + + <para>Workspace data container configuration:</para> + + <para>class - A workspace data container class name</para> + + <para>properties - the list of properties (name-value pairs) for the + concrete Workspace data container</para> + + <para>value-storages - the list of value storage plugins</para> + + <para>Value Storage plugin configuration (optional feature):</para> + + <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> + + <para>value-storage - Optional value Storage plugin definition</para> + + <para>class- a value storage plugin class name (attribute)</para> + + <para>properties - the list of properties (name-value pairs) for a + concrete Value Storage plugin</para> + + <para>filters - the list of filters defining conditions when this plugin + is applicable</para> + + <para>Initializer configuration (optional):</para> + + <para>class - initializer implementation class.</para> + + <para>properties - the list of properties (name-value pairs). Properties + are supported:</para> + + <para>root-nodetype - The node type for root node initialization</para> + + <para>root-permissions - 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.</para> + + <para>Configurable initializer adds a capability to override workspace + initial startup procedure.</para> + + <para>Cache configuration:</para> + + <para>enabled - if workspace cache is enabled</para> + + <para>class - cache implementation class, optional from 1.9. Default + value is + org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl.</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> + + <para>properties - the list of properties (name-value pairs) for + Workspace cache:</para> + + <para>max-size - cache maximum size.</para> + + <para>live-time - cached item live time.</para> + + <para>LinkedWorkspaceStorageCacheImpl supports additional optional + parameters TODO</para> + + <para>Query Handler configuration:</para> + + <para>class - A Query Handler class name</para> + + <para>properties - the list of properties (name-value pairs) for a Query + Handler (indexDir) properties and advanced features described in *Search + Configuration*</para> + + <para>Lock Manager configuration:</para> + + <para>time-out - time after which the unused global lock will be + removed.</para> + + <para>persister - a class for storing lock information for future use. + For example, remove lock after jcr restart.</para> + + <para>path - a lock folder, each workspace has its own.</para> + + <para></para> + + <para>Configuration definition:</para> + + <programlisting>&lt;!ELEMENT repository-service (repositories)&gt; + &lt;!ATTLIST repository-service default-repository NMTOKEN #REQUIRED&gt; + &lt;!ELEMENT repositories (repository)&gt; + &lt;!ELEMENT repository (security-domain,access-control,session-max-age,authentication-policy,workspaces)&gt; + &lt;!ATTLIST repository + default-workspace NMTOKEN #REQUIRED + name NMTOKEN #REQUIRED + system-workspace NMTOKEN #REQUIRED + &gt; + &lt;!ELEMENT security-domain (#PCDATA)&gt; + &lt;!ELEMENT access-control (#PCDATA)&gt; + &lt;!ELEMENT session-max-age (#PCDATA)&gt; + &lt;!ELEMENT authentication-policy (#PCDATA)&gt; + &lt;!ELEMENT workspaces (workspace+)&gt; + &lt;!ELEMENT workspace (container,initializer,cache,query-handler)&gt; + &lt;!ATTLIST workspace name NMTOKEN #REQUIRED&gt; + &lt;!ELEMENT container (properties,value-storages)&gt; + &lt;!ATTLIST container class NMTOKEN #REQUIRED&gt; + &lt;!ELEMENT value-storages (value-storage+)&gt; + &lt;!ELEMENT value-storage (properties,filters)&gt; + &lt;!ATTLIST value-storage class NMTOKEN #REQUIRED&gt; + &lt;!ELEMENT filters (filter+)&gt; + &lt;!ELEMENT filter EMPTY&gt; + &lt;!ATTLIST filter property-type NMTOKEN #REQUIRED&gt; + &lt;!ELEMENT initializer (properties)&gt; + &lt;!ATTLIST initializer class NMTOKEN #REQUIRED&gt; + &lt;!ELEMENT cache (properties)&gt; + &lt;!ATTLIST cache + enabled NMTOKEN #REQUIRED + class NMTOKEN #REQUIRED + &gt; + &lt;!ELEMENT query-handler (properties)&gt; + &lt;!ATTLIST query-handler class NMTOKEN #REQUIRED&gt; + &lt;!ELEMENT access-manager (properties)&gt; + &lt;!ATTLIST access-manager class NMTOKEN #REQUIRED&gt; + &lt;!ELEMENT lock-manager (time-out,persister)&gt; + &lt;!ELEMENT time-out (#PCDATA)&gt; + &lt;!ELEMENT persister (properties)&gt; + &lt;!ELEMENT properties (property+)&gt; + &lt;!ELEMENT property EMPTY&gt;</programlisting> + </section> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/external-value-storages.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/external-value-storages.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/external-value-storages.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,247 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="ch_external_value_storages"> + <?dbhtml filename="ch-external-value-storages.html"?> + <title>External Value Storages</title> + + <section> + <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 (see [TODOBinary values processing link]).</para> + + <para>Value storage configuration is a part of Repository configuration, + find more details <link + linkend="sect_repository_service_configuration">there</link>.</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.</para> + </section> + + <section> + <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.</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.</para> + + <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> + + <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></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.</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".</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> + </section> + + <section> + <title>S3 File Value Storage</title> + + <para>Holds Values at Amazon S3 storage. For more about S3 see <ulink + url="http://www.amazon.com/S3-AWS-home-page-Money/b/ref=sc_fe_l_2/10... + + <para>This type of storage saves all matching Values on Amazon S3 service. + That is very useful for <phrase>cloud computing</phrase> (like Amazon EC2 + hosted repositories). But can be used in any environment and storages + combinations. It's often used in combined with Workspace Simple DB storage + [TODO Workspace Simple DB storage].</para> + + <para>It's networked storage with RESTbased access (via HTTP) that makes a + footprint on performance of the Repository.</para> + + <programlisting>&lt;value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.s3.SimpleS3ValueStorage"&gt; + &lt;properties&gt; + &lt;property name="bucket" value="BUCKET NAME HERE"/&gt; + &lt;property name="aws-access-key" value="INSERT YOUR AWS ACCESS KEY ID HERE"/&gt; + &lt;property name="aws-secret-access-key" value="INSERT YOUR AWS SECRET ACCESS KEY HERE"/&gt; + &lt;property name="s3-swap-directory" value="s3swap_directory_name"/&gt; + &lt;/properties&gt; + &lt;filters&gt; + &lt;filter property-type="Binary"/&gt; + &lt;/filters&gt; +&lt;/value-storage&gt;</programlisting> + </section> + + <section> + <title>Simple File Value Storage</title> + + <note> + <para>Not recommended to use in production due to low capacity + capabilities on most file systems.</para> + + <para>But if you're sure in your file-system or data amount is small it + may be useful for you as haves a faster speed of Value removal.</para> + </note> + + <para>Holds Values in flat FileSystem files. <property>path</property> + property points to root directory in order to store files</para> + + <programlisting>&lt;value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.SimpleFileValueStorage"&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> + </section> + + <section> + <title>Content Addressable Value storage (CAS) support</title> + + <remark>Available from version 1.9.3</remark> + + <para>eXo JCR supports <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 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.</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.</para> + + <para>Content address calculation based on java.security.MessageDigest + hash computation and tested with <abbrev>MD5</abbrev> and + <abbrev>SHA1</abbrev> 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.</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.</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> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/intro.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/intro.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/intro.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter> + <?dbhtml filename="ch-intro.html"?> + + <title>Introduction in eXoJCR</title> + + <section> + <title>JCR (JSR-170) API main concepts</title> + + <para>Java Content Repository API as well as other Java language related + standards is created within the Java Community Process http://jcp.org/ as + a result of collaboration of an expert group and the Java community and + known as JSR-170 (Java Specification Request) + http://www.jcp.org/en/jsr/detail?id=170.</para> + + <section> + <title>Data model</title> + + <para>As the main purpose of content repository is to maintain the data + - the heart of CR is the data model:</para> + + <para><itemizedlist> + <listitem> + <para>The main data storage abstraction of JCR's data model is a + workspace</para> + </listitem> + + <listitem> + <para>Each repository should have one or more workspaces</para> + </listitem> + + <listitem> + <para>The content is stored in a workspace as a hierarchy of + items</para> + </listitem> + + <listitem> + <para>Each workspace has its own hierarchy of items</para> + </listitem> + </itemizedlist></para> + + <figure> + <title>Item hierarchy</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/item-hierarchy.gif" /> + </imageobject> + </mediaobject> + </figure> + + <para>Node is intended to support the data hierarchy. They are typed + using namespaced names which allows the content to be structured + according to standardized constraints. A node may be versioned through + an associated version graph (optional feature)</para> + + <para>Property stored data are values of predefined types (String, + Binary, Long, Boolean, Double, Date, Reference, Path).</para> + + <para>It is important to note that the data model for the interface (the + repository model) is rarely the same as the data models used by the + repository's underlying storage subsystems. The repository knows how to + make the client's changes persistent because that is part of the + repository configuration, rather than part of the application + programming task.</para> + </section> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jbosscache-configuration-templates.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jbosscache-configuration-templates.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jbosscache-configuration-templates.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,266 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="ch_jbosscache_config_templates"> + + <?dbhtml filename="ch-jbosscache-configuration-templates.html"?> + + <title>JBoss Cache configuration</title> + + <section> + <title>JBoss cache configuration for 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: </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:</para> + + <para>template: </para> + + <programlisting>... +&lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; + &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; +...</programlisting> + + <para>and 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> + </section> + + <section> + <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. </para> + + <programlisting>&lt;property name="jgroups-configuration" value="your/path/to/modified-udp.xml" /&gt;</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".</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> + </section> + + <section> + <title>Shipped JBoss Cache configuration 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.</para> + + <section> + <title>Data container template</title> + + <para>Data container template is "jbosscache-data.xml" It's</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.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> + <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> + + <section> + <title>Lock manager template</title> + + <para>It's template name is "jbosscache-lock.xml" </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;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; + cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name} + cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create} + cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop} + cache.jdbc.table.primarykey=${jbosscache-cl-cache.jdbc.table.primarykey} + cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column} + cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type} + cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column} + cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type} + cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column} + cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource} + &lt;/properties&gt; + &lt;/loader&gt; + &lt;/loaders&gt; +&lt;/jbosscache&gt;</programlisting> + + <table> + <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> + + <section> + <title>Query handler (indexer) template</title> + + <para>Have a look at "jbosscache-indexer.xml" </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> + <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> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jdbc-data-container-config.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jdbc-data-container-config.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jdbc-data-container-config.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,533 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="ch_jdbc_data_container"> + <?dbhtml filename="ch-jdbc-data-container-config.html"?> + + <title>JDBC Data Container Config</title> + + <section> + <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></para> + + <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.</para> + + <para>Currently the data container is tested with the following + RDBMS:<itemizedlist> + <listitem> + <para>MySQL (5.x including UTF8 support)</para> + </listitem> + + <listitem> + <para>PostgreSQL (8.x)</para> + </listitem> + + <listitem> + <para>Oracle Database (9i, 10g)</para> + </listitem> + + <listitem> + <para>Microsoft SQL Server (2005)</para> + </listitem> + + <listitem> + <para>Sybase ASE (15.0)</para> + </listitem> + + <listitem> + <para>Apache Derby/Java DB (10.1.x, 10.2.x)</para> + </listitem> + + <listitem> + <para>IBM DB2 (8.x, 9.x)</para> + </listitem> + + <listitem> + <para>HSQLDB (1.8.0.7)</para> + </listitem> + </itemizedlist></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.</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<... + + <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.</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).</para> + + <para>Read more about <link linkend="ch_configuration">Repository + configuration</link>.</para> + </section> + + <section> + <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.</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.</para> + + <para>Example (standalone mode, two data containers + <parameter>jdbcjcr</parameter> - local HSQLDB, + <parameter>jdbcjcr1</parameter> - remote MySQL):<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; + &lt;component-plugins&gt; + &lt;component-plugin&gt; + &lt;name&gt;bind.datasource&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;bind-name&lt;/name&gt; + &lt;value&gt;jdbcjcr&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;class-name&lt;/name&gt; + &lt;value&gt;javax.sql.DataSource&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;factory&lt;/name&gt; + &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt; + &lt;/value-param&gt; + &lt;properties-param&gt; + &lt;name&gt;ref-addresses&lt;/name&gt; + &lt;description&gt;ref-addresses&lt;/description&gt; + &lt;property name="driverClassName" value="org.hsqldb.jdbcDriver"/&gt; + &lt;property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/&gt; + &lt;property name="username" value="sa"/&gt; + &lt;property name="password" value=""/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;component-plugin&gt; + &lt;name&gt;bind.datasource&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;bind-name&lt;/name&gt; + &lt;value&gt;jdbcjcr1&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;class-name&lt;/name&gt; + &lt;value&gt;javax.sql.DataSource&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;factory&lt;/name&gt; + &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt; + &lt;/value-param&gt; + &lt;properties-param&gt; + &lt;name&gt;ref-addresses&lt;/name&gt; + &lt;description&gt;ref-addresses&lt;/description&gt; + &lt;property name="driverClassName" value="com.mysql.jdbc.Driver"/&gt; + &lt;property name="url" value="jdbc:mysql://exoua.dnsalias.net/jcr"/&gt; + &lt;property name="username" value="exoadmin"/&gt; + &lt;property name="password" value="exo12321"/&gt; + &lt;property name="maxActive" value="50"/&gt; + &lt;property name="maxIdle" value="5"/&gt; + &lt;property name="initialSize" value="5"/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;component-plugins&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;default-context-factory&lt;/name&gt; + &lt;value&gt;org.exoplatform.services.naming.SimpleContextFactory&lt;/value&gt; + &lt;/value-param&gt; + &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):<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; + &lt;properties&gt; + &lt;property name="source-name" value="jdbcjcr"/&gt; + &lt;property name="dialect" value="hsqldb"/&gt; + &lt;property name="multi-db" value="true"/&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;/container&gt; + &lt;cache enabled="true"&gt; + &lt;properties&gt; + &lt;property name="max-size" value="10K"/&gt;&lt;!-- 10Kbytes --&gt; + &lt;property name="live-time" value="30m"/&gt;&lt;!-- 30 min --&gt; + &lt;/properties&gt; + &lt;/cache&gt; + &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + &lt;properties&gt; + &lt;property name="index-dir" value="target/temp/index"/&gt; + &lt;/properties&gt; + &lt;/query-handler&gt; + &lt;lock-manager&gt; + &lt;time-out&gt;15m&lt;/time-out&gt;&lt;!-- 15 min --&gt; + &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; + &lt;properties&gt; + &lt;property name="path" value="target/temp/lock/ws"/&gt; + &lt;/properties&gt; + &lt;/persister&gt; + &lt;/lock-manager&gt; + &lt;/workspace&gt; + &lt;workspace name="ws1" auto-init-root-nodetype="nt:unstructured"&gt; + &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; + &lt;properties&gt; + &lt;property name="source-name" value="jdbcjcr1"/&gt; + &lt;property name="dialect" value="mysql"/&gt; + &lt;property name="multi-db" value="true"/&gt; + &lt;property name="max-buffer-size" value="200K"/&gt; + &lt;property name="swap-directory" value="target/temp/swap/ws1"/&gt; + &lt;/properties&gt; + &lt;/container&gt; + &lt;cache enabled="true"&gt; + &lt;properties&gt; + &lt;property name="max-size" value="10K"/&gt; + &lt;property name="live-time" value="5m"/&gt; + &lt;/properties&gt; + &lt;/cache&gt; + &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + &lt;properties&gt; + &lt;property name="index-dir" value="target/temp/index"/&gt; + &lt;/properties&gt; + &lt;/query-handler&gt; + &lt;lock-manager&gt; + &lt;time-out&gt;15m&lt;/time-out&gt;&lt;!-- 15 min --&gt; + &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; + &lt;properties&gt; + &lt;property name="path" value="target/temp/lock/ws1"/&gt; + &lt;/properties&gt; + &lt;/persister&gt; + &lt;/lock-manager&gt; + &lt;/workspace&gt; +&lt;/workspaces&gt;</programlisting><itemizedlist> + <listitem> + <para><parameter>source-name</parameter> - a javax.sql.DataSource + name configured in InitialContextInitializer component (was + <parameter>sourceName</parameter> prior JCR 1.9);</para> + </listitem> + + <listitem> + <para><parameter>dialect</parameter> - a database dialect, one of + "hsqldb", "mysql", "mysql-utf8", "pgsql", "oracle", "oracle-oci", + "mssql", "sybase", "derby", "db2", "db2v8".</para> + </listitem> + + <listitem> + <para><parameter>multi-db</parameter> - enable multi-database + container with this parameter (set value "true");</para> + </listitem> + + <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.</para> + </listitem> + + <listitem> + <para><parameter>swap-directory</parameter> - a path in the file + system used to swap the pending changes.</para> + </listitem> + </itemizedlist></para> + + <para>In this way we have configured two workspace which will be persisted + in two different databases (ws in HSQLDB, ws1 in MySQL).</para> + + <note> + <para> Starting from v.1.9 <link linkend="ch_configuration">repository + configuration</link> parameters supports human-readable formats of + values (e.g. 200K - 200 Kbytes, 30m - 30 minutes etc)</para> + </note> + </section> + + <section> + <title>Single-database configuration</title> + + <para>It's more simple to configure a single-database data container. We + have to configure one naming resource.</para> + + <para>Example (embedded mode for <parameter>jdbcjcr</parameter> data + container):<programlisting>&lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;bind.datasource&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;bind-name&lt;/name&gt; + &lt;value&gt;jdbcjcr&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;class-name&lt;/name&gt; + &lt;value&gt;javax.sql.DataSource&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;factory&lt;/name&gt; + &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt; + &lt;/value-param&gt; + &lt;properties-param&gt; + &lt;name&gt;ref-addresses&lt;/name&gt; + &lt;description&gt;ref-addresses&lt;/description&gt; + &lt;property name="driverClassName" value="org.postgresql.Driver"/&gt; + &lt;property name="url" value="jdbc:postgresql://exoua.dnsalias.net/portal"/&gt; + &lt;property name="username" value="exoadmin"/&gt; + &lt;property name="password" value="exo12321"/&gt; + &lt;property name="maxActive" value="50"/&gt; + &lt;property name="maxIdle" value="5"/&gt; + &lt;property name="initialSize" value="5"/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt;</programlisting></para> + + <para>And configure repository workspaces in repositories configuration + with this one database. Parameter "multi-db" must be switched off (set + value "false").</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; + &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; + &lt;/container&gt; + &lt;cache enabled="true"&gt; + &lt;properties&gt; + &lt;property name="max-size" value="10K"/&gt; + &lt;property name="live-time" value="30m"/&gt; + &lt;/properties&gt; + &lt;/cache&gt; + &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + &lt;properties&gt; + &lt;property name="index-dir" value="../temp/index"/&gt; + &lt;/properties&gt; + &lt;/query-handler&gt; + &lt;lock-manager&gt; + &lt;time-out&gt;15m&lt;/time-out&gt; + &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; + &lt;properties&gt; + &lt;property name="path" value="target/temp/lock/ws"/&gt; + &lt;/properties&gt; + &lt;/persister&gt; + &lt;/lock-manager&gt; + &lt;/workspace&gt; + &lt;workspace name="ws1" auto-init-root-nodetype="nt:unstructured"&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/ws1"/&gt; + &lt;/properties&gt; + &lt;/container&gt; + &lt;cache enabled="true"&gt; + &lt;properties&gt; + &lt;property name="max-size" value="10K"/&gt; + &lt;property name="live-time" value="5m"/&gt; + &lt;/properties&gt; + &lt;/cache&gt; + &lt;lock-manager&gt; + &lt;time-out&gt;15m&lt;/time-out&gt; + &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; + &lt;properties&gt; + &lt;property name="path" value="target/temp/lock/ws1"/&gt; + &lt;/properties&gt; + &lt;/persister&gt; + &lt;/lock-manager&gt; + &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> + <title>Configuration without DataSource</title> + + <para>Repository configuration without using of the + <classname>javax.sql.DataSource</classname> bounded 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> + <para>You have to remove the configuration in + <classname>InitialContextInitializer</classname> for your database + and configure a new one directly in the workspace + container.</para> + </listitem> + + <listitem> + <para>Remove parameter "source-name" and add next lines instead. + Describe your values for a JDBC driver, database url and + username.</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> + + <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; + &lt;property name="dialect" value="hsqldb"/&gt; + &lt;property name="driverClassName" value="org.hsqldb.jdbcDriver"/&gt; + &lt;property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/&gt; + &lt;property name="username" value="su"/&gt; + &lt;property name="password" value=""/&gt; + ......</programlisting> + </section> + + <section> + <title>Dynamic Workspace Creation</title> + + <para>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></para> + </section> + </section> + + <section> + <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.</para> + + <para>Microsoft Windows has <parameter>MaxUserPort</parameter>, + <parameter>TcpTimedWaitDelay</parameter> registry keys in the node + <parameter>HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesTcpipParameters</parameter>, + by default these keys are unset, set each one with values like + these:<itemizedlist> + <listitem> + <para>"TcpTimedWaitDelay"=dword:0000001e, sets TIME_WAIT parameter + to 30 seconds, default is 240.</para> + </listitem> + + <listitem> + <para>"MaxUserPort"=dword:00001b58, sets the maximum of open ports + to 7000 or higher, default is 5000.</para> + </listitem> + </itemizedlist></para> + + <para>A sample registry file is below:<programlisting>Windows Registry Editor Version 5.00 + +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters] +"MaxUserPort"=dword:00001b58 +"TcpTimedWaitDelay"=dword:0000001e</programlisting></para> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/lock-manager-config.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/lock-manager-config.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/lock-manager-config.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,442 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="ch_lock_manager_config"> + <?dbhtml filename="ch-lock-manager-config.html"?> + + <title>LockManager configuration</title> + + <section> + <title>Introduction</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>Also LockManager is responsible for removing Locks that live too + long. This parameter may be configured with "time-out" property.</para> + + <para>JCR provide two base implementation of LockManager:</para> + + <itemizedlist> + <listitem> + <para><classname>org.exoplatform.services.jcr.impl.core.lock.LockManagerImpl</classname>;</para> + </listitem> + + <listitem> + <para><classname>org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl</classname>;</para> + </listitem> + </itemizedlist> + + <para>In this article we will talk mostly about + CacheableLockManagerImpl.</para> + + <para>You can enable LockManager by adding lock-manager-configuration to + workspace-configuration.</para> + + <para>For example:</para> + + <programlisting>&lt;workspace name="ws"&gt; + ... + &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;/properties&gt; + &lt;/lock-manager&gt; + ... +&lt;/workspace&gt;</programlisting> + </section> + + <section> + <title>LockManagerImpl</title> + + <para>LockManagerImpl is simple implementation of LockManager, and also + faster than CacheableLockManager. It stores Lock objects in HashMap and + may also persist Locks if LockPersister is configured. LockManagerImpl do + not support replication in any way.</para> + + <para>See more about LockManager Configuration <link + linkend="ch_configuration">here</link>.</para> + </section> + + <section> + <title>CacheableLockManagerImpl</title> + + <para>CacheableLockManagerImpl stores Lock object in JBoss-cache, so Locks + are replicable and affects on cluster, not only a single node. Also + JBoss-cache has JDBCCacheLoader, so locks will be stored to + database.</para> + + <para>Both implementation supports Expired Locks removing. There is + LockRemover - separate thread, that periodically ask LockManager for Locks + that lives to much and must be removed. So, timeout for LockRemover may be + set as follows, default value is 30m.</para> + + <programlisting>&lt;properties&gt; + &lt;property name="time-out" value="10m" /&gt; + ... +&lt;/properties&gt;</programlisting> + + <section> + <title>Configuration</title> + + <para>Replication requirements are same as for Cache</para> + + <para>Full JCR configuration example you can see <link + linkend="sect_conf_cluster_jcr">here</link>.</para> + + <para>Common tips:</para> + + <itemizedlist> + <listitem> + <para><parameter>clusterName</parameter> ("jbosscache-cluster-name") + must be unique;</para> + </listitem> + + <listitem> + <para><parameter>cache.jdbc.table.name</parameter> must be unique + per datasource;</para> + </listitem> + + <listitem> + <para><parameter>cache.jdbc.fqn.type</parameter> must and + cache.jdbc.node.type must be configured according to used + database;</para> + </listitem> + </itemizedlist> + + <para>There is few ways how to configure CacheableLockManagerImpl, and + all of them configures JBoss-cache and JDBCCacheLoader.</para> + + <para>See <ulink + url="http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader"... + </section> + + <section> + <title>Simple JbossCache Configuraion</title> + + <para>First one is - put JbossCache configuraion file path to + CacheableLockManagerImpl</para> + + <para><note> + <para>This configuration is not so good, as you can think. Because + repository may contain many workspaces, and each workspace must + contain LockManager configuration, and LockManager config may + contain JbossCache config file. So total configuration is growing + up. But it is usefull if we want a single LockManager with special + configuration.</para> + </note></para> + + <para>Config is:</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="conf/standalone/cluster/test-jbosscache-lock-config.xml" /&gt; + &lt;/properties&gt; +&lt;/lock-manager&gt;</programlisting> + + <para><filename>test-jbosscache-lock-config.xml</filename><programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.2"&gt; + + &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" lockAcquisitionTimeout="20000" /&gt; + + &lt;clustering mode="replication" clusterName="JBoss-Cache-Lock-Cluster_Name"&gt; + &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" nonBlocking="true" /&gt; + &lt;jgroupsConfig&gt; + + &lt;TCP bind_addr="127.0.0.1" start_port="9800" loopback="true" recv_buf_size="20000000" send_buf_size="640000" discard_incompatible_packets="true" + max_bundle_size="64000" max_bundle_timeout="30" use_incoming_packet_handler="true" enable_bundling="false" use_send_queues="false" sock_conn_timeout="300" + skip_suspected_members="true" use_concurrent_stack="true" thread_pool.enabled="true" thread_pool.min_threads="1" thread_pool.max_threads="25" + thread_pool.keep_alive_time="5000" thread_pool.queue_enabled="false" thread_pool.queue_max_size="100" thread_pool.rejection_policy="run" + oob_thread_pool.enabled="true" oob_thread_pool.min_threads="1" oob_thread_pool.max_threads="8" oob_thread_pool.keep_alive_time="5000" + oob_thread_pool.queue_enabled="false" oob_thread_pool.queue_max_size="100" oob_thread_pool.rejection_policy="run" /&gt; + &lt;MPING timeout="2000" num_initial_members="2" mcast_port="34540" bind_addr="127.0.0.1" mcast_addr="224.0.0.1" /&gt; + + + &lt;MERGE2 max_interval="30000" min_interval="10000" /&gt; + &lt;FD_SOCK /&gt; + &lt;FD max_tries="5" shun="true" timeout="10000" /&gt; + &lt;VERIFY_SUSPECT timeout="1500" /&gt; + &lt;pbcast.NAKACK discard_delivered_msgs="true" gc_lag="0" retransmit_timeout="300,600,1200,2400,4800" use_mcast_xmit="false" /&gt; + &lt;UNICAST timeout="300,600,1200,2400,3600" /&gt; + &lt;pbcast.STABLE desired_avg_gossip="50000" max_bytes="400000" stability_delay="1000" /&gt; + &lt;pbcast.GMS join_timeout="5000" print_local_addr="true" shun="false" view_ack_collection_timeout="5000" view_bundling="true" /&gt; + &lt;FRAG2 frag_size="60000" /&gt; + &lt;pbcast.STREAMING_STATE_TRANSFER /&gt; + &lt;pbcast.FLUSH timeout="0" /&gt; + + &lt;/jgroupsConfig + + &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; + cache.jdbc.table.name=jcrlocks_ws + cache.jdbc.table.create=true + cache.jdbc.table.drop=false + cache.jdbc.table.primarykey=jcrlocks_ws_pk + cache.jdbc.fqn.column=fqn + cache.jdbc.fqn.type=VARCHAR(512) + cache.jdbc.node.column=node + cache.jdbc.node.type=&lt;BLOB&gt; + cache.jdbc.parent.column=parent + cache.jdbc.datasource=jdbcjcr + &lt;/properties&gt; + &lt;/loader&gt; + + &lt;/loaders&gt; + +&lt;/jbosscache&gt;</programlisting></para> + + <para>Configuration requirements:</para> + + <itemizedlist> + <listitem> + <para>&lt;clustering mode="replication" + clusterName="JBoss-Cache-Lock-Cluster_Name"&gt; - cluster name must + be unique;</para> + </listitem> + + <listitem> + <para><parameter>cache.jdbc.table.name</parameter> must be unique + per datasource;</para> + </listitem> + + <listitem> + <para><parameter>cache.jdbc.node.type</parameter> and + <parameter>cache.jdbc.fqn.type</parameter> must be configured + according to using database. See <link endterm="datatypes.title" + linkend="datatypes"></link> .</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Template JBossCache Configuration</title> + + <para>Second one is - use template JBoss-cache configuration for all + LockManagers</para> + + <para><citetitle>Lock template configuration</citetitle></para> + + <para><filename>test-jbosscache-lock.xml</filename></para> + + <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; + + &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" + lockAcquisitionTimeout="20000" /&gt; + + &lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; + &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; + &lt;jgroupsConfig multiplexerStack="jcr.stack" /&gt; + &lt;sync /&gt; + &lt;/clustering&gt; + + &lt;loaders passivation="false" shared="true"&gt; + &lt;!-- All the data of the JCR locks needs to be loaded at startup --&gt; + &lt;preload&gt; + &lt;node fqn="/" /&gt; + &lt;/preload&gt; + &lt;!-- + For another cache-loader class you should use another template with + cache-loader specific parameters + -&gt; + &lt;loader class="org.jboss.cache.loader.JDBCCacheLoader" async=q"false" fetchPersistentState="false" + ignoreModifications="false" purgeOnStartup="false"&gt; + &lt;properties&gt; + cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name} + cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create} + cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop} + cache.jdbc.table.primarykey=${jbosscache-cl-cache.jdbc.table.primarykey} + cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column} + cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type} + cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column} + cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type} + cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column} + cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource} + &lt;/properties&gt; + &lt;/loader&gt; + &lt;/loaders&gt; +&lt;/jbosscache&gt;</programlisting> + + <para>As you see, all configurable paramaters filled by templates and + will be replaced by LockManagers conf parameters:</para> + + <programlisting>&lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; + &lt;properties&gt; + &lt;property name="time-out" value="15m" /&gt; + &lt;property name="jbosscache-configuration" value="test-jbosscache-lock.xml" /&gt; + &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; + &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; + &lt;property name="jbosscache-cluster-name" value="JCR-cluster-locks-ws" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_ws" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.create" value="true" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.drop" value="false" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_ws_pk" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.fqn.type" value="AUTO"/&gt; + &lt;property name="jbosscache-cl-cache.jdbc.node.column" value="node" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.node.type" value="AUTO"/&gt; + &lt;property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" /&gt; + &lt;/properties&gt; +&lt;/lock-manager&gt;</programlisting> + + <para>Configuration requirements:<itemizedlist> + <listitem> + <para><parameter>jbosscache-cl-cache.jdbc.fqn.column</parameter> + and <parameter>jbosscache-cl-cache.jdbc.node.type</parameter> is + nothing else as cache.jdbc.fqn.type and cache.jdbc.node.type in + JBoss-Cache configuration. You can set those data types according + to database type (See <link endterm="datatypes.title" + linkend="datatypes"></link>) or set it as AUTO (or do not set at + all) and data type will by detected automaticaly.</para> + </listitem> + + <listitem> + <para>as you see, jgroups-configuration moved to separate config + file - udp-mux.xml; In our case udp-mux.xml is common JGroup + config for all components (QueryHandler, cache, LockManager). But + we, still, can create own config.</para> + </listitem> + </itemizedlist></para> + + <para><filename>our-udp-mux.xml</filename><programlisting>&lt;protocol_stacks&gt; + &lt;stack name="jcr.stack"&gt; + &lt;config&gt; + &lt;UDP mcast_addr="228.10.10.10" mcast_port="45588" tos="8" ucast_recv_buf_size="20000000" + ucast_send_buf_size="640000" mcast_recv_buf_size="25000000" mcast_send_buf_size="640000" loopback="false" + discard_incompatible_packets="true" max_bundle_size="64000" max_bundle_timeout="30" + use_incoming_packet_handler="true" ip_ttl="2" enable_bundling="true" enable_diagnostics="true" + thread_naming_pattern="cl" use_concurrent_stack="true" thread_pool.enabled="true" thread_pool.min_threads="2" + thread_pool.max_threads="8" thread_pool.keep_alive_time="5000" thread_pool.queue_enabled="true" + thread_pool.queue_max_size="1000" thread_pool.rejection_policy="discard" oob_thread_pool.enabled="true" + oob_thread_pool.min_threads="1" oob_thread_pool.max_threads="8" oob_thread_pool.keep_alive_time="5000" + oob_thread_pool.queue_enabled="false" oob_thread_pool.queue_max_size="100" oob_thread_pool.rejection_policy="Run" /&gt; + + &lt;PING timeout="2000" num_initial_members="3" /&gt; + &lt;MERGE2 max_interval="30000" min_interval="10000" /&gt; + &lt;FD_SOCK /&gt; + &lt;FD timeout="10000" max_tries="5" shun="true" /&gt; + &lt;VERIFY_SUSPECT timeout="1500" /&gt; + &lt;BARRIER /&gt; + &lt;pbcast.NAKACK use_stats_for_retransmission="false" exponential_backoff="150" use_mcast_xmit="true" + gc_lag="0" retransmit_timeout="50,300,600,1200" discard_delivered_msgs="true" /&gt; + &lt;UNICAST timeout="300,600,1200" /&gt; + &lt;pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000" max_bytes="1000000" /&gt; + &lt;VIEW_SYNC avg_send_interval="60000" /&gt; + &lt;pbcast.GMS print_local_addr="true" join_timeout="3000" shun="false" view_bundling="true" /&gt; + &lt;FC max_credits="500000" min_threshold="0.20" /&gt; + &lt;FRAG2 frag_size="60000" /&gt; + &lt;!--pbcast.STREAMING_STATE_TRANSFER /--&gt; + &lt;pbcast.STATE_TRANSFER /&gt; + &lt;!-- pbcast.FLUSH /--&gt; + &lt;/config&gt; + &lt;/stack&gt; +&lt;/protocol_stacks&gt; </programlisting></para> + </section> + + <section id="datatypes"> + <title id="datatypes.title">Data Types in Different Databases</title> + + <table> + <title>Fqn type and node type in different databases</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>DataBase name</entry> + + <entry>Node data type</entry> + + <entry>FQN data type</entry> + </row> + </thead> + + <tbody> + <row> + <entry>default</entry> + + <entry>BLOB</entry> + + <entry>VARCHAR(512)</entry> + </row> + + <row> + <entry>HSSQL</entry> + + <entry>OBJECT</entry> + + <entry>VARCHAR(512)</entry> + </row> + + <row> + <entry>MySQL</entry> + + <entry>LONGBLOB</entry> + + <entry>VARCHAR(512)</entry> + </row> + + <row> + <entry>ORACLE</entry> + + <entry>BLOB</entry> + + <entry>VARCHAR2(512)</entry> + </row> + + <row> + <entry>PostgreSQL</entry> + + <entry>bytea</entry> + + <entry>VARCHAR(512)</entry> + </row> + + <row> + <entry>MSSQL</entry> + + <entry>VARBINARY(MAX)</entry> + + <entry>VARCHAR(512)</entry> + </row> + + <row> + <entry>DB2</entry> + + <entry>BLOB</entry> + + <entry>VARCHAR(512)</entry> + </row> + + <row> + <entry>Sybase</entry> + + <entry>IMAGE</entry> + + <entry>VARCHAR(512)</entry> + </row> + + <row> + <entry>Ingres</entry> + + <entry>long byte</entry> + + <entry>VARCHAR(512)</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/multilanguage-support.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/multilanguage-support.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/multilanguage-support.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,170 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="ch_multilanguage_support"> + <?dbhtml filename="ch-multilanguage-support.html"?> + + <title>Multilanguage support in eXo JCR RDB backend</title> + + <section> + <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.</para> + + <para>The configuration file you have to modify: + .../webapps/portal/WEB-INF/conf/jcr/repository-configuration.xml</para> + + <note> + <para>Datasource <parameter>jdbcjcr</parameter> used in examples can be + configured via <classname>InitialContextInitializer</classname> + component.</para> + </note> + </section> + + <section> + <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>.</para> + + <para>We have tested <constant>NLS_CHARACTERSET</constant> = + <constant>AL32UTF8</constant> and it's works well for many European and + Asian languages.</para> + + <para>Example of database configuration (used for JCR + testing):<programlisting>NLS_LANGUAGE AMERICAN +NLS_TERRITORY AMERICA +NLS_CURRENCY $ +NLS_ISO_CURRENCY AMERICA +NLS_NUMERIC_CHARACTERS ., +NLS_CHARACTERSET AL32UTF8 +NLS_CALENDAR GREGORIAN +NLS_DATE_FORMAT DD-MON-RR +NLS_DATE_LANGUAGE AMERICAN +NLS_SORT BINARY +NLS_TIME_FORMAT HH.MI.SSXFF AM +NLS_TIMESTAMP_FORMAT DD-MON-RR HH.MI.SSXFF AM +NLS_TIME_TZ_FORMAT HH.MI.SSXFF AM TZR +NLS_TIMESTAMP_TZ_FORMAT DD-MON-RR HH.MI.SSXFF AM TZR +NLS_DUAL_CURRENCY $ +NLS_COMP BINARY +NLS_LENGTH_SEMANTICS BYTE +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.</para> + </warning> + + <para>Create database with Unicode encoding and use Oracle dialect for the + Workspace Container:</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> + </section> + + <section> + <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.</para> + + <para>Example of UTF-8 database creation:<programlisting>DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US</programlisting></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; + .....</programlisting></para> + + <note> + <para>For DB2 v.8.x support change the property "dialect" to + db2v8.</para> + </note> + </section> + + <section> + <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.</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></para> + </section> + + <section> + <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> + <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.</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.</para> + </listitem> + </itemizedlist></para> + + <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></para> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/query-handler-config.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/query-handler-config.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/query-handler-config.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,194 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="ch_query_handler_config"> + <?dbhtml filename="ch-query-handler-config.html"?> + + <title>QueryHandler configuration</title> + + <section> + <title>How does it work?</title> + + <para>Lets talk about indexing content in cluster.</para> + + <para>For couple of reasons, we can't replicate index. That's means, some + data added and indexed on one cluster node, will be replicated to another + cluster node, but will not be indexed on that node.</para> + + <para><citetitle>So, how do the indexing works in cluster + environment?</citetitle></para> + + <para>As, we can not index same data on all nodes of cluster, we must + index it on one node. Node, that can index data and do changes on lucene + index, is called "coordinator". Coordinator-node is choosen automaticaly, + so we do not need special configuration for coordinator.</para> + + <para>But, how can another nodes save their changes to lucene + index?</para> + + <para>First of all, data is already saved and replicated to another + cluster-nodes, so we need only deliver message like "we need to index this + data" to coordinator. Thats why Jboss-cache is used.</para> + + <para>All nodes of cluster writes messages into JBoss-cache but only + coordinator takes those messages and makes changes Lucene index.</para> + + <para><citetitle>How do the search works in cluster + environment?</citetitle></para> + + <para>Search engine do not works with indexer, coordinator, etc. Search + needs only lucene index. But only one cluster node can change lucene index + - asking you. Yes - lucene index is shared. So, all cluster nodes must be + configured to use lucene index from shared directory.</para> + + <para>A little bit about indexing process (no matter, cluster or not) + Indexer do not writes changes to FS lucene index immediately. At first, + Indexer writes changes to Volatile index. If Volatile index size become + 1Mb or more it is flushed to FS. Also there is timer, that flushes + volatile index by timeout. Volatile index timeout configured by + "max-volatile-time" paremeter.</para> + + <para>See more about <link linkend="ch_search_configuration">Search + Configuration</link>.</para> + + <para>Common scheme of Shared Index<mediaobject> + <imageobject> + <imagedata fileref="images/diagram-shared-index.png" /> + </imageobject> + </mediaobject></para> + </section> + + <section> + <title>Configuration</title> + + <section> + <title>Common requirements</title> + + <para>Now, lets see what we need to run Search engine in cluster + environment.<itemizedlist> + <listitem> + <para>shared directory for storing Lucene index (i.e. NFS);</para> + </listitem> + + <listitem> + <para>changes filter configured as + org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter;</para> + + <note> + <para>This filter ignore changes on non-coordinator nodes, and + index changes on coordinator node.</para> + </note> + </listitem> + + <listitem> + <para>configure JBoss-cache, course;</para> + </listitem> + </itemizedlist></para> + </section> + + <section> + <title>Query-handler configuration</title> + + <para>Configuration example:<programlisting>&lt;workspace name="ws"&gt; + &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + &lt;properties&gt; + &lt;property name="index-dir" value="shareddir/index/db1/ws" /&gt; + &lt;property name="changesfilter-class" + value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /&gt; + &lt;property name="jbosscache-configuration" value="jbosscache-indexer.xml" /&gt; + &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; + &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; + &lt;property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /&gt; + &lt;property name="max-volatile-time" value="60" /&gt; + &lt;/properties&gt; + &lt;/query-handler&gt; +&lt;/workspace&gt;</programlisting> <table> + <title>Config properties description</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Property name</entry> + + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry>index-dir</entry> + + <entry>path to index</entry> + </row> + + <row> + <entry>jbosscache-configuration</entry> + + <entry>template of JBoss-cache configuration for all + query-handlers in repository</entry> + </row> + + <row> + <entry>jgroups-configuration</entry> + + <entry>jgroups-configuration is template configuration for all + components (search, cache, locks) [Add link to document + describing template configurations]</entry> + </row> + + <row> + <entry>jgroups-multiplexer-stack</entry> + + <entry>[TODO about jgroups-multiplexer-stack - add link to + JBoss doc]</entry> + </row> + + <row> + <entry>jbosscache-cluster-name</entry> + + <entry>cluster name (must be unique)</entry> + </row> + + <row> + <entry>max-volatile-time</entry> + + <entry>max time to live for Volatile Index</entry> + </row> + </tbody> + </tgroup> + </table></para> + </section> + + <section> + <title>JBoss-Cache template configuration</title> + + <para>JBoss-Cache template configuration for query handler.</para> + + <para>jbosscache-indexer.xml<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;!-- Configure the TransactionManager --&gt; + &lt;transaction transactionManagerLookupClass="org.jboss.cache.transaction.JBossStandaloneJTAManagerLookup" /&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></para> + + <para>See more about template configurations <link + linkend="ch_jbosscache_config_templates">here</link>.</para> + </section> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/search-configuration.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/search-configuration.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/search-configuration.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,774 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="ch_search_configuration"> + <?dbhtml filename="ch-search-configuration.html"?> + + <title>Search Configuration</title> + + <section> + <title>XML Configuration</title> + + <para>JCR index configuration. You can find this file here: + <filename>.../portal/WEB-INF/conf/jcr/repository-configuration.xml</filename></para> + + <programlisting>&lt;repository-service default-repository="db1"&gt; + &lt;repositories&gt; + &lt;repository name="db1" system-workspace="ws" default-workspace="ws"&gt; + .... + &lt;workspaces&gt; + &lt;workspace name="ws"&gt; + .... + &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + &lt;properties&gt; + &lt;property name="index-dir" value="${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; + ... + &lt;/workspace&gt; + &lt;/workspaces&gt; + &lt;/repository&gt; + &lt;/repositories&gt; +&lt;/repository-service&gt;</programlisting> + </section> + + <section> + <title>Configuration parameters</title> + + <table> + <title></title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Parameter</entry> + + <entry>Default</entry> + + <entry>Description</entry> + + <entry>Since</entry> + </row> + </thead> + + <tbody> + <row> + <entry>index-dir</entry> + + <entry>none</entry> + + <entry>The location of the index directory. This parameter is + mandatory. Up to 1.9 this parameter called "indexDir"</entry> + + <entry>1.0</entry> + </row> + + <row> + <entry>use-compoundfile</entry> + + <entry>true</entry> + + <entry>Advises lucene to use compound files for the index + files.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>min-merge-docs</entry> + + <entry>100</entry> + + <entry>Minimum number of nodes in an index until segments are + merged.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>volatile-idle-time</entry> + + <entry>3</entry> + + <entry>Idle time in seconds until the volatile index part is moved + to a persistent index even though minMergeDocs is not + reached.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>max-merge-docs</entry> + + <entry>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.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>merge-factor</entry> + + <entry>10</entry> + + <entry>Determines how often segment indices are merged.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>max-field-length</entry> + + <entry>10000</entry> + + <entry>The number of words that are fulltext indexed at most per + property.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>cache-size</entry> + + <entry>1000</entry> + + <entry>Size of the document number cache. This cache maps uuids to + lucene document numbers</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>force-consistencycheck</entry> + + <entry>false</entry> + + <entry>Runs a consistency check on every startup. If false, a + consistency check is only performed when the search index detects + a prior forced shutdown.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>auto-repair</entry> + + <entry>true</entry> + + <entry>Errors detected by a consistency check are automatically + repaired. If false, errors are only written to the log.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>query-class</entry> + + <entry>QueryImpl</entry> + + <entry>Class name that implements the javax.jcr.query.Query + interface.This class must also extend from the class: + org.exoplatform.services.jcr.impl.core.query.AbstractQueryImpl.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>document-order</entry> + + <entry>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'.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>result-fetch-size</entry> + + <entry>Integer.MAX_VALUE</entry> + + <entry>The number of results when a query is executed. Default + value: Integer.MAX_VALUE (-&gt; all).</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>excerptprovider-class</entry> + + <entry>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.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>support-highlighting</entry> + + <entry>false</entry> + + <entry>If set to true additional information is stored in the + index to support highlighting using the rep:excerpt() + function.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>synonymprovider-class</entry> + + <entry>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).</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>synonymprovider-config-path</entry> + + <entry>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).</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>indexing-configuration-path</entry> + + <entry>none</entry> + + <entry>The path to the indexing configuration file.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>indexing-configuration-class</entry> + + <entry>IndexingConfigurationImpl</entry> + + <entry>The name of the class that implements + org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfiguration.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>force-consistencycheck</entry> + + <entry>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.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>spellchecker-class</entry> + + <entry>none</entry> + + <entry>The name of a class that implements + org.exoplatform.services.jcr.impl.core.query.lucene.SpellChecker.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>errorlog-size</entry> + + <entry>50(Kb)</entry> + + <entry>The default size of error log file in Kb.</entry> + + <entry>1.9</entry> + </row> + + <row> + <entry>upgrade-index</entry> + + <entry>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.)</entry> + + <entry>1.12</entry> + </row> + + <row> + <entry>analyzer</entry> + + <entry>org.apache.lucene.analysis.standard.StandardAnalyzer</entry> + + <entry>Class name of a lucene analyzer to use for fulltext + indexing of text.</entry> + + <entry>1.12</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Global Search Index</title> + + <section> + <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> + + <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> + <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) { + 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> + <para>The first one (StandardFilter) removes 's (as 's in + "Peter's") from the end of words and removes dots from + acronyms.</para> + </listitem> + + <listitem> + <para>The second one (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></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.</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.</para> + + <section> + <title>Create the filter</title> + + <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.</para> + </section> + + <section> + <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.</para> + </section> + + <section> + <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() { + return MyAnalyzer; + }</programlisting>to return your analyzer. You can see the attached + SearchIndex.</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> + + <section> + <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<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;</programlisting></para> + </section> + + <section> + <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; + ... + &lt;property name="analyzer" value="org.exoplatform.services.jcr.impl.core.MyAnalyzer"/&gt; + ... + &lt;/properties&gt; +&lt;/query-handler&gt;</programlisting></para> + + <para>When you start exo, your SearchIndex will start to index + contents with the specified filters.</para> + </section> + </section> + </section> + + <section> + <title>Index Adjustments</title> + + <section> + <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> + + <programlisting>&lt;param name="indexing-configuration-path" value="/indexing_configuration.xml"/&gt;</programlisting> + </section> + + <section> + <title>Index rules</title> + + <section> + <title>Node Scope Limit</title> + + <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.</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> + + <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> + <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> + + <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"&gt; + &lt;property&gt;Text&lt;/property&gt; + &lt;/index-rule&gt; +&lt;/configuration&gt;</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:<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 boost="3.0"&gt;Title&lt;/property&gt; + &lt;property boost="1.5"&gt;Text&lt;/property&gt; + &lt;/index-rule&gt; +&lt;/configuration&gt;</programlisting></para> + </section> + + <section> + <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" + 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" + 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" + 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" + 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> + <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></para> + </section> + </section> + + <section> + <title>Index Aggregates</title> + + <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.</para> + + <para>JCR allows you to define index aggregates based on relative path + patterns and primary node types.</para> + + <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></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></para> + + <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></para> + + <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></para> + </section> + + <section> + <title>Property-Level Analyzers</title> + + <section> + <title>Example</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></para> + + <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.</para> + + <para>The WhitespaceAnalyzer tokenizes a property, the KeywordAnalyzer + takes the property as a whole.</para> + </section> + + <section> + <title>Characteristics of Node Scope Searches</title> + + <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.</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).</para> + + <para>If your query is for example:<programlisting>xpath = "//*[jcr:contains(mytext,'analyzer')]"</programlisting></para> + + <para>This xpath does not return a hit in the node with the property + above and default analyzers.</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.</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<programlisting>xpath = "//*[jcr:contains(mytext,'analyzer')]"</programlisting>you + would get a hit because of the word stemming (analyzers - + analyzer).</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> + + <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!</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!</para> + </note> + </section> + </section> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/transaction-manager-lookup.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/transaction-manager-lookup.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/transaction-manager-lookup.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter> + <?dbhtml filename="ch-transaction-manager.html"?> + + <title>TransactionManagerLookup</title> + + <section> + <title>Intro</title> + + <para></para> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/transaction-service.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/transaction-service.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/transaction-service.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter> + <?dbhtml filename="ch-tranasction-service.html"?> + + <title>TransactionService</title> + + <section> + <title>Intro</title> + + <para></para> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<part> + <?dbhtml filename="part-jcr.html"?> + + <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" /> + + <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" /> + + <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/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" /> + +</part> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jdbc-data-container-config.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jdbc-data-container-config.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jdbc-data-container-config.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,533 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_jdbc_data_container"> - <?dbhtml filename="jdbc-data-container-config.html"?> - - <title>JDBC Data Container Config</title> - - <section> - <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></para> - - <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.</para> - - <para>Currently the data container is tested with the following - RDBMS:<itemizedlist> - <listitem> - <para>MySQL (5.x including UTF8 support)</para> - </listitem> - - <listitem> - <para>PostgreSQL (8.x)</para> - </listitem> - - <listitem> - <para>Oracle Database (9i, 10g)</para> - </listitem> - - <listitem> - <para>Microsoft SQL Server (2005)</para> - </listitem> - - <listitem> - <para>Sybase ASE (15.0)</para> - </listitem> - - <listitem> - <para>Apache Derby/Java DB (10.1.x, 10.2.x)</para> - </listitem> - - <listitem> - <para>IBM DB2 (8.x, 9.x)</para> - </listitem> - - <listitem> - <para>HSQLDB (1.8.0.7)</para> - </listitem> - </itemizedlist></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.</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<... - - <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.</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).</para> - - <para>Read more about <link linkend="ch_configuration">Repository - configuration</link>.</para> - </section> - - <section> - <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.</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.</para> - - <para>Example (standalone mode, two data containers - <parameter>jdbcjcr</parameter> - local HSQLDB, - <parameter>jdbcjcr1</parameter> - remote MySQL):<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; - &lt;component-plugins&gt; - &lt;component-plugin&gt; - &lt;name&gt;bind.datasource&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;bind-name&lt;/name&gt; - &lt;value&gt;jdbcjcr&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;class-name&lt;/name&gt; - &lt;value&gt;javax.sql.DataSource&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;factory&lt;/name&gt; - &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt; - &lt;/value-param&gt; - &lt;properties-param&gt; - &lt;name&gt;ref-addresses&lt;/name&gt; - &lt;description&gt;ref-addresses&lt;/description&gt; - &lt;property name="driverClassName" value="org.hsqldb.jdbcDriver"/&gt; - &lt;property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/&gt; - &lt;property name="username" value="sa"/&gt; - &lt;property name="password" value=""/&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;component-plugin&gt; - &lt;name&gt;bind.datasource&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;bind-name&lt;/name&gt; - &lt;value&gt;jdbcjcr1&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;class-name&lt;/name&gt; - &lt;value&gt;javax.sql.DataSource&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;factory&lt;/name&gt; - &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt; - &lt;/value-param&gt; - &lt;properties-param&gt; - &lt;name&gt;ref-addresses&lt;/name&gt; - &lt;description&gt;ref-addresses&lt;/description&gt; - &lt;property name="driverClassName" value="com.mysql.jdbc.Driver"/&gt; - &lt;property name="url" value="jdbc:mysql://exoua.dnsalias.net/jcr"/&gt; - &lt;property name="username" value="exoadmin"/&gt; - &lt;property name="password" value="exo12321"/&gt; - &lt;property name="maxActive" value="50"/&gt; - &lt;property name="maxIdle" value="5"/&gt; - &lt;property name="initialSize" value="5"/&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;component-plugins&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;default-context-factory&lt;/name&gt; - &lt;value&gt;org.exoplatform.services.naming.SimpleContextFactory&lt;/value&gt; - &lt;/value-param&gt; - &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):<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; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr"/&gt; - &lt;property name="dialect" value="hsqldb"/&gt; - &lt;property name="multi-db" value="true"/&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;/container&gt; - &lt;cache enabled="true"&gt; - &lt;properties&gt; - &lt;property name="max-size" value="10K"/&gt;&lt;!-- 10Kbytes --&gt; - &lt;property name="live-time" value="30m"/&gt;&lt;!-- 30 min --&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="target/temp/index"/&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; - &lt;lock-manager&gt; - &lt;time-out&gt;15m&lt;/time-out&gt;&lt;!-- 15 min --&gt; - &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; - &lt;properties&gt; - &lt;property name="path" value="target/temp/lock/ws"/&gt; - &lt;/properties&gt; - &lt;/persister&gt; - &lt;/lock-manager&gt; - &lt;/workspace&gt; - &lt;workspace name="ws1" auto-init-root-nodetype="nt:unstructured"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr1"/&gt; - &lt;property name="dialect" value="mysql"/&gt; - &lt;property name="multi-db" value="true"/&gt; - &lt;property name="max-buffer-size" value="200K"/&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws1"/&gt; - &lt;/properties&gt; - &lt;/container&gt; - &lt;cache enabled="true"&gt; - &lt;properties&gt; - &lt;property name="max-size" value="10K"/&gt; - &lt;property name="live-time" value="5m"/&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="target/temp/index"/&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; - &lt;lock-manager&gt; - &lt;time-out&gt;15m&lt;/time-out&gt;&lt;!-- 15 min --&gt; - &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; - &lt;properties&gt; - &lt;property name="path" value="target/temp/lock/ws1"/&gt; - &lt;/properties&gt; - &lt;/persister&gt; - &lt;/lock-manager&gt; - &lt;/workspace&gt; -&lt;/workspaces&gt;</programlisting><itemizedlist> - <listitem> - <para><parameter>source-name</parameter> - a javax.sql.DataSource - name configured in InitialContextInitializer component (was - <parameter>sourceName</parameter> prior JCR 1.9);</para> - </listitem> - - <listitem> - <para><parameter>dialect</parameter> - a database dialect, one of - "hsqldb", "mysql", "mysql-utf8", "pgsql", "oracle", "oracle-oci", - "mssql", "sybase", "derby", "db2", "db2v8".</para> - </listitem> - - <listitem> - <para><parameter>multi-db</parameter> - enable multi-database - container with this parameter (set value "true");</para> - </listitem> - - <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.</para> - </listitem> - - <listitem> - <para><parameter>swap-directory</parameter> - a path in the file - system used to swap the pending changes.</para> - </listitem> - </itemizedlist></para> - - <para>In this way we have configured two workspace which will be persisted - in two different databases (ws in HSQLDB, ws1 in MySQL).</para> - - <note> - <para> Starting from v.1.9 <link linkend="ch_configuration">repository - configuration</link> parameters supports human-readable formats of - values (e.g. 200K - 200 Kbytes, 30m - 30 minutes etc)</para> - </note> - </section> - - <section> - <title>Single-database configuration</title> - - <para>It's more simple to configure a single-database data container. We - have to configure one naming resource.</para> - - <para>Example (embedded mode for <parameter>jdbcjcr</parameter> data - container):<programlisting>&lt;external-component-plugins&gt; - &lt;target-component&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;name&gt;bind.datasource&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;bind-name&lt;/name&gt; - &lt;value&gt;jdbcjcr&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;class-name&lt;/name&gt; - &lt;value&gt;javax.sql.DataSource&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;factory&lt;/name&gt; - &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt; - &lt;/value-param&gt; - &lt;properties-param&gt; - &lt;name&gt;ref-addresses&lt;/name&gt; - &lt;description&gt;ref-addresses&lt;/description&gt; - &lt;property name="driverClassName" value="org.postgresql.Driver"/&gt; - &lt;property name="url" value="jdbc:postgresql://exoua.dnsalias.net/portal"/&gt; - &lt;property name="username" value="exoadmin"/&gt; - &lt;property name="password" value="exo12321"/&gt; - &lt;property name="maxActive" value="50"/&gt; - &lt;property name="maxIdle" value="5"/&gt; - &lt;property name="initialSize" value="5"/&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;/external-component-plugins&gt;</programlisting></para> - - <para>And configure repository workspaces in repositories configuration - with this one database. Parameter "multi-db" must be switched off (set - value "false").</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; - &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; - &lt;/container&gt; - &lt;cache enabled="true"&gt; - &lt;properties&gt; - &lt;property name="max-size" value="10K"/&gt; - &lt;property name="live-time" value="30m"/&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="../temp/index"/&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; - &lt;lock-manager&gt; - &lt;time-out&gt;15m&lt;/time-out&gt; - &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; - &lt;properties&gt; - &lt;property name="path" value="target/temp/lock/ws"/&gt; - &lt;/properties&gt; - &lt;/persister&gt; - &lt;/lock-manager&gt; - &lt;/workspace&gt; - &lt;workspace name="ws1" auto-init-root-nodetype="nt:unstructured"&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/ws1"/&gt; - &lt;/properties&gt; - &lt;/container&gt; - &lt;cache enabled="true"&gt; - &lt;properties&gt; - &lt;property name="max-size" value="10K"/&gt; - &lt;property name="live-time" value="5m"/&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;lock-manager&gt; - &lt;time-out&gt;15m&lt;/time-out&gt; - &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; - &lt;properties&gt; - &lt;property name="path" value="target/temp/lock/ws1"/&gt; - &lt;/properties&gt; - &lt;/persister&gt; - &lt;/lock-manager&gt; - &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> - <title>Configuration without DataSource</title> - - <para>Repository configuration without using of the - <classname>javax.sql.DataSource</classname> bounded 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> - <para>You have to remove the configuration in - <classname>InitialContextInitializer</classname> for your database - and configure a new one directly in the workspace - container.</para> - </listitem> - - <listitem> - <para>Remove parameter "source-name" and add next lines instead. - Describe your values for a JDBC driver, database url and - username.</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> - - <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; - &lt;property name="dialect" value="hsqldb"/&gt; - &lt;property name="driverClassName" value="org.hsqldb.jdbcDriver"/&gt; - &lt;property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/&gt; - &lt;property name="username" value="su"/&gt; - &lt;property name="password" value=""/&gt; - ......</programlisting> - </section> - - <section> - <title>Dynamic Workspace Creation</title> - - <para>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></para> - </section> - </section> - - <section> - <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.</para> - - <para>Microsoft Windows has <parameter>MaxUserPort</parameter>, - <parameter>TcpTimedWaitDelay</parameter> registry keys in the node - <parameter>HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesTcpipParameters</parameter>, - by default these keys are unset, set each one with values like - these:<itemizedlist> - <listitem> - <para>"TcpTimedWaitDelay"=dword:0000001e, sets TIME_WAIT parameter - to 30 seconds, default is 240.</para> - </listitem> - - <listitem> - <para>"MaxUserPort"=dword:00001b58, sets the maximum of open ports - to 7000 or higher, default is 5000.</para> - </listitem> - </itemizedlist></para> - - <para>A sample registry file is below:<programlisting>Windows Registry Editor Version 5.00 - -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters] -"MaxUserPort"=dword:00001b58 -"TcpTimedWaitDelay"=dword:0000001e</programlisting></para> - </section> -</chapter> Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/kernel.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/kernel.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/kernel.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,25 +1,27 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter> - <title>eXo Kernel</title> - - <section> - <title>eXo Kernel introduction</title> - - <para>eXo Kernel is the basis of all eXo platform products and modules. - Any component available in eXo Platform is managed by the Exo Container, - our micro container responsible for gluing the services through dependency - injection</para> - - <para>Therefore, each product is composed of a set of services and plugins - registered to the container and configured by XML configuration - files.</para> - - <para>The Kernel module also contains a set of very low level - services.</para> - - <para><ulink url="http://wiki.exoplatform.org/xwiki/bin/view/Kernel/">Find - more on eXo site</ulink></para> - </section> -</chapter> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter> + <?dbhtml filename="ch-kernel.html"?> + + <title>eXo Kernel</title> + + <section> + <title>eXo Kernel introduction</title> + + <para>eXo Kernel is the basis of all eXo platform products and modules. + Any component available in eXo Platform is managed by the Exo Container, + our micro container responsible for gluing the services through dependency + injection</para> + + <para>Therefore, each product is composed of a set of services and plugins + registered to the container and configured by XML configuration + files.</para> + + <para>The Kernel module also contains a set of very low level + services.</para> + + <para><ulink url="http://wiki.exoplatform.org/xwiki/bin/view/Kernel/">Find + more on eXo site</ulink></para> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,12 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<part> + <?dbhtml filename="part-kernel.html"?> + + <title>eXoKernel</title> + + <xi:include href="kernel/kernel.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</part> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/lock-manager-config.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/lock-manager-config.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/lock-manager-config.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,442 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_lock_manager_config"> - <?dbhtml filename="lock-manager-config.html"?> - - <title>LockManager configuration</title> - - <section> - <title>Introduction</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>Also LockManager is responsible for removing Locks that live too - long. This parameter may be configured with "time-out" property.</para> - - <para>JCR provide two base implementation of LockManager:</para> - - <itemizedlist> - <listitem> - <para><classname>org.exoplatform.services.jcr.impl.core.lock.LockManagerImpl</classname>;</para> - </listitem> - - <listitem> - <para><classname>org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl</classname>;</para> - </listitem> - </itemizedlist> - - <para>In this article we will talk mostly about - CacheableLockManagerImpl.</para> - - <para>You can enable LockManager by adding lock-manager-configuration to - workspace-configuration.</para> - - <para>For example:</para> - - <programlisting>&lt;workspace name="ws"&gt; - ... - &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;/properties&gt; - &lt;/lock-manager&gt; - ... -&lt;/workspace&gt;</programlisting> - </section> - - <section> - <title>LockManagerImpl</title> - - <para>LockManagerImpl is simple implementation of LockManager, and also - faster than CacheableLockManager. It stores Lock objects in HashMap and - may also persist Locks if LockPersister is configured. LockManagerImpl do - not support replication in any way.</para> - - <para>See more about LockManager Configuration <link - linkend="ch_configuration">here</link>.</para> - </section> - - <section> - <title>CacheableLockManagerImpl</title> - - <para>CacheableLockManagerImpl stores Lock object in JBoss-cache, so Locks - are replicable and affects on cluster, not only a single node. Also - JBoss-cache has JDBCCacheLoader, so locks will be stored to - database.</para> - - <para>Both implementation supports Expired Locks removing. There is - LockRemover - separate thread, that periodically ask LockManager for Locks - that lives to much and must be removed. So, timeout for LockRemover may be - set as follows, default value is 30m.</para> - - <programlisting>&lt;properties&gt; - &lt;property name="time-out" value="10m" /&gt; - ... -&lt;/properties&gt;</programlisting> - - <section> - <title>Configuration</title> - - <para>Replication requirements are same as for Cache</para> - - <para>Full JCR configuration example you can see <link - linkend="sect_conf_cluster_jcr">here</link>.</para> - - <para>Common tips:</para> - - <itemizedlist> - <listitem> - <para><parameter>clusterName</parameter> ("jbosscache-cluster-name") - must be unique;</para> - </listitem> - - <listitem> - <para><parameter>cache.jdbc.table.name</parameter> must be unique - per datasource;</para> - </listitem> - - <listitem> - <para><parameter>cache.jdbc.fqn.type</parameter> must and - cache.jdbc.node.type must be configured according to used - database;</para> - </listitem> - </itemizedlist> - - <para>There is few ways how to configure CacheableLockManagerImpl, and - all of them configures JBoss-cache and JDBCCacheLoader.</para> - - <para>See <ulink - url="http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader"... - </section> - - <section> - <title>Simple JbossCache Configuraion</title> - - <para>First one is - put JbossCache configuraion file path to - CacheableLockManagerImpl</para> - - <para><note> - <para>This configuration is not so good, as you can think. Because - repository may contain many workspaces, and each workspace must - contain LockManager configuration, and LockManager config may - contain JbossCache config file. So total configuration is growing - up. But it is usefull if we want a single LockManager with special - configuration.</para> - </note></para> - - <para>Config is:</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="conf/standalone/cluster/test-jbosscache-lock-config.xml" /&gt; - &lt;/properties&gt; -&lt;/lock-manager&gt;</programlisting> - - <para><filename>test-jbosscache-lock-config.xml</filename><programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.2"&gt; - - &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" lockAcquisitionTimeout="20000" /&gt; - - &lt;clustering mode="replication" clusterName="JBoss-Cache-Lock-Cluster_Name"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" nonBlocking="true" /&gt; - &lt;jgroupsConfig&gt; - - &lt;TCP bind_addr="127.0.0.1" start_port="9800" loopback="true" recv_buf_size="20000000" send_buf_size="640000" discard_incompatible_packets="true" - max_bundle_size="64000" max_bundle_timeout="30" use_incoming_packet_handler="true" enable_bundling="false" use_send_queues="false" sock_conn_timeout="300" - skip_suspected_members="true" use_concurrent_stack="true" thread_pool.enabled="true" thread_pool.min_threads="1" thread_pool.max_threads="25" - thread_pool.keep_alive_time="5000" thread_pool.queue_enabled="false" thread_pool.queue_max_size="100" thread_pool.rejection_policy="run" - oob_thread_pool.enabled="true" oob_thread_pool.min_threads="1" oob_thread_pool.max_threads="8" oob_thread_pool.keep_alive_time="5000" - oob_thread_pool.queue_enabled="false" oob_thread_pool.queue_max_size="100" oob_thread_pool.rejection_policy="run" /&gt; - &lt;MPING timeout="2000" num_initial_members="2" mcast_port="34540" bind_addr="127.0.0.1" mcast_addr="224.0.0.1" /&gt; - - - &lt;MERGE2 max_interval="30000" min_interval="10000" /&gt; - &lt;FD_SOCK /&gt; - &lt;FD max_tries="5" shun="true" timeout="10000" /&gt; - &lt;VERIFY_SUSPECT timeout="1500" /&gt; - &lt;pbcast.NAKACK discard_delivered_msgs="true" gc_lag="0" retransmit_timeout="300,600,1200,2400,4800" use_mcast_xmit="false" /&gt; - &lt;UNICAST timeout="300,600,1200,2400,3600" /&gt; - &lt;pbcast.STABLE desired_avg_gossip="50000" max_bytes="400000" stability_delay="1000" /&gt; - &lt;pbcast.GMS join_timeout="5000" print_local_addr="true" shun="false" view_ack_collection_timeout="5000" view_bundling="true" /&gt; - &lt;FRAG2 frag_size="60000" /&gt; - &lt;pbcast.STREAMING_STATE_TRANSFER /&gt; - &lt;pbcast.FLUSH timeout="0" /&gt; - - &lt;/jgroupsConfig - - &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; - cache.jdbc.table.name=jcrlocks_ws - cache.jdbc.table.create=true - cache.jdbc.table.drop=false - cache.jdbc.table.primarykey=jcrlocks_ws_pk - cache.jdbc.fqn.column=fqn - cache.jdbc.fqn.type=VARCHAR(512) - cache.jdbc.node.column=node - cache.jdbc.node.type=&lt;BLOB&gt; - cache.jdbc.parent.column=parent - cache.jdbc.datasource=jdbcjcr - &lt;/properties&gt; - &lt;/loader&gt; - - &lt;/loaders&gt; - -&lt;/jbosscache&gt;</programlisting></para> - - <para>Configuration requirements:</para> - - <itemizedlist> - <listitem> - <para>&lt;clustering mode="replication" - clusterName="JBoss-Cache-Lock-Cluster_Name"&gt; - cluster name must - be unique;</para> - </listitem> - - <listitem> - <para><parameter>cache.jdbc.table.name</parameter> must be unique - per datasource;</para> - </listitem> - - <listitem> - <para><parameter>cache.jdbc.node.type</parameter> and - <parameter>cache.jdbc.fqn.type</parameter> must be configured - according to using database. See <link endterm="datatypes.title" - linkend="datatypes"></link> .</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Template JBossCache Configuration</title> - - <para>Second one is - use template JBoss-cache configuration for all - LockManagers</para> - - <para><citetitle>Lock template configuration</citetitle></para> - - <para><filename>test-jbosscache-lock.xml</filename></para> - - <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; - - &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" - lockAcquisitionTimeout="20000" /&gt; - - &lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; - &lt;jgroupsConfig multiplexerStack="jcr.stack" /&gt; - &lt;sync /&gt; - &lt;/clustering&gt; - - &lt;loaders passivation="false" shared="true"&gt; - &lt;!-- All the data of the JCR locks needs to be loaded at startup --&gt; - &lt;preload&gt; - &lt;node fqn="/" /&gt; - &lt;/preload&gt; - &lt;!-- - For another cache-loader class you should use another template with - cache-loader specific parameters - -&gt; - &lt;loader class="org.jboss.cache.loader.JDBCCacheLoader" async=q"false" fetchPersistentState="false" - ignoreModifications="false" purgeOnStartup="false"&gt; - &lt;properties&gt; - cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name} - cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create} - cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop} - cache.jdbc.table.primarykey=${jbosscache-cl-cache.jdbc.table.primarykey} - cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column} - cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type} - cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column} - cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type} - cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column} - cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource} - &lt;/properties&gt; - &lt;/loader&gt; - &lt;/loaders&gt; -&lt;/jbosscache&gt;</programlisting> - - <para>As you see, all configurable paramaters filled by templates and - will be replaced by LockManagers conf parameters:</para> - - <programlisting>&lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; - &lt;properties&gt; - &lt;property name="time-out" value="15m" /&gt; - &lt;property name="jbosscache-configuration" value="test-jbosscache-lock.xml" /&gt; - &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="JCR-cluster-locks-ws" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_ws" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.create" value="true" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.drop" value="false" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_ws_pk" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.fqn.type" value="AUTO"/&gt; - &lt;property name="jbosscache-cl-cache.jdbc.node.column" value="node" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.node.type" value="AUTO"/&gt; - &lt;property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" /&gt; - &lt;/properties&gt; -&lt;/lock-manager&gt;</programlisting> - - <para>Configuration requirements:<itemizedlist> - <listitem> - <para><parameter>jbosscache-cl-cache.jdbc.fqn.column</parameter> - and <parameter>jbosscache-cl-cache.jdbc.node.type</parameter> is - nothing else as cache.jdbc.fqn.type and cache.jdbc.node.type in - JBoss-Cache configuration. You can set those data types according - to database type (See <link endterm="datatypes.title" - linkend="datatypes"></link>) or set it as AUTO (or do not set at - all) and data type will by detected automaticaly.</para> - </listitem> - - <listitem> - <para>as you see, jgroups-configuration moved to separate config - file - udp-mux.xml; In our case udp-mux.xml is common JGroup - config for all components (QueryHandler, cache, LockManager). But - we, still, can create own config.</para> - </listitem> - </itemizedlist></para> - - <para><filename>our-udp-mux.xml</filename><programlisting>&lt;protocol_stacks&gt; - &lt;stack name="jcr.stack"&gt; - &lt;config&gt; - &lt;UDP mcast_addr="228.10.10.10" mcast_port="45588" tos="8" ucast_recv_buf_size="20000000" - ucast_send_buf_size="640000" mcast_recv_buf_size="25000000" mcast_send_buf_size="640000" loopback="false" - discard_incompatible_packets="true" max_bundle_size="64000" max_bundle_timeout="30" - use_incoming_packet_handler="true" ip_ttl="2" enable_bundling="true" enable_diagnostics="true" - thread_naming_pattern="cl" use_concurrent_stack="true" thread_pool.enabled="true" thread_pool.min_threads="2" - thread_pool.max_threads="8" thread_pool.keep_alive_time="5000" thread_pool.queue_enabled="true" - thread_pool.queue_max_size="1000" thread_pool.rejection_policy="discard" oob_thread_pool.enabled="true" - oob_thread_pool.min_threads="1" oob_thread_pool.max_threads="8" oob_thread_pool.keep_alive_time="5000" - oob_thread_pool.queue_enabled="false" oob_thread_pool.queue_max_size="100" oob_thread_pool.rejection_policy="Run" /&gt; - - &lt;PING timeout="2000" num_initial_members="3" /&gt; - &lt;MERGE2 max_interval="30000" min_interval="10000" /&gt; - &lt;FD_SOCK /&gt; - &lt;FD timeout="10000" max_tries="5" shun="true" /&gt; - &lt;VERIFY_SUSPECT timeout="1500" /&gt; - &lt;BARRIER /&gt; - &lt;pbcast.NAKACK use_stats_for_retransmission="false" exponential_backoff="150" use_mcast_xmit="true" - gc_lag="0" retransmit_timeout="50,300,600,1200" discard_delivered_msgs="true" /&gt; - &lt;UNICAST timeout="300,600,1200" /&gt; - &lt;pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000" max_bytes="1000000" /&gt; - &lt;VIEW_SYNC avg_send_interval="60000" /&gt; - &lt;pbcast.GMS print_local_addr="true" join_timeout="3000" shun="false" view_bundling="true" /&gt; - &lt;FC max_credits="500000" min_threshold="0.20" /&gt; - &lt;FRAG2 frag_size="60000" /&gt; - &lt;!--pbcast.STREAMING_STATE_TRANSFER /--&gt; - &lt;pbcast.STATE_TRANSFER /&gt; - &lt;!-- pbcast.FLUSH /--&gt; - &lt;/config&gt; - &lt;/stack&gt; -&lt;/protocol_stacks&gt; </programlisting></para> - </section> - - <section id="datatypes"> - <title id="datatypes.title">Data Types in Different Databases</title> - - <table> - <title>Fqn type and node type in different databases</title> - - <tgroup cols="3"> - <thead> - <row> - <entry>DataBase name</entry> - - <entry>Node data type</entry> - - <entry>FQN data type</entry> - </row> - </thead> - - <tbody> - <row> - <entry>default</entry> - - <entry>BLOB</entry> - - <entry>VARCHAR(512)</entry> - </row> - - <row> - <entry>HSSQL</entry> - - <entry>OBJECT</entry> - - <entry>VARCHAR(512)</entry> - </row> - - <row> - <entry>MySQL</entry> - - <entry>LONGBLOB</entry> - - <entry>VARCHAR(512)</entry> - </row> - - <row> - <entry>ORACLE</entry> - - <entry>BLOB</entry> - - <entry>VARCHAR2(512)</entry> - </row> - - <row> - <entry>PostgreSQL</entry> - - <entry>bytea</entry> - - <entry>VARCHAR(512)</entry> - </row> - - <row> - <entry>MSSQL</entry> - - <entry>VARBINARY(MAX)</entry> - - <entry>VARCHAR(512)</entry> - </row> - - <row> - <entry>DB2</entry> - - <entry>BLOB</entry> - - <entry>VARCHAR(512)</entry> - </row> - - <row> - <entry>Sybase</entry> - - <entry>IMAGE</entry> - - <entry>VARCHAR(512)</entry> - </row> - - <row> - <entry>Ingres</entry> - - <entry>long byte</entry> - - <entry>VARCHAR(512)</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - </section> -</chapter> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/multilanguage-support.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/multilanguage-support.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/multilanguage-support.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,170 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_multilanguage_support"> - <?dbhtml filename="multilanguage-support.html"?> - - <title>Multilanguage support in eXo JCR RDB backend</title> - - <section> - <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.</para> - - <para>The configuration file you have to modify: - .../webapps/portal/WEB-INF/conf/jcr/repository-configuration.xml</para> - - <note> - <para>Datasource <parameter>jdbcjcr</parameter> used in examples can be - configured via <classname>InitialContextInitializer</classname> - component.</para> - </note> - </section> - - <section> - <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>.</para> - - <para>We have tested <constant>NLS_CHARACTERSET</constant> = - <constant>AL32UTF8</constant> and it's works well for many European and - Asian languages.</para> - - <para>Example of database configuration (used for JCR - testing):<programlisting>NLS_LANGUAGE AMERICAN -NLS_TERRITORY AMERICA -NLS_CURRENCY $ -NLS_ISO_CURRENCY AMERICA -NLS_NUMERIC_CHARACTERS ., -NLS_CHARACTERSET AL32UTF8 -NLS_CALENDAR GREGORIAN -NLS_DATE_FORMAT DD-MON-RR -NLS_DATE_LANGUAGE AMERICAN -NLS_SORT BINARY -NLS_TIME_FORMAT HH.MI.SSXFF AM -NLS_TIMESTAMP_FORMAT DD-MON-RR HH.MI.SSXFF AM -NLS_TIME_TZ_FORMAT HH.MI.SSXFF AM TZR -NLS_TIMESTAMP_TZ_FORMAT DD-MON-RR HH.MI.SSXFF AM TZR -NLS_DUAL_CURRENCY $ -NLS_COMP BINARY -NLS_LENGTH_SEMANTICS BYTE -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.</para> - </warning> - - <para>Create database with Unicode encoding and use Oracle dialect for the - Workspace Container:</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> - </section> - - <section> - <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.</para> - - <para>Example of UTF-8 database creation:<programlisting>DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US</programlisting></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; - .....</programlisting></para> - - <note> - <para>For DB2 v.8.x support change the property "dialect" to - db2v8.</para> - </note> - </section> - - <section> - <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.</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></para> - </section> - - <section> - <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> - <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.</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.</para> - </listitem> - </itemizedlist></para> - - <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></para> - </section> -</chapter> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/query-handler-config.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/query-handler-config.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/query-handler-config.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,194 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_query_handler_config"> - <?dbhtml filename="query-handler-config.html"?> - - <title>QueryHandler configuration</title> - - <section> - <title>How does it work?</title> - - <para>Lets talk about indexing content in cluster.</para> - - <para>For couple of reasons, we can't replicate index. That's means, some - data added and indexed on one cluster node, will be replicated to another - cluster node, but will not be indexed on that node.</para> - - <para><citetitle>So, how do the indexing works in cluster - environment?</citetitle></para> - - <para>As, we can not index same data on all nodes of cluster, we must - index it on one node. Node, that can index data and do changes on lucene - index, is called "coordinator". Coordinator-node is choosen automaticaly, - so we do not need special configuration for coordinator.</para> - - <para>But, how can another nodes save their changes to lucene - index?</para> - - <para>First of all, data is already saved and replicated to another - cluster-nodes, so we need only deliver message like "we need to index this - data" to coordinator. Thats why Jboss-cache is used.</para> - - <para>All nodes of cluster writes messages into JBoss-cache but only - coordinator takes those messages and makes changes Lucene index.</para> - - <para><citetitle>How do the search works in cluster - environment?</citetitle></para> - - <para>Search engine do not works with indexer, coordinator, etc. Search - needs only lucene index. But only one cluster node can change lucene index - - asking you. Yes - lucene index is shared. So, all cluster nodes must be - configured to use lucene index from shared directory.</para> - - <para>A little bit about indexing process (no matter, cluster or not) - Indexer do not writes changes to FS lucene index immediately. At first, - Indexer writes changes to Volatile index. If Volatile index size become - 1Mb or more it is flushed to FS. Also there is timer, that flushes - volatile index by timeout. Volatile index timeout configured by - "max-volatile-time" paremeter.</para> - - <para>See more about <link linkend="ch_search_configuration">Search - Configuration</link>.</para> - - <para>Common scheme of Shared Index<mediaobject> - <imageobject> - <imagedata fileref="images/diagram-shared-index.png" /> - </imageobject> - </mediaobject></para> - </section> - - <section> - <title>Configuration</title> - - <section> - <title>Common requirements</title> - - <para>Now, lets see what we need to run Search engine in cluster - environment.<itemizedlist> - <listitem> - <para>shared directory for storing Lucene index (i.e. NFS);</para> - </listitem> - - <listitem> - <para>changes filter configured as - org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter;</para> - - <note> - <para>This filter ignore changes on non-coordinator nodes, and - index changes on coordinator node.</para> - </note> - </listitem> - - <listitem> - <para>configure JBoss-cache, course;</para> - </listitem> - </itemizedlist></para> - </section> - - <section> - <title>Query-handler configuration</title> - - <para>Configuration example:<programlisting>&lt;workspace name="ws"&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="shareddir/index/db1/ws" /&gt; - &lt;property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /&gt; - &lt;property name="jbosscache-configuration" value="jbosscache-indexer.xml" /&gt; - &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /&gt; - &lt;property name="max-volatile-time" value="60" /&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; -&lt;/workspace&gt;</programlisting> <table> - <title>Config properties description</title> - - <tgroup cols="2"> - <thead> - <row> - <entry>Property name</entry> - - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>index-dir</entry> - - <entry>path to index</entry> - </row> - - <row> - <entry>jbosscache-configuration</entry> - - <entry>template of JBoss-cache configuration for all - query-handlers in repository</entry> - </row> - - <row> - <entry>jgroups-configuration</entry> - - <entry>jgroups-configuration is template configuration for all - components (search, cache, locks) [Add link to document - describing template configurations]</entry> - </row> - - <row> - <entry>jgroups-multiplexer-stack</entry> - - <entry>[TODO about jgroups-multiplexer-stack - add link to - JBoss doc]</entry> - </row> - - <row> - <entry>jbosscache-cluster-name</entry> - - <entry>cluster name (must be unique)</entry> - </row> - - <row> - <entry>max-volatile-time</entry> - - <entry>max time to live for Volatile Index</entry> - </row> - </tbody> - </tgroup> - </table></para> - </section> - - <section> - <title>JBoss-Cache template configuration</title> - - <para>JBoss-Cache template configuration for query handler.</para> - - <para>jbosscache-indexer.xml<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;!-- Configure the TransactionManager --&gt; - &lt;transaction transactionManagerLookupClass="org.jboss.cache.transaction.JBossStandaloneJTAManagerLookup" /&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></para> - - <para>See more about template configurations <link - linkend="ch_jbosscache_config_templates">here</link>.</para> - </section> - </section> -</chapter> Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/search-configuration.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/search-configuration.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/search-configuration.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,774 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_search_configuration"> - <?dbhtml filename="search-configuration.html"?> - - <title>Search Configuration</title> - - <section> - <title>XML Configuration</title> - - <para>JCR index configuration. You can find this file here: - <filename>.../portal/WEB-INF/conf/jcr/repository-configuration.xml</filename></para> - - <programlisting>&lt;repository-service default-repository="db1"&gt; - &lt;repositories&gt; - &lt;repository name="db1" system-workspace="ws" default-workspace="ws"&gt; - .... - &lt;workspaces&gt; - &lt;workspace name="ws"&gt; - .... - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="${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; - ... - &lt;/workspace&gt; - &lt;/workspaces&gt; - &lt;/repository&gt; - &lt;/repositories&gt; -&lt;/repository-service&gt;</programlisting> - </section> - - <section> - <title>Configuration parameters</title> - - <table> - <title></title> - - <tgroup cols="4"> - <thead> - <row> - <entry>Parameter</entry> - - <entry>Default</entry> - - <entry>Description</entry> - - <entry>Since</entry> - </row> - </thead> - - <tbody> - <row> - <entry>index-dir</entry> - - <entry>none</entry> - - <entry>The location of the index directory. This parameter is - mandatory. Up to 1.9 this parameter called "indexDir"</entry> - - <entry>1.0</entry> - </row> - - <row> - <entry>use-compoundfile</entry> - - <entry>true</entry> - - <entry>Advises lucene to use compound files for the index - files.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>min-merge-docs</entry> - - <entry>100</entry> - - <entry>Minimum number of nodes in an index until segments are - merged.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>volatile-idle-time</entry> - - <entry>3</entry> - - <entry>Idle time in seconds until the volatile index part is moved - to a persistent index even though minMergeDocs is not - reached.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>max-merge-docs</entry> - - <entry>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.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>merge-factor</entry> - - <entry>10</entry> - - <entry>Determines how often segment indices are merged.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>max-field-length</entry> - - <entry>10000</entry> - - <entry>The number of words that are fulltext indexed at most per - property.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>cache-size</entry> - - <entry>1000</entry> - - <entry>Size of the document number cache. This cache maps uuids to - lucene document numbers</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>force-consistencycheck</entry> - - <entry>false</entry> - - <entry>Runs a consistency check on every startup. If false, a - consistency check is only performed when the search index detects - a prior forced shutdown.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>auto-repair</entry> - - <entry>true</entry> - - <entry>Errors detected by a consistency check are automatically - repaired. If false, errors are only written to the log.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>query-class</entry> - - <entry>QueryImpl</entry> - - <entry>Class name that implements the javax.jcr.query.Query - interface.This class must also extend from the class: - org.exoplatform.services.jcr.impl.core.query.AbstractQueryImpl.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>document-order</entry> - - <entry>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'.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>result-fetch-size</entry> - - <entry>Integer.MAX_VALUE</entry> - - <entry>The number of results when a query is executed. Default - value: Integer.MAX_VALUE (-&gt; all).</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>excerptprovider-class</entry> - - <entry>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.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>support-highlighting</entry> - - <entry>false</entry> - - <entry>If set to true additional information is stored in the - index to support highlighting using the rep:excerpt() - function.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>synonymprovider-class</entry> - - <entry>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).</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>synonymprovider-config-path</entry> - - <entry>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).</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>indexing-configuration-path</entry> - - <entry>none</entry> - - <entry>The path to the indexing configuration file.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>indexing-configuration-class</entry> - - <entry>IndexingConfigurationImpl</entry> - - <entry>The name of the class that implements - org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfiguration.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>force-consistencycheck</entry> - - <entry>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.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>spellchecker-class</entry> - - <entry>none</entry> - - <entry>The name of a class that implements - org.exoplatform.services.jcr.impl.core.query.lucene.SpellChecker.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>errorlog-size</entry> - - <entry>50(Kb)</entry> - - <entry>The default size of error log file in Kb.</entry> - - <entry>1.9</entry> - </row> - - <row> - <entry>upgrade-index</entry> - - <entry>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.)</entry> - - <entry>1.12</entry> - </row> - - <row> - <entry>analyzer</entry> - - <entry>org.apache.lucene.analysis.standard.StandardAnalyzer</entry> - - <entry>Class name of a lucene analyzer to use for fulltext - indexing of text.</entry> - - <entry>1.12</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>Global Search Index</title> - - <section> - <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> - - <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> - <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) { - 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> - <para>The first one (StandardFilter) removes 's (as 's in - "Peter's") from the end of words and removes dots from - acronyms.</para> - </listitem> - - <listitem> - <para>The second one (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></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.</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.</para> - - <section> - <title>Create the filter</title> - - <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.</para> - </section> - - <section> - <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.</para> - </section> - - <section> - <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() { - return MyAnalyzer; - }</programlisting>to return your analyzer. You can see the attached - SearchIndex.</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> - - <section> - <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<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;</programlisting></para> - </section> - - <section> - <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; - ... - &lt;property name="analyzer" value="org.exoplatform.services.jcr.impl.core.MyAnalyzer"/&gt; - ... - &lt;/properties&gt; -&lt;/query-handler&gt;</programlisting></para> - - <para>When you start exo, your SearchIndex will start to index - contents with the specified filters.</para> - </section> - </section> - </section> - - <section> - <title>Index Adjustments</title> - - <section> - <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> - - <programlisting>&lt;param name="indexing-configuration-path" value="/indexing_configuration.xml"/&gt;</programlisting> - </section> - - <section> - <title>Index rules</title> - - <section> - <title>Node Scope Limit</title> - - <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.</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> - - <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> - <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> - - <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"&gt; - &lt;property&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; -&lt;/configuration&gt;</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:<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 boost="3.0"&gt;Title&lt;/property&gt; - &lt;property boost="1.5"&gt;Text&lt;/property&gt; - &lt;/index-rule&gt; -&lt;/configuration&gt;</programlisting></para> - </section> - - <section> - <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" - 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" - 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" - 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" - 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> - <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></para> - </section> - </section> - - <section> - <title>Index Aggregates</title> - - <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.</para> - - <para>JCR allows you to define index aggregates based on relative path - patterns and primary node types.</para> - - <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></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></para> - - <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></para> - - <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></para> - </section> - - <section> - <title>Property-Level Analyzers</title> - - <section> - <title>Example</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></para> - - <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.</para> - - <para>The WhitespaceAnalyzer tokenizes a property, the KeywordAnalyzer - takes the property as a whole.</para> - </section> - - <section> - <title>Characteristics of Node Scope Searches</title> - - <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.</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).</para> - - <para>If your query is for example:<programlisting>xpath = "//*[jcr:contains(mytext,'analyzer')]"</programlisting></para> - - <para>This xpath does not return a hit in the node with the property - above and default analyzers.</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.</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<programlisting>xpath = "//*[jcr:contains(mytext,'analyzer')]"</programlisting>you - would get a hit because of the word stemming (analyzers - - analyzer).</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> - - <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!</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!</para> - </note> - </section> - </section> - </section> -</chapter> Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/ws/ws.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/ws/ws.xml 2010-02-18 16:32:40 UTC (rev 1905) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/ws/ws.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -1,19 +1,21 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter> - <title>eXo Web Services</title> - - <section> - <title>eXo Web Services introduction</title> - - <para>The Web Services module allows eXo technology to integrate with - external products and services.</para> - - <para>It's implementaion of API for RESTful Web Services with extensions, - Servlet and cross-domain AJAX web-frameworks and JavaBean-JSON - transformer. Find full documentaion on <ulink - url="http://wiki.exoplatform.org/xwiki/bin/view/WS/">eXo - site</ulink>.</para> - </section> -</chapter> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter> + <?dbhtml filename="ch-ws.html"?> + + <title>eXo Web Services</title> + + <section> + <title>eXo Web Services introduction</title> + + <para>The Web Services module allows eXo technology to integrate with + external products and services.</para> + + <para>It's implementaion of API for RESTful Web Services with extensions, + Servlet and cross-domain AJAX web-frameworks and JavaBean-JSON + transformer. Find full documentaion on <ulink + url="http://wiki.exoplatform.org/xwiki/bin/view/WS/">eXo + site</ulink>.</para> + </section> +</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/ws.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/ws.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/ws.xml 2010-02-18 16:44:48 UTC (rev 1906) @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<part> + <?dbhtml filename="part-ws.html"?> + + <title>eXoWS</title> + + <xi:include href="ws/ws.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> +</part>