[exo-jcr-commits] exo-jcr SVN: r2875 - in jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr: concepts and 2 other directories.

Author: sergiykarpenko Date: 2010-08-04 11:01:37 -0400 (Wed, 04 Aug 2010) New Revision: 2875 Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetype-registration.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetypes-and-namespaces.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/configuration-persister.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/exo-jcr-configuration.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/external-value-storages.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/jdbc-data-container-config.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/multilanguage-support.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/search-configuration.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/workspace-persistence-storage.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container-howto.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/lock-manager-config.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/fulltext-search-and-settings.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/searching-repository-content.xml Log: EXOJCR-869: link fixes Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/cluster-config.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="ch_cluster_config"> +<chapter id="JCR.ClusterConfig"> <?dbhtml filename="ch-cluster-config.html"?> <title>Configuring JBoss AS with eXo JCR in cluster</title> @@ -87,7 +87,7 @@ </orderedlist> </section> - <section id="sect_conf_cluster_jcr"> + <section id="JCR.ClusterConfig.JCRExternalConfig"> <title>Configuring JCR to use external configuration</title> <itemizedlist> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetype-registration.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetype-registration.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetype-registration.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -358,9 +358,7 @@ <title>Node type registration</title> <para>eXo JCR implementation supports various methods of the node-type - registration. The most used is registration from <link - linkend="JCR.NodeTypesandNamespaces">xml file</link> on JCR - startup.</para> + registration. </para> <section> <title>Run time registration from xml file.</title> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetypes-and-namespaces.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetypes-and-namespaces.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetypes-and-namespaces.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -11,11 +11,10 @@ <para>Support of node types and namespaces is required by the JSR-170 specification. Beyond the methods required by the specification, eXo JCR - has its own API extension for the <ulink - url="JCR.NodeTypeRegistration"><link - linkend="JCR.NodeTypeRegistration">Node type registration</link></ulink> - as well as the ability to declaratively define node types in the - Repository at the start-up time.</para> + has its own API extension for the <link + linkend="JCR.NodeTypeRegistration">Node type registration</link> as well + as the ability to declaratively define node types in the Repository at the + start-up time.</para> </section> <section> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/configuration-persister.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/configuration-persister.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/configuration-persister.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -1,124 +1,125 @@ -<?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="JCR.ConfigurationPersister"> - <?dbhtml filename="ch-external-value-storages.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> +<?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="JCR.ConfigurationPersister"> + <?dbhtml filename="ch-jcr-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="JCR.JDBCDataContainerConfig">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="JCR.JDBCDataContainerConfig">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> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/exo-jcr-configuration.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/exo-jcr-configuration.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/exo-jcr-configuration.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -21,22 +21,19 @@ </listitem> <listitem> - <para><link linkend="ch_jdbc_data_container">JDBC Data Container + <para><link linkend="JCR.JDBCDataContainerConfig">JDBC Data Container config</link></para> </listitem> <listitem> - <para><link linkend="ch_external_value_storages">External Value + <para><link linkend="JCR.ExternalValueStorages">External Value Storages</link></para> </listitem> <listitem> - <para><link linkend="none">Workspace SimpleDB storage</link></para> + <para><link linkend="JCR.WorkspacePersistenceStorage">Workspace + Persistence Storage</link></para> </listitem> - - <listitem> - <para><link linkend="none">Workspace Persistence Storage</link></para> - </listitem> </itemizedlist> </section> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/external-value-storages.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/external-value-storages.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/external-value-storages.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -13,8 +13,7 @@ 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 [TODO<link linkend="TODO"> Binary values - processing</link>]).</para> + (BLOBs) for example.</para> <para>Value storage configuration is a part of Repository configuration, find more details <link Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/jdbc-data-container-config.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/jdbc-data-container-config.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/jdbc-data-container-config.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -89,7 +89,7 @@ Repository Service and related serivces) and repository-configuration.xml (repositories configuration).</para> - <para>Read more about <link linkend="ch_configuration">Repository + <para>Read more about <link linkend="JCR.eXoJCRconfiguration">Repository configuration</link>.</para> </section> @@ -320,9 +320,10 @@ 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> + <para>Starting from v.1.9 <link + linkend="JCR.eXoJCRconfiguration">repository configuration</link> + parameters supports human-readable formats of values (e.g. 200K - 200 + Kbytes, 30m - 30 minutes etc)</para> </note> </section> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/multilanguage-support.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/multilanguage-support.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/multilanguage-support.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -110,8 +110,7 @@ <title>MySQL</title> <para>JCR MySQL-backend requires special dialect <ulink - url="http://dev.mysql.com/doc/refman/5.0/en/charset-unicode-utf8.htm... - url="http://jira.exoplatform.org/browse/JCR-375">MySQL-UTF8&... + url="http://dev.mysql.com/doc/refman/5.0/en/charset-unicode-utf8.htm... 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 Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/search-configuration.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/search-configuration.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/search-configuration.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -805,31 +805,31 @@ <itemizedlist> <listitem> <para>Get a text excerpt with <emphasis role="bold">highlighted - words</emphasis> that matches the query: <ulink - url="ExcerptProvider&gt;http://wiki.exoplatform.com/xwiki/bin/vi... + words</emphasis> that matches the query: <link + linkend="JCR.SearchingRepositoryContent.Highlighting">ExcerptProvider</link>.</para> </listitem> <listitem> <para>Search for a term and its <emphasis - role="bold">synonyms</emphasis>: <ulink - url="SynonymSearch&gt;http://wiki.exoplatform.com/xwiki/bin/view... + role="bold">synonyms</emphasis>: <link + linkend="JCR.SearchingRepositoryContent.SynonimProvider">SynonymSearch</link></para> </listitem> <listitem> <para>Search for <emphasis role="bold">similar</emphasis> nodes: - <ulink - url="SimilaritySearch&gt;http://wiki.exoplatform.com/xwiki/bin/v... + <link + linkend="JCR.SearchingRepositoryContent.Similarity">SimilaritySearch</link></para> </listitem> <listitem> <para>Check <emphasis role="bold">spelling</emphasis> of a fulltext - query statement: <ulink - url="SpellChecker&gt;http://wiki.exoplatform.com/xwiki/bin/view/... + query statement: <link + linkend="JCR.SearchingRepositoryContent.SpellChecker">SpellChecker</link></para> </listitem> <listitem> <para>Define index <emphasis role="bold">aggregates and - rules</emphasis>: IndexingConfiguration (see this article)</para> + rules</emphasis>: IndexingConfiguration.</para> </listitem> </itemizedlist> </section> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/workspace-persistence-storage.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/workspace-persistence-storage.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/configuration/workspace-persistence-storage.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -1,7 +1,7 @@ <?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="JCR.WorkspaceDataContainer"> +<chapter id="JCR.WorkspacePersistenceStorage"> <?dbhtml filename="ch-workspace-data-container.html"?> <title>Workspace Data Container</title> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container-howto.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container-howto.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container-howto.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -1,112 +1,112 @@ -<?xml version='1.0' ?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - <chapter id="JCR.HowtoimplementWorkspaceDataContainer"> - <title>How-to implement Workspace Data Container</title> - <?dbhtml filename="ch-data-container-howto.html"?> - <section id="ShortintrointoWorkspacedatacontainerimplementationpractices"> - <title>Short intro into Workspace data container implementation practices:</title> - <orderedlist> - <listitem> - <para>Read a bit about the <link linkend="JCRWorkspaceDataContainerarchitecturecontract">contract</link>.</para> - </listitem> - <listitem> - <para>Start new implementation project pom.xml with org.exoplatform.jcr parent. (optional, but will makes the development easy)</para> - </listitem> - <listitem> - <para>Update sources of JCR Core and read JavaDoc on - <emphasis role="bold">org.exoplatform.services.jcr.storage.WorkspaceDataContainer</emphasis> and - <emphasis role="bold">org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</emphasis> interfaces. This two are main part for the implemenation. - </para> - </listitem> - <listitem> - <para>Look at - <emphasis role="bold">org.exoplatform.services.jcr.impl.dataflow.persistent.WorkspacePersistentDataManager</emphasis> sourcecode, check how data meneger uses container and its connections (see in save() method) - </para> - </listitem> - <listitem> - <para>Create - <emphasis role="bold">WorkspaceStorageConnection</emphasis> dummy implementation class. It's freeform class, but to be close to the eXo JCR, check how implemented JDBC or SimpleDB containers ( - <emphasis role="bold">org.exoplatform.services.jcr.impl.storage.jdbc.JDBCStorageConnection</emphasis> and - <emphasis role="bold">org.exoplatform.services.jcr.aws.storage.sdb.SDBWorkspaceStorageConnection</emphasis>). Take in account usage of - <emphasis role="bold">ValueStoragePluginProvider</emphasis> in both implementations.Value storage is an useful option for production versions. But leave it to the end of implementation work. - </para> - </listitem> - <listitem> - <para>Create the connection implementation unit tests to play TTD. (optional, but takes many benefits for the process)</para> - </listitem> - <listitem> - <para>Implement CRUD starting from the read to write etc. Test the methods using external to the implementation ways of data read/write in your backend.</para> - </listitem> - <listitem> - <para>When all methods of the connection done start - <emphasis role="bold">WorkspaceDataContainer</emphasis>. Container class very simple, it's like a factory for the connections only. - </para> - </listitem> - <listitem> - <para>Care about container reuseConnection(WorkspaceStorageConnection) method logic. For some backends it cab be same as openConnection(), but for some others it's important to reuse physical backend connection, e.g. to be in same transaction - see JDBC container.</para> - </listitem> - <listitem> - <para>It's almost ready for use in data manager. Start another test and go on.</para> - </listitem> - </orderedlist> - <para>When the container will be ready for run as JCR persistence storage (e.g. for this level testing) it should be configured in Repository configuration.</para> - <para>Assuming that our new implementation class name is - <emphasis role="bold">org.project.jcr.impl.storage.MyWorkspaceDataContainer</emphasis>. - </para> - <programlisting> &lt;repository-service default-repository="repository"> - &lt;repositories> - &lt;repository name="repository" system-workspace="production" default-workspace="production"> - ............. - &lt;workspaces> - &lt;workspace name="production"> - &lt;container class="org.project.jcr.impl.storage.MyWorkspaceDataContainer"> - &lt;properties> - &lt;property name="propertyName1" value="propertyValue1" /> - &lt;property name="propertyName2" value="propertyValue2" /> - ....... - &lt;property name="propertyNameN" value="propertyValueN" /> - &lt;/properties> - &lt;value-storages> - ....... - &lt;/value-storages> - &lt;/container> - -</programlisting> - <para>Container can be configured using set properties.</para> - </section> - <section id="Valuestorageusagenotes"> - <title>Value storage usage notes:</title> - <para>Value storages pluggable to the container but if it used the container implementation should respect set of interfaces and external storage usage principles.</para> - <para>If the container have - <emphasis role="bold">ValueStoragePluginProvider</emphasis> (e.g. via constructor) it's just few methods to manipulate external Values data. - </para> - <programlisting>// get channel for ValueData write (add or update) -ValueIOChannel channel = valueStorageProvider.getApplicableChannel(data, i); -if (channel == null) { - // write - channel.write(data.getIdentifier(), vd); - // obtain storage id, id can be used for linkage of external ValueData and PropertyData in main backend - String storageId = channel.getStorageId(); -} - -.... - -// delete all Property Values in external storage -ValueIOChannel channel = valueStorageProvider.getChannel(storageId); -channel.delete(propertyData.getIdentifier()); - -.... - -// read ValueData from external storage -ValueIOChannel channel = valueStorageProvider.getChannel(storageId); -ValueData vdata = channel.read(propertyData.getIdentifier(), orderNumber, maxBufferSize); - -</programlisting> - <important> - <title>Important</title> - <para>After a sequence of write and/or delete operations on the storage channel, the channel should be committed (or rolled back on an error). See - <emphasis role="bold">ValueIOChannel.commit()</emphasis> and - <emphasis role="bold">ValueIOChannel.rollback()</emphasis> and how those methods used in JDBC container. - </para> - </important> - </section> - </chapter> +<?xml version='1.0' ?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + <chapter id="JCR.HowToImplementWorkspaceDataContainer"> + <title>How-to implement Workspace Data Container</title> + <?dbhtml filename="ch-data-container-howto.html"?> + <section id="ShortintrointoWorkspacedatacontainerimplementationpractices"> + <title>Short intro into Workspace data container implementation practices:</title> + <orderedlist> + <listitem> + <para>Read a bit about the <link linkend="JCRWorkspaceDataContainerarchitecturecontract">contract</link>.</para> + </listitem> + <listitem> + <para>Start new implementation project pom.xml with org.exoplatform.jcr parent. (optional, but will makes the development easy)</para> + </listitem> + <listitem> + <para>Update sources of JCR Core and read JavaDoc on + <emphasis role="bold">org.exoplatform.services.jcr.storage.WorkspaceDataContainer</emphasis> and + <emphasis role="bold">org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</emphasis> interfaces. This two are main part for the implemenation. + </para> + </listitem> + <listitem> + <para>Look at + <emphasis role="bold">org.exoplatform.services.jcr.impl.dataflow.persistent.WorkspacePersistentDataManager</emphasis> sourcecode, check how data meneger uses container and its connections (see in save() method) + </para> + </listitem> + <listitem> + <para>Create + <emphasis role="bold">WorkspaceStorageConnection</emphasis> dummy implementation class. It's freeform class, but to be close to the eXo JCR, check how implemented JDBC or SimpleDB containers ( + <emphasis role="bold">org.exoplatform.services.jcr.impl.storage.jdbc.JDBCStorageConnection</emphasis> and + <emphasis role="bold">org.exoplatform.services.jcr.aws.storage.sdb.SDBWorkspaceStorageConnection</emphasis>). Take in account usage of + <emphasis role="bold">ValueStoragePluginProvider</emphasis> in both implementations.Value storage is an useful option for production versions. But leave it to the end of implementation work. + </para> + </listitem> + <listitem> + <para>Create the connection implementation unit tests to play TTD. (optional, but takes many benefits for the process)</para> + </listitem> + <listitem> + <para>Implement CRUD starting from the read to write etc. Test the methods using external to the implementation ways of data read/write in your backend.</para> + </listitem> + <listitem> + <para>When all methods of the connection done start + <emphasis role="bold">WorkspaceDataContainer</emphasis>. Container class very simple, it's like a factory for the connections only. + </para> + </listitem> + <listitem> + <para>Care about container reuseConnection(WorkspaceStorageConnection) method logic. For some backends it cab be same as openConnection(), but for some others it's important to reuse physical backend connection, e.g. to be in same transaction - see JDBC container.</para> + </listitem> + <listitem> + <para>It's almost ready for use in data manager. Start another test and go on.</para> + </listitem> + </orderedlist> + <para>When the container will be ready for run as JCR persistence storage (e.g. for this level testing) it should be configured in Repository configuration.</para> + <para>Assuming that our new implementation class name is + <emphasis role="bold">org.project.jcr.impl.storage.MyWorkspaceDataContainer</emphasis>. + </para> + <programlisting> &lt;repository-service default-repository="repository"> + &lt;repositories> + &lt;repository name="repository" system-workspace="production" default-workspace="production"> + ............. + &lt;workspaces> + &lt;workspace name="production"> + &lt;container class="org.project.jcr.impl.storage.MyWorkspaceDataContainer"> + &lt;properties> + &lt;property name="propertyName1" value="propertyValue1" /> + &lt;property name="propertyName2" value="propertyValue2" /> + ....... + &lt;property name="propertyNameN" value="propertyValueN" /> + &lt;/properties> + &lt;value-storages> + ....... + &lt;/value-storages> + &lt;/container> + +</programlisting> + <para>Container can be configured using set properties.</para> + </section> + <section id="Valuestorageusagenotes"> + <title>Value storage usage notes:</title> + <para>Value storages pluggable to the container but if it used the container implementation should respect set of interfaces and external storage usage principles.</para> + <para>If the container have + <emphasis role="bold">ValueStoragePluginProvider</emphasis> (e.g. via constructor) it's just few methods to manipulate external Values data. + </para> + <programlisting>// get channel for ValueData write (add or update) +ValueIOChannel channel = valueStorageProvider.getApplicableChannel(data, i); +if (channel == null) { + // write + channel.write(data.getIdentifier(), vd); + // obtain storage id, id can be used for linkage of external ValueData and PropertyData in main backend + String storageId = channel.getStorageId(); +} + +.... + +// delete all Property Values in external storage +ValueIOChannel channel = valueStorageProvider.getChannel(storageId); +channel.delete(propertyData.getIdentifier()); + +.... + +// read ValueData from external storage +ValueIOChannel channel = valueStorageProvider.getChannel(storageId); +ValueData vdata = channel.read(propertyData.getIdentifier(), orderNumber, maxBufferSize); + +</programlisting> + <important> + <title>Important</title> + <para>After a sequence of write and/or delete operations on the storage channel, the channel should be committed (or rolled back on an error). See + <emphasis role="bold">ValueIOChannel.commit()</emphasis> and + <emphasis role="bold">ValueIOChannel.rollback()</emphasis> and how those methods used in JDBC container. + </para> + </important> + </section> + </chapter> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/data-container.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -1,392 +1,392 @@ -<?xml version='1.0' ?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="JCR.WorkspaceDataContainerarchitecturecontract"> - <?dbhtml filename="ch-data-container.html"?> - <title>JCR Workspace Data Container (architecture contract)</title> - <section id="Goals"> - <title>Goals</title> - <itemizedlist> - <listitem> - <para>Cover Workspace Data Container implementation requirements</para> - </listitem> - <listitem> - <para>Describe container life cycle</para> - </listitem> - <listitem> - <para>Describe relations between container and high-level DataManagers</para> - </listitem> - </itemizedlist> - </section> - <section id="Concepts"> - <title>Concepts</title> - <section id="Containerandconnection"> - <title>Container and connection</title> - <para>Workspace Data Container (container) serves Repository Workspace persistent storage. - WorkspacePersistentDataManager (data manager) uses container to perform CRUD operation on the persistent - storage. - Access to the storage in data manager makes via storage connection obtained from the container (WorkspaceDataContainer - interface implemenatiton). Each connection represents a transaction on the storage. Storage Connection - (connection) should be an implementation of WorkspaceStorageConnection.</para> - <itemizedlist> - <listitem> - <para>Container acts as a factory of a new storage connections. Usually this method is designed to be - synchronized, to avoid possible concurrent issues.</para> - </listitem> - </itemizedlist> - <programlisting>WorkspaceStorageConnection openConnection() throws RepositoryException; -</programlisting> - <itemizedlist> - <listitem> - <para>Open read-only WorkspaceStorageConnection. Read-only connections can be potentially a bit faster in - some cases.</para> - </listitem> - </itemizedlist> - <programlisting>WorkspaceStorageConnection openConnection(boolean readOnly) throws RepositoryException; -</programlisting> - <note> - <title>*EXPERIMENTAL*</title> - <para>Read-only WorkspaceStorageConnection is experimental feature and not currently handled in JCR. - Actually such connections didn't prove their performance, so JCR Core doesn't use them.</para> - </note> - <itemizedlist> - <listitem> - <para>Storage connection might be reused also. Reuse of the connection means reuse of physical resource - (e.g. JDBC Connection) allocated by one connection in another. This feature used in data manager for - saving ordinary and system changes on the system Workspace. But the reuse is an optional feature and - it works only if possible, otherwise the new connection opens.</para> - </listitem> - </itemizedlist> - <programlisting>WorkspaceStorageConnection reuseConnection(WorkspaceStorageConnection original) throws RepositoryException; -</programlisting> - <itemizedlist> - <listitem> - <para>When checking Same-Name Siblings (SNS) existence, JCR Core can use new connection or not. This is - defined via Workspace Data Container configuration and retrieved using special method.</para> - </listitem> - </itemizedlist> - <programlisting>boolean isCheckSNSNewConnection(); -</programlisting> - <important> - <title>New connection for SNS</title> - <para> Sometimes there is a need of checking if there are some nodes with equal names. Usually new Workspace - Storage Connection is used for purpose. The improvement came from JDBC Workspace Data Container, which - shows better performance on Oracle RDBMS when using new connection for checking SNS existence. But later - this led to deadlocks on Sybase RDBMS, so feature was made as an optional and configurable.</para> - </important> - <para>Container initialization based on a configuration only. After the container created it's not possible to - change parameters. Configuration consists of implementation class and set of properties and Value Storages - configuration.</para> - </section> - <section id="Valuestorages"> - <title>Value storages</title> - <para>Container provides optional special mechanism for Value storing. It's possible to configure external - Value Storages via container configuration (available only via configuration). - Value Storage works as fully independent pluggable storage. All required parameters storage obtains from its - configuration. Some storages are possible for one container. - Configuration describes such parameters as ValueStoragePluginimplementation class, set of implementation specific properties and - filters. The filters declares criteria for Value matching to the storage. Only matched Property Values will - be stored. So, in common case, the storage might contains only the part of the Workspace content. - Value Storages are very useful for BLOB storing. E.g. storing on the File System instead of a database.</para> - <para>Container obtains Values Storages from ValueStoragePluginProvider component. Provider acts as a factory - of Value channels (ValueIOChannel). Channel provides all CRUD operation for Value Storage respecting the - transaction manner of work (how it can be possible due to implementation specifics of the storages).</para> - </section> - <section id="Lifecycle"> - <title>Lifecycle</title> - <para>Container used by data manager for read and write operations. - Read operations (getters) uses connection once and close it on the finally. - Write operations performs in commit method as a sequence of create/update calls and final commit (or rollback on error). - Writes uses one connection (or two - another for system workspace) per commit call. One connection - guaranties transaction support for write operations. - Commit or rollback should free/clean all resources consumed by the container (connection).</para> - </section> - <section id="Valuestoragelifecycle"> - <title>Value storage lifecycle</title> - <para>Value storage used from the container inside. Reads are related to a container reads. Writes are commit - related. - Container (connection) implementation should use transaction capabilities of the storages in same way as for other - operations.</para> - </section> - </section> - <section id="Requirements"> - <title>Requirements</title> - <para>Connection create and reuse should be a thread safe operation. - Connection provides CRUD operations support on the storage.</para> - <section id="Readoperations"> - <title>Read operations</title> - <itemizedlist> - <listitem> - <para>Reads ItemData from the storage by item identifier.</para> - </listitem> - </itemizedlist> - <programlisting>ItemData getItemData(String identifier) throws RepositoryException, IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Reads ItemData from the storage using item's parent and name relative the parent location.</para> - </listitem> - </itemizedlist> - <programlisting>ItemData getItemData(NodeData parentData, QPathEntry name) throws RepositoryException,IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Reads List of NodeData from the storage using item's parent location.</para> - </listitem> - </itemizedlist> - <programlisting>List&lt;NodeData> getChildNodesData(NodeData parent) throws RepositoryException, IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Reads List of PropertyData from the storage using item's parent location</para> - </listitem> - </itemizedlist> - <programlisting>List&lt;PropertyData> getChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Reads List of PropertyData with empty ValueData from the storage using item's parent location.</para> - </listitem> - </itemizedlist> - <para>This methiod specially dedicated for non-content modification operations (e.g. Items delete).</para> - <programlisting>List&lt;PropertyData> listChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Reads List of PropertyData from the storage using item's parent location.</para> - </listitem> - </itemizedlist> - <para>It's REFERENCE type Properties referencing Node with given nodeIdentifier. See more in javax.jcr.Node.getReferences()</para> - <programlisting>List&lt;PropertyData> getReferencesData(String nodeIdentifier) throws RepositoryException,IllegalStateException,UnsupportedOperationException; -</programlisting> - </section> - <section id="Writeoperations"> - <title>Write operations</title> - <itemizedlist> - <listitem> - <para>Adds single NodeData.</para> - </listitem> - </itemizedlist> - <programlisting>void add(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Adds single PropertyData.</para> - </listitem> - </itemizedlist> - <programlisting>void add(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Updates NodeData.</para> - </listitem> - </itemizedlist> - <programlisting>void update(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Updates PropertyData.</para> - </listitem> - </itemizedlist> - <programlisting>void update(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Renames NodeData using Node identifier and new name and index from the data.</para> - </listitem> - </itemizedlist> - <programlisting>void rename(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Deletes NodeData.</para> - </listitem> - </itemizedlist> - <programlisting>void delete(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Deletes PropertyData.</para> - </listitem> - </itemizedlist> - <programlisting>void delete(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; -</programlisting> - <itemizedlist> - <listitem> - <para>Persist changes and closes connection. It can be database transaction commit for instance etc.</para> - </listitem> - </itemizedlist> - <programlisting>void commit() throws IllegalStateException, RepositoryException; -</programlisting> - <itemizedlist> - <listitem> - <para>Refuses persistent changes and closes connection. It can be database transaction rollback for instance etc.</para> - </listitem> - </itemizedlist> - <programlisting>void rollback() throws IllegalStateException, RepositoryException; -</programlisting> - <para>All methods throws IllegalStateException if connection is closed. - UnsupportedOperationException if the method is not supported (e.g. JCR Level 1 implementation etc). - RepositoryException if some error occurs during preparation, validation or persistence.</para> - </section> - <section id="Stateoperations"> - <title>State operations</title> - <itemizedlist> - <listitem> - <para>Returns true if connection can be used.</para> - </listitem> - </itemizedlist> - <programlisting>boolean isOpened(); -</programlisting> - </section> - <section id="Validationofwriteoperations"> - <title>Validation of write operations</title> - <para>Container have to care about storage consistency (JCR constraints) on write operations: - (InvalidItemStateException should be thrown according the spec) - At least following checks should be performed:</para> - <itemizedlist> - <listitem> - <para>On ADD errors</para> - <itemizedlist> - <listitem> - <para>Parent not found. Condition: Parent ID (Item with ID is not exists).</para> - </listitem> - <listitem> - <para>Item already exists. Condition: ID (Item with ID already exists).</para> - </listitem> - <listitem> - <para>Item already exists. Condition: Parent ID, Name, Index (Item with parent ID, name and index already exists).</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - <itemizedlist> - <listitem> - <para>On DELETE errors</para> - <itemizedlist> - <listitem> - <para>Item not found. Condition ID.</para> - </listitem> - <listitem> - <para>Can not delete parent till children exists.</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - <itemizedlist> - <listitem> - <para>On UPDATE errors</para> - <itemizedlist> - <listitem> - <para>Item not found. Condition ID.</para> - </listitem> - <listitem> - <para>Item already exists with higher Version. Condition: ID, Version (Some Session had updated Item with ID prior this update).</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </section> - <section id="Consistencyofsave"> - <title>Consistency of save</title> - <para>The container (connection) should implement consistency of Commit (Rollback) in - <emphasis role="bold">transaction manner</emphasis>. - I.e. if set of operations were performed - <emphasis role="bold">before</emphasis> the future - <emphasis role="bold">Commit</emphasis> and another next operation - <emphasis role="bold">fails</emphasis>. - <emphasis role="bold">It should be possible to</emphasis> rollback applied changes using - <emphasis role="bold">Rollback</emphasis> command. - </para> - </section> - </section> - <section id="ValuestoragesAPI"> - <title>Value storages API</title> - <section id="Storagesprovider"> - <title>Storages provider:</title> - <para>Container implementation obtains Values Storages option via ValueStoragePluginProvider component. Provider acts as a factory of Value channels (ValueIOChannel) and has two methods for this purpose:</para> - <itemizedlist> - <listitem> - <para>Return ValueIOChannel matched this property and valueOrderNumer. Null will be returned if no channel matches.</para> - </listitem> - </itemizedlist> - <programlisting>ValueIOChannel getApplicableChannel(PropertyData property, int valueOrderNumer) throws IOException; -</programlisting> - <itemizedlist> - <listitem> - <para>Return ValueIOChannel associated with given storageId.</para> - </listitem> - </itemizedlist> - <programlisting>ValueIOChannel getChannel(String storageId) throws IOException, ValueStorageNotFoundException; -</programlisting> - <para>There is also method for consistency check, but this method doesn't used anywhere and storage implementations has it empty.</para> - </section> - <section id="Valuestorageplugin"> - <title>Value storage plugin</title> - <para>Provider implementation should use ValueStoragePlugin abstract class as a base for all storage implementations. - Plugin provides support for provider implementation methods. Plugin's methods should be implemented:</para> - <itemizedlist> - <listitem> - <para>Initialize this plugin. Used at start time in ValueStoragePluginProvider.</para> - </listitem> - </itemizedlist> - <programlisting>public abstract void init(Properties props, ValueDataResourceHolder resources) throws RepositoryConfigurationException, IOException; -</programlisting> - <itemizedlist> - <listitem> - <para>Open ValueIOChannel.Used in ValueStoragePluginProvider.getApplicableChannel(PropertyData, int) and getChannel(String)</para> - </listitem> - </itemizedlist> - <programlisting>public abstract ValueIOChannel openIOChannel() throws IOException; -</programlisting> - <itemizedlist> - <listitem> - <para>Return true if this storage has same storageId.</para> - </listitem> - </itemizedlist> - <programlisting>public abstract boolean isSame(String valueDataDescriptor); -</programlisting> - </section> - <section id="ValueIOchannel"> - <title>Value I/O channel</title> - <para>Channel should implement ValueIOChannel interface. CRUD operation for Value Storage:</para> - <itemizedlist> - <listitem> - <para>Read Property value.</para> - </listitem> - </itemizedlist> - <programlisting>ValueData read(String propertyId, int orderNumber, int maxBufferSize) throws IOException; -</programlisting> - <itemizedlist> - <listitem> - <para>Add or update Property value.</para> - </listitem> - </itemizedlist> - <programlisting>void write(String propertyId, ValueData data) throws IOException; -</programlisting> - <itemizedlist> - <listitem> - <para>Delete Property all values.</para> - </listitem> - </itemizedlist> - <programlisting>void delete(String propertyId) throws IOException; -</programlisting> - </section> - <section id="Transactionsupportviachannel"> - <title>Transaction support via channel</title> - <para>Modification operations should be applied only on commit. Rollback is required for data created cleanup.</para> - <itemizedlist> - <listitem> - <para>Commit channel changes.</para> - </listitem> - </itemizedlist> - <programlisting>void commit() throws IOException; -</programlisting> - <itemizedlist> - <listitem> - <para>Rollback channel changes.</para> - </listitem> - </itemizedlist> - <programlisting>void rollback() throws IOException; -</programlisting> - </section> - </section> - </chapter> +<?xml version='1.0' ?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="JCR.WorkspaceDataContainer"> + <?dbhtml filename="ch-data-container.html"?> + <title>JCR Workspace Data Container (architecture contract)</title> + <section id="Goals"> + <title>Goals</title> + <itemizedlist> + <listitem> + <para>Cover Workspace Data Container implementation requirements</para> + </listitem> + <listitem> + <para>Describe container life cycle</para> + </listitem> + <listitem> + <para>Describe relations between container and high-level DataManagers</para> + </listitem> + </itemizedlist> + </section> + <section id="Concepts"> + <title>Concepts</title> + <section id="Containerandconnection"> + <title>Container and connection</title> + <para>Workspace Data Container (container) serves Repository Workspace persistent storage. + WorkspacePersistentDataManager (data manager) uses container to perform CRUD operation on the persistent + storage. + Access to the storage in data manager makes via storage connection obtained from the container (WorkspaceDataContainer + interface implemenatiton). Each connection represents a transaction on the storage. Storage Connection + (connection) should be an implementation of WorkspaceStorageConnection.</para> + <itemizedlist> + <listitem> + <para>Container acts as a factory of a new storage connections. Usually this method is designed to be + synchronized, to avoid possible concurrent issues.</para> + </listitem> + </itemizedlist> + <programlisting>WorkspaceStorageConnection openConnection() throws RepositoryException; +</programlisting> + <itemizedlist> + <listitem> + <para>Open read-only WorkspaceStorageConnection. Read-only connections can be potentially a bit faster in + some cases.</para> + </listitem> + </itemizedlist> + <programlisting>WorkspaceStorageConnection openConnection(boolean readOnly) throws RepositoryException; +</programlisting> + <note> + <title>*EXPERIMENTAL*</title> + <para>Read-only WorkspaceStorageConnection is experimental feature and not currently handled in JCR. + Actually such connections didn't prove their performance, so JCR Core doesn't use them.</para> + </note> + <itemizedlist> + <listitem> + <para>Storage connection might be reused also. Reuse of the connection means reuse of physical resource + (e.g. JDBC Connection) allocated by one connection in another. This feature used in data manager for + saving ordinary and system changes on the system Workspace. But the reuse is an optional feature and + it works only if possible, otherwise the new connection opens.</para> + </listitem> + </itemizedlist> + <programlisting>WorkspaceStorageConnection reuseConnection(WorkspaceStorageConnection original) throws RepositoryException; +</programlisting> + <itemizedlist> + <listitem> + <para>When checking Same-Name Siblings (SNS) existence, JCR Core can use new connection or not. This is + defined via Workspace Data Container configuration and retrieved using special method.</para> + </listitem> + </itemizedlist> + <programlisting>boolean isCheckSNSNewConnection(); +</programlisting> + <important> + <title>New connection for SNS</title> + <para> Sometimes there is a need of checking if there are some nodes with equal names. Usually new Workspace + Storage Connection is used for purpose. The improvement came from JDBC Workspace Data Container, which + shows better performance on Oracle RDBMS when using new connection for checking SNS existence. But later + this led to deadlocks on Sybase RDBMS, so feature was made as an optional and configurable.</para> + </important> + <para>Container initialization based on a configuration only. After the container created it's not possible to + change parameters. Configuration consists of implementation class and set of properties and Value Storages + configuration.</para> + </section> + <section id="Valuestorages"> + <title>Value storages</title> + <para>Container provides optional special mechanism for Value storing. It's possible to configure external + Value Storages via container configuration (available only via configuration). + Value Storage works as fully independent pluggable storage. All required parameters storage obtains from its + configuration. Some storages are possible for one container. + Configuration describes such parameters as ValueStoragePluginimplementation class, set of implementation specific properties and + filters. The filters declares criteria for Value matching to the storage. Only matched Property Values will + be stored. So, in common case, the storage might contains only the part of the Workspace content. + Value Storages are very useful for BLOB storing. E.g. storing on the File System instead of a database.</para> + <para>Container obtains Values Storages from ValueStoragePluginProvider component. Provider acts as a factory + of Value channels (ValueIOChannel). Channel provides all CRUD operation for Value Storage respecting the + transaction manner of work (how it can be possible due to implementation specifics of the storages).</para> + </section> + <section id="Lifecycle"> + <title>Lifecycle</title> + <para>Container used by data manager for read and write operations. + Read operations (getters) uses connection once and close it on the finally. + Write operations performs in commit method as a sequence of create/update calls and final commit (or rollback on error). + Writes uses one connection (or two - another for system workspace) per commit call. One connection + guaranties transaction support for write operations. + Commit or rollback should free/clean all resources consumed by the container (connection).</para> + </section> + <section id="Valuestoragelifecycle"> + <title>Value storage lifecycle</title> + <para>Value storage used from the container inside. Reads are related to a container reads. Writes are commit + related. + Container (connection) implementation should use transaction capabilities of the storages in same way as for other + operations.</para> + </section> + </section> + <section id="Requirements"> + <title>Requirements</title> + <para>Connection create and reuse should be a thread safe operation. + Connection provides CRUD operations support on the storage.</para> + <section id="Readoperations"> + <title>Read operations</title> + <itemizedlist> + <listitem> + <para>Reads ItemData from the storage by item identifier.</para> + </listitem> + </itemizedlist> + <programlisting>ItemData getItemData(String identifier) throws RepositoryException, IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Reads ItemData from the storage using item's parent and name relative the parent location.</para> + </listitem> + </itemizedlist> + <programlisting>ItemData getItemData(NodeData parentData, QPathEntry name) throws RepositoryException,IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Reads List of NodeData from the storage using item's parent location.</para> + </listitem> + </itemizedlist> + <programlisting>List&lt;NodeData> getChildNodesData(NodeData parent) throws RepositoryException, IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Reads List of PropertyData from the storage using item's parent location</para> + </listitem> + </itemizedlist> + <programlisting>List&lt;PropertyData> getChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Reads List of PropertyData with empty ValueData from the storage using item's parent location.</para> + </listitem> + </itemizedlist> + <para>This methiod specially dedicated for non-content modification operations (e.g. Items delete).</para> + <programlisting>List&lt;PropertyData> listChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Reads List of PropertyData from the storage using item's parent location.</para> + </listitem> + </itemizedlist> + <para>It's REFERENCE type Properties referencing Node with given nodeIdentifier. See more in javax.jcr.Node.getReferences()</para> + <programlisting>List&lt;PropertyData> getReferencesData(String nodeIdentifier) throws RepositoryException,IllegalStateException,UnsupportedOperationException; +</programlisting> + </section> + <section id="Writeoperations"> + <title>Write operations</title> + <itemizedlist> + <listitem> + <para>Adds single NodeData.</para> + </listitem> + </itemizedlist> + <programlisting>void add(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Adds single PropertyData.</para> + </listitem> + </itemizedlist> + <programlisting>void add(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Updates NodeData.</para> + </listitem> + </itemizedlist> + <programlisting>void update(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Updates PropertyData.</para> + </listitem> + </itemizedlist> + <programlisting>void update(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Renames NodeData using Node identifier and new name and index from the data.</para> + </listitem> + </itemizedlist> + <programlisting>void rename(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Deletes NodeData.</para> + </listitem> + </itemizedlist> + <programlisting>void delete(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Deletes PropertyData.</para> + </listitem> + </itemizedlist> + <programlisting>void delete(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; +</programlisting> + <itemizedlist> + <listitem> + <para>Persist changes and closes connection. It can be database transaction commit for instance etc.</para> + </listitem> + </itemizedlist> + <programlisting>void commit() throws IllegalStateException, RepositoryException; +</programlisting> + <itemizedlist> + <listitem> + <para>Refuses persistent changes and closes connection. It can be database transaction rollback for instance etc.</para> + </listitem> + </itemizedlist> + <programlisting>void rollback() throws IllegalStateException, RepositoryException; +</programlisting> + <para>All methods throws IllegalStateException if connection is closed. + UnsupportedOperationException if the method is not supported (e.g. JCR Level 1 implementation etc). + RepositoryException if some error occurs during preparation, validation or persistence.</para> + </section> + <section id="Stateoperations"> + <title>State operations</title> + <itemizedlist> + <listitem> + <para>Returns true if connection can be used.</para> + </listitem> + </itemizedlist> + <programlisting>boolean isOpened(); +</programlisting> + </section> + <section id="Validationofwriteoperations"> + <title>Validation of write operations</title> + <para>Container have to care about storage consistency (JCR constraints) on write operations: + (InvalidItemStateException should be thrown according the spec) + At least following checks should be performed:</para> + <itemizedlist> + <listitem> + <para>On ADD errors</para> + <itemizedlist> + <listitem> + <para>Parent not found. Condition: Parent ID (Item with ID is not exists).</para> + </listitem> + <listitem> + <para>Item already exists. Condition: ID (Item with ID already exists).</para> + </listitem> + <listitem> + <para>Item already exists. Condition: Parent ID, Name, Index (Item with parent ID, name and index already exists).</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + <para>On DELETE errors</para> + <itemizedlist> + <listitem> + <para>Item not found. Condition ID.</para> + </listitem> + <listitem> + <para>Can not delete parent till children exists.</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + <para>On UPDATE errors</para> + <itemizedlist> + <listitem> + <para>Item not found. Condition ID.</para> + </listitem> + <listitem> + <para>Item already exists with higher Version. Condition: ID, Version (Some Session had updated Item with ID prior this update).</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </section> + <section id="Consistencyofsave"> + <title>Consistency of save</title> + <para>The container (connection) should implement consistency of Commit (Rollback) in + <emphasis role="bold">transaction manner</emphasis>. + I.e. if set of operations were performed + <emphasis role="bold">before</emphasis> the future + <emphasis role="bold">Commit</emphasis> and another next operation + <emphasis role="bold">fails</emphasis>. + <emphasis role="bold">It should be possible to</emphasis> rollback applied changes using + <emphasis role="bold">Rollback</emphasis> command. + </para> + </section> + </section> + <section id="ValuestoragesAPI"> + <title>Value storages API</title> + <section id="Storagesprovider"> + <title>Storages provider:</title> + <para>Container implementation obtains Values Storages option via ValueStoragePluginProvider component. Provider acts as a factory of Value channels (ValueIOChannel) and has two methods for this purpose:</para> + <itemizedlist> + <listitem> + <para>Return ValueIOChannel matched this property and valueOrderNumer. Null will be returned if no channel matches.</para> + </listitem> + </itemizedlist> + <programlisting>ValueIOChannel getApplicableChannel(PropertyData property, int valueOrderNumer) throws IOException; +</programlisting> + <itemizedlist> + <listitem> + <para>Return ValueIOChannel associated with given storageId.</para> + </listitem> + </itemizedlist> + <programlisting>ValueIOChannel getChannel(String storageId) throws IOException, ValueStorageNotFoundException; +</programlisting> + <para>There is also method for consistency check, but this method doesn't used anywhere and storage implementations has it empty.</para> + </section> + <section id="Valuestorageplugin"> + <title>Value storage plugin</title> + <para>Provider implementation should use ValueStoragePlugin abstract class as a base for all storage implementations. + Plugin provides support for provider implementation methods. Plugin's methods should be implemented:</para> + <itemizedlist> + <listitem> + <para>Initialize this plugin. Used at start time in ValueStoragePluginProvider.</para> + </listitem> + </itemizedlist> + <programlisting>public abstract void init(Properties props, ValueDataResourceHolder resources) throws RepositoryConfigurationException, IOException; +</programlisting> + <itemizedlist> + <listitem> + <para>Open ValueIOChannel.Used in ValueStoragePluginProvider.getApplicableChannel(PropertyData, int) and getChannel(String)</para> + </listitem> + </itemizedlist> + <programlisting>public abstract ValueIOChannel openIOChannel() throws IOException; +</programlisting> + <itemizedlist> + <listitem> + <para>Return true if this storage has same storageId.</para> + </listitem> + </itemizedlist> + <programlisting>public abstract boolean isSame(String valueDataDescriptor); +</programlisting> + </section> + <section id="ValueIOchannel"> + <title>Value I/O channel</title> + <para>Channel should implement ValueIOChannel interface. CRUD operation for Value Storage:</para> + <itemizedlist> + <listitem> + <para>Read Property value.</para> + </listitem> + </itemizedlist> + <programlisting>ValueData read(String propertyId, int orderNumber, int maxBufferSize) throws IOException; +</programlisting> + <itemizedlist> + <listitem> + <para>Add or update Property value.</para> + </listitem> + </itemizedlist> + <programlisting>void write(String propertyId, ValueData data) throws IOException; +</programlisting> + <itemizedlist> + <listitem> + <para>Delete Property all values.</para> + </listitem> + </itemizedlist> + <programlisting>void delete(String propertyId) throws IOException; +</programlisting> + </section> + <section id="Transactionsupportviachannel"> + <title>Transaction support via channel</title> + <para>Modification operations should be applied only on commit. Rollback is required for data created cleanup.</para> + <itemizedlist> + <listitem> + <para>Commit channel changes.</para> + </listitem> + </itemizedlist> + <programlisting>void commit() throws IOException; +</programlisting> + <itemizedlist> + <listitem> + <para>Rollback channel changes.</para> + </listitem> + </itemizedlist> + <programlisting>void rollback() throws IOException; +</programlisting> + </section> + </section> + </chapter> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/lock-manager-config.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/lock-manager-config.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/lock-manager-config.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -1,442 +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="JCR.LockManagerConfiguration"> - <?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> +<?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="JCR.LockManagerConfiguration"> + <?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="JCR.eXoJCRconfiguration">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="JCR.ClusterConfig.JCRExternalConfig">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> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/fulltext-search-and-settings.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/fulltext-search-and-settings.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/fulltext-search-and-settings.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -1,280 +1,281 @@ -<?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="JCR.FulltextSearchAndSettings"> - <title>Fulltext Search And Affecting Settings</title> - - <section> - <title>Property content indexing</title> - - <para>Each property of a node (if it is indexable) is processed with - Lucene analyzer and stored in Lucene index. That's called indexing of a - property. After that we can perform a fulltext search among these indexed - properties.</para> - </section> - - <section> - <title>Lucene Analyzers</title> - - <para>The sense of analyzers is to transform all strings stored in the - index in a well-defined condition. The same analyzer(s) is/are used when - searching in order to adapt the query string to the index reality.</para> - - <para>Therefore, performing the same query using different analyzers can - return different results.</para> - - <para>Now, let's see how the same string is transformed by different - analyzers.</para> - - <table> - <title>"The quick brown fox jumped over the lazy dogs"</title> - - <tgroup cols="2"> - <thead> - <row> - <entry>Analyzer</entry> - - <entry>Parsed</entry> - </row> - </thead> - - <tbody> - <row> - <entry>org.apache.lucene.analysis.WhitespaceAnalyzer</entry> - - <entry>[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] - [dogs]</entry> - </row> - - <row> - <entry>org.apache.lucene.analysis.SimpleAnalyzer</entry> - - <entry>[the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] - [dogs]</entry> - </row> - - <row> - <entry>org.apache.lucene.analysis.StopAnalyzer</entry> - - <entry>[quick] [brown] [fox] [jumped] [over] [lazy] [dogs]</entry> - </row> - - <row> - <entry>org.apache.lucene.analysis.standard.StandardAnalyzer</entry> - - <entry>[quick] [brown] [fox] [jumped] [over] [lazy] [dogs]</entry> - </row> - - <row> - <entry>org.apache.lucene.analysis.snowball.SnowballAnalyzer</entry> - - <entry>[quick] [brown] [fox] [jump] [over] [lazi] [dog]</entry> - </row> - - <row> - <entry>org.apache.lucene.analysis.standard.StandardAnalyzer - (configured without stop word - jcr default analyzer)</entry> - - <entry>[the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] - [dogs]</entry> - </row> - </tbody> - </tgroup> - </table> - - <table> - <title>"XY&amp;Z Corporation - xyz(a)example.com&quot;&lt;/title&gt; - - <tgroup cols="2"> - <thead> - <row> - <entry>Analyzer</entry> - - <entry>Parsed</entry> - </row> - </thead> - - <tbody> - <row> - <entry>org.apache.lucene.analysis.WhitespaceAnalyzer</entry> - - <entry>[XY&amp;Z] [Corporation] [-] [xyz(a)example.com]&lt;/entry&gt; - </row> - - <row> - <entry>org.apache.lucene.analysis.SimpleAnalyzer</entry> - - <entry>[xy] [z] [corporation] [xyz] [example] [com]</entry> - </row> - - <row> - <entry>org.apache.lucene.analysis.StopAnalyzer</entry> - - <entry>[xy] [z] [corporation] [xyz] [example] [com]</entry> - </row> - - <row> - <entry>org.apache.lucene.analysis.standard.StandardAnalyzer</entry> - - <entry>[xy&amp;z] [corporation] [xyz@example] [com]</entry> - </row> - - <row> - <entry>org.apache.lucene.analysis.snowball.SnowballAnalyzer</entry> - - <entry>[xy&amp;z] [corpor] [xyz@exampl] [com]</entry> - </row> - - <row> - <entry>org.apache.lucene.analysis.standard.StandardAnalyzer - (configured without stop word - jcr default analyzer)</entry> - - <entry>[xy&amp;z] [corporation] [xyz@example] [com]</entry> - </row> - </tbody> - </tgroup> - </table> - - <note> - <para>StandardAnalyzer is the default analyzer in exo's jcr search - engine. But we do not use stop words.</para> - </note> - - <para>You can assign your analyzer as described in <link - linkend="JCR.SearchConfiguration">Search Configuration</link></para> - </section> - - <section> - <title>How are different properties indexed?</title> - - <para>Different properties are indexed in different ways, this affect to - can it be searched like fulltext by property or not.</para> - - <para>Only two property types are indexed as fulltext searcheable: STRING - and BINARY.</para> - - <table> - <title>Fulltext search by different properties</title> - - <tgroup cols="3"> - <thead> - <row> - <entry>Property Type</entry> - - <entry>Fulltext search by all properties</entry> - - <entry>Fulltext search by exact property</entry> - </row> - </thead> - - <tbody> - <row> - <entry>STRING</entry> - - <entry>YES</entry> - - <entry>YES</entry> - </row> - - <row> - <entry>BINARY</entry> - - <entry>YES</entry> - - <entry>NO</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>For example. We have property jcr:data (it' BINARY). Its stored - well. But you will newer find any string with query like:</para> - - <programlisting>SELECT * FROM nt:resource WHERE CONTAINS(jcr:data, 'some string')</programlisting> - - <para>Because,  BINARY is not searchable by fulltext search on exact - property.</para> - - <para>But, next query will return result (off course if node has searched - data):</para> - - <programlisting>SELECT * FROM nt:resource WHERE CONTAINS( * , 'some string')</programlisting> - </section> - - <section> - <title>Fulltext search query examples</title> - - <itemizedlist> - <listitem> - <para><link linkend="JCR.FulltextSearchByProperty">JCR.Fulltext Search - by Property</link></para> - </listitem> - - <listitem> - <para><link linkend="JCR.FulltextSearchByAllProperties">JCR.Fulltext - Search by All Properties</link></para> - </listitem> - - <listitem> - <para><link linkend="JCR.AggregationRule">Find nt:file document by - content of its child jcr:content node</link></para> - </listitem> - - <listitem> - <para><link linkend="JCR.IgnoreAccentSymbols">How to set a new - analyzer. Accent symbols ignoring</link></para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Different analyzers in action</title> - - <para>First of all, we will fill repository by nodes with mixin type - 'mix:title' and different values of 'jcr:description' property.</para> - - <itemizedlist> - <listitem> - <para>root</para> - - <itemizedlist> - <listitem> - <para>document1 (mix:title) jcr:description = "The quick brown fox - jumped over the lazy dogs"</para> - </listitem> - - <listitem> - <para>document2 (mix:title) jcr:description = "Brown fox live in - forest."</para> - </listitem> - - <listitem> - <para>document3 (mix:title) jcr:description = "Fox is a nice - animal."</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - - <para>Lets see analyzers effect closer. In first case we use base jcr - settings, so, as mentioned above, string "The quick brown fox jumped over - the lazy dogs" will be transformed to set {[the] [quick] [brown] [fox] - [jumped] [over] [the] [lazy] [dogs] }</para> - - <programlisting>// make SQL query -QueryManager queryManager = workspace.getQueryManager(); -String sqlStatement = "SELECT * FROM mix:title WHERE CONTAINS(jcr:description, 'the')"; -// create query -Query query = queryManager.createQuery(sqlStatement, Query.SQL); -// execute query and fetch result -QueryResult result = query.execute();</programlisting> - - <para>NodeIterator will return "document1".</para> - - <para>Now change default analyzer to - org.apache.lucene.analysis.StopAnalyzer. Fill repository again (new - Analyzer must process nodes properties) and run same query again. It will - return nothing, because stop words like "the" will be excluded from parsed - string set.</para> - </section> -</chapter> +<?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="JCR.FulltextSearchAndSettings"> + <?dbhtml filename="ch-jcr-fulltext-search-and-settings.html"?> + <title>Fulltext Search And Affecting Settings</title> + + <section> + <title>Property content indexing</title> + + <para>Each property of a node (if it is indexable) is processed with + Lucene analyzer and stored in Lucene index. That's called indexing of a + property. After that we can perform a fulltext search among these indexed + properties.</para> + </section> + + <section> + <title>Lucene Analyzers</title> + + <para>The sense of analyzers is to transform all strings stored in the + index in a well-defined condition. The same analyzer(s) is/are used when + searching in order to adapt the query string to the index reality.</para> + + <para>Therefore, performing the same query using different analyzers can + return different results.</para> + + <para>Now, let's see how the same string is transformed by different + analyzers.</para> + + <table> + <title>"The quick brown fox jumped over the lazy dogs"</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Analyzer</entry> + + <entry>Parsed</entry> + </row> + </thead> + + <tbody> + <row> + <entry>org.apache.lucene.analysis.WhitespaceAnalyzer</entry> + + <entry>[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] + [dogs]</entry> + </row> + + <row> + <entry>org.apache.lucene.analysis.SimpleAnalyzer</entry> + + <entry>[the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] + [dogs]</entry> + </row> + + <row> + <entry>org.apache.lucene.analysis.StopAnalyzer</entry> + + <entry>[quick] [brown] [fox] [jumped] [over] [lazy] [dogs]</entry> + </row> + + <row> + <entry>org.apache.lucene.analysis.standard.StandardAnalyzer</entry> + + <entry>[quick] [brown] [fox] [jumped] [over] [lazy] [dogs]</entry> + </row> + + <row> + <entry>org.apache.lucene.analysis.snowball.SnowballAnalyzer</entry> + + <entry>[quick] [brown] [fox] [jump] [over] [lazi] [dog]</entry> + </row> + + <row> + <entry>org.apache.lucene.analysis.standard.StandardAnalyzer + (configured without stop word - jcr default analyzer)</entry> + + <entry>[the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] + [dogs]</entry> + </row> + </tbody> + </tgroup> + </table> + + <table> + <title>"XY&amp;Z Corporation - xyz(a)example.com&quot;&lt;/title&gt; + + <tgroup cols="2"> + <thead> + <row> + <entry>Analyzer</entry> + + <entry>Parsed</entry> + </row> + </thead> + + <tbody> + <row> + <entry>org.apache.lucene.analysis.WhitespaceAnalyzer</entry> + + <entry>[XY&amp;Z] [Corporation] [-] [xyz(a)example.com]&lt;/entry&gt; + </row> + + <row> + <entry>org.apache.lucene.analysis.SimpleAnalyzer</entry> + + <entry>[xy] [z] [corporation] [xyz] [example] [com]</entry> + </row> + + <row> + <entry>org.apache.lucene.analysis.StopAnalyzer</entry> + + <entry>[xy] [z] [corporation] [xyz] [example] [com]</entry> + </row> + + <row> + <entry>org.apache.lucene.analysis.standard.StandardAnalyzer</entry> + + <entry>[xy&amp;z] [corporation] [xyz@example] [com]</entry> + </row> + + <row> + <entry>org.apache.lucene.analysis.snowball.SnowballAnalyzer</entry> + + <entry>[xy&amp;z] [corpor] [xyz@exampl] [com]</entry> + </row> + + <row> + <entry>org.apache.lucene.analysis.standard.StandardAnalyzer + (configured without stop word - jcr default analyzer)</entry> + + <entry>[xy&amp;z] [corporation] [xyz@example] [com]</entry> + </row> + </tbody> + </tgroup> + </table> + + <note> + <para>StandardAnalyzer is the default analyzer in exo's jcr search + engine. But we do not use stop words.</para> + </note> + + <para>You can assign your analyzer as described in <link + linkend="JCR.SearchConfiguration">Search Configuration</link></para> + </section> + + <section> + <title>How are different properties indexed?</title> + + <para>Different properties are indexed in different ways, this affect to + can it be searched like fulltext by property or not.</para> + + <para>Only two property types are indexed as fulltext searcheable: STRING + and BINARY.</para> + + <table> + <title>Fulltext search by different properties</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Property Type</entry> + + <entry>Fulltext search by all properties</entry> + + <entry>Fulltext search by exact property</entry> + </row> + </thead> + + <tbody> + <row> + <entry>STRING</entry> + + <entry>YES</entry> + + <entry>YES</entry> + </row> + + <row> + <entry>BINARY</entry> + + <entry>YES</entry> + + <entry>NO</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>For example. We have property jcr:data (it' BINARY). Its stored + well. But you will newer find any string with query like:</para> + + <programlisting>SELECT * FROM nt:resource WHERE CONTAINS(jcr:data, 'some string')</programlisting> + + <para>Because,  BINARY is not searchable by fulltext search on exact + property.</para> + + <para>But, next query will return result (off course if node has searched + data):</para> + + <programlisting>SELECT * FROM nt:resource WHERE CONTAINS( * , 'some string')</programlisting> + </section> + + <section> + <title>Fulltext search query examples</title> + + <itemizedlist> + <listitem> + <para><link linkend="JCR.FulltextSearchByProperty">JCR.Fulltext Search + by Property</link></para> + </listitem> + + <listitem> + <para><link linkend="JCR.FulltextSearchByAllProperties">JCR.Fulltext + Search by All Properties</link></para> + </listitem> + + <listitem> + <para><link linkend="JCR.AggregationRule">Find nt:file document by + content of its child jcr:content node</link></para> + </listitem> + + <listitem> + <para><link linkend="JCR.IgnoreAccentSymbols">How to set a new + analyzer. Accent symbols ignoring</link></para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Different analyzers in action</title> + + <para>First of all, we will fill repository by nodes with mixin type + 'mix:title' and different values of 'jcr:description' property.</para> + + <itemizedlist> + <listitem> + <para>root</para> + + <itemizedlist> + <listitem> + <para>document1 (mix:title) jcr:description = "The quick brown fox + jumped over the lazy dogs"</para> + </listitem> + + <listitem> + <para>document2 (mix:title) jcr:description = "Brown fox live in + forest."</para> + </listitem> + + <listitem> + <para>document3 (mix:title) jcr:description = "Fox is a nice + animal."</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + + <para>Lets see analyzers effect closer. In first case we use base jcr + settings, so, as mentioned above, string "The quick brown fox jumped over + the lazy dogs" will be transformed to set {[the] [quick] [brown] [fox] + [jumped] [over] [the] [lazy] [dogs] }</para> + + <programlisting>// make SQL query +QueryManager queryManager = workspace.getQueryManager(); +String sqlStatement = "SELECT * FROM mix:title WHERE CONTAINS(jcr:description, 'the')"; +// create query +Query query = queryManager.createQuery(sqlStatement, Query.SQL); +// execute query and fetch result +QueryResult result = query.execute();</programlisting> + + <para>NodeIterator will return "document1".</para> + + <para>Now change default analyzer to + org.apache.lucene.analysis.StopAnalyzer. Fill repository again (new + Analyzer must process nodes properties) and run same query again. It will + return nothing, because stop words like "the" will be excluded from parsed + string set.</para> + </section> +</chapter> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/searching-repository-content.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/searching-repository-content.xml 2010-08-04 13:51:23 UTC (rev 2874) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/searching-repository-content.xml 2010-08-04 15:01:37 UTC (rev 2875) @@ -1,374 +1,374 @@ -<?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="JCR.SearchingRepositoryContent"> - <?dbhtml filename="ch-jcr-searching-repository-conten.html"?> - - <title>Searching Repository Content</title> - - <section> - <title>Introduction</title> - - <para>You can find the JCR configuration file here: - .../portal/WEB-INF/conf/jcr/repository-configuration.xml. Please read also - <link linkend="JCR.SearchConfiguration">Search Configuration</link> for - more information about index configuration.</para> - </section> - - <section> - <title>Bi-directional RangeIterator (since 1.9)</title> - - <para>QueryResult.getNodes() will return bi-directional NodeIterator - implementation.</para> - - <note> - <para>Bi-directional NodeIterator is <emphasis role="bold">not - supported</emphasis> in two cases:</para> - - <itemizedlist> - <listitem> - <para>SQL query: select * from nt:base</para> - </listitem> - - <listitem> - <para>XPath query: //* .</para> - </listitem> - </itemizedlist> - - <para>")</para> - </note> - - <para>TwoWayRangeIterator interface:</para> - - <programlisting>/** - * Skip a number of elements in the iterator. - * - * @param skipNum the non-negative number of elements to skip - * @throws java.util.NoSuchElementException if skipped past the first element - * in the iterator. - */ -public void skipBack(long skipNum);</programlisting> - - <para>Usage:</para> - - <programlisting>NodeIterator iter = queryResult.getNodes(); -while (iter.hasNext()) { - if (skipForward) { - iter.skip(10); // Skip 10 nodes in forward direction - } else if (skipBack) { - TwoWayRangeIterator backIter = (TwoWayRangeIterator) iter; - backIter.skipBack(10); // Skip 10 nodes back - } - ....... -}</programlisting> - </section> - - <section> - <title>Fuzzy Searches (since 1.0)</title> - - <para>JCR supports such features as Lucene Fuzzy Searches <ulink - url="http://lucene.apache.org/java/2_3_2/queryparsersyntax.html"... - Lucene - Query Parser Syntax</ulink>.</para> - - <para>To use it you have to form a query like described below:</para> - - <programlisting>QueryManager qman = session.getWorkspace().getQueryManager(); -Query q = qman.createQuery("select * from nt:base where contains(field, 'ccccc~')", Query.SQL); -QueryResult res = q.execute();</programlisting> - </section> - - <section> - <title>SynonymSearch (since 1.9)</title> - - <para>Searching with synonyms is integrated in the jcr:contains() function - and uses the same syntax as synonym searches in Google. If a search term - is prefixed by a tilde symbol ( ~ ) also synonyms of the search term are - taken into consideration. Example:</para> - - <programlisting>SQL: select * from nt:resource where contains(., '~parameter') - -XPath: //element(*, nt:resource)[jcr:contains(., '~parameter')</programlisting> - - <para>This feature is disabled per default and you need to add a - configuration parameter to the query-handler element in your jcr - configuration file to enable it.</para> - - <programlisting>&lt;param name="synonymprovider-config-path" value="..you path to configuration file....."/&gt; -&lt;param name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider"/&gt;</programlisting> - - <programlisting>/** - * &lt;code&gt;SynonymProvider&lt;/code&gt; defines an interface for a component that - * returns synonyms for a given term. - */ -public interface SynonymProvider { - - /** - * Initializes the synonym provider and passes the file system resource to - * the synonym provider configuration defined by the configuration value of - * the &lt;code&gt;synonymProviderConfigPath&lt;/code&gt; parameter. The resource may be - * &lt;code&gt;null&lt;/code&gt; if the configuration parameter is not set. - * - * @param fsr the file system resource to the synonym provider - * configuration. - * @throws IOException if an error occurs while initializing the synonym - * provider. - */ - public void initialize(InputStream fsr) throws IOException; - - /** - * Returns an array of terms that are considered synonyms for the given - * &lt;code&gt;term&lt;/code&gt;. - * - * @param term a search term. - * @return an array of synonyms for the given &lt;code&gt;term&lt;/code&gt; or an empty - * array if no synonyms are known. - */ - public String[] getSynonyms(String term); -}</programlisting> - </section> - - <section id="JCR.SearchingRepositoryContent.Highlighting"> - <title>Highlighting (Since 1.9)</title> - - <para>An ExcerptProvider retrieves text excerpts for a node in the query - result and marks up the words in the text that match the query - terms.</para> - - <para>Per default highlighting words that matched the query is disabled - because this feature requires that additional information is written to - the search index. To enable this feature you need to add a configuration - parameter to the query-handler element in your jcr configuration file to - enable it.</para> - - <programlisting>&lt;param name="support-highlighting" value="true"/&gt;</programlisting> - - <para>Additionally there is a parameter that controls the format of the - excerpt created. In JCR 1.9 the default is set to - org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt. - The configuration parameter for this setting is:</para> - - <programlisting>&lt;param name="excerptprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.DefaultXMLExcerpt"/&gt;</programlisting> - - <section> - <title>DefaultXMLExcerpt</title> - - <para>This excerpt provider creates an XML fragment of the following - form:</para> - - <programlisting>&lt;excerpt&gt; - &lt;fragment&gt; - &lt;highlight&gt;exoplatform&lt;/highlight&gt; implements both the mandatory - XPath and optional SQL &lt;highlight&gt;query&lt;/highlight&gt; syntax. - &lt;/fragment&gt; - &lt;fragment&gt; - Before parsing the XPath &lt;highlight&gt;query&lt;/highlight&gt; in - &lt;highlight&gt;exoplatform&lt;/highlight&gt;, the statement is surrounded - &lt;/fragment&gt; -&lt;/excerpt&gt;</programlisting> - </section> - - <section> - <title>DefaultHTMLExcerpt</title> - - <para>This excerpt provider creates an HTML fragment of the following - form:</para> - - <programlisting>&lt;div&gt; - &lt;span&gt; - &lt;strong&gt;exoplatform&lt;/strong&gt; implements both the mandatory XPath - and optional SQL &lt;strong&gt;query&lt;/strong&gt; syntax. - &lt;/span&gt; - &lt;span&gt; - Before parsing the XPath &lt;strong&gt;query&lt;/strong&gt; in - &lt;strong&gt;exoplatform&lt;/strong&gt;, the statement is surrounded - &lt;/span&gt; -&lt;/div&gt;</programlisting> - </section> - - <section> - <title>How to use it</title> - - <para>If you are using XPath you must use the rep:excerpt() function in - the last location step, just like you would select properties:</para> - - <programlisting>QueryManager qm = session.getWorkspace().getQueryManager(); -Query q = qm.createQuery("//*[jcr:contains(., 'exoplatform')]/(@Title|rep:excerpt(.))", Query.XPATH); -QueryResult result = q.execute(); -for (RowIterator it = result.getRows(); it.hasNext(); ) { - Row r = it.nextRow(); - Value title = r.getValue("Title"); - Value excerpt = r.getValue("rep:excerpt(.)"); -}</programlisting> - - <para>The above code searches for nodes that contain the word - exoplatform and then gets the value of the Title property and an excerpt - for each result node.</para> - - <para>It is also possible to use a relative path in the call - Row.getValue() while the query statement still remains the same. Also - you may use a relative path to a string property. The returned value - will then be an excerpt based on string value of the property.</para> - - <para>Both available excerpt provider will create fragments of about 150 - characters and up to 3 fragments.</para> - - <para>In SQL the function is called excerpt() without the rep prefix, - but the column in the RowIterator will nonetheless be labled - rep:excerpt(.)!</para> - - <programlisting>QueryManager qm = session.getWorkspace().getQueryManager(); -Query q = qm.createQuery("select excerpt(.) from nt:resource where contains(., 'exoplatform')", Query.SQL); -QueryResult result = q.execute(); -for (RowIterator it = result.getRows(); it.hasNext(); ) { - Row r = it.nextRow(); - Value excerpt = r.getValue("rep:excerpt(.)"); -}</programlisting> - </section> - </section> - - <section> - <title>SpellChecker</title> - - <para>The lucene based query handler implementation supports a pluggable - spell checker mechanism. Per default spell checking is not available and - you have to configure it first. See parameter spellCheckerClass on page - <link linkend="JCR.SearchConfiguration">Search Configuration</link> JCR - currently provides an implementation class , which uses the <ulink - url="http://wiki.apache.org/jakarta-lucene/SpellChecker">luc... - contrib . The dictionary is derived from the fulltext indexed content of - the workspace and updated periodically. You can configure the refresh - interval by picking one of the available inner classes of - org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker:</para> - - <itemizedlist> - <listitem> - <para>OneMinuteRefreshInterval</para> - </listitem> - - <listitem> - <para>FiveMinutesRefreshInterval</para> - </listitem> - - <listitem> - <para>ThirtyMinutesRefreshInterval</para> - </listitem> - - <listitem> - <para>OneHourRefreshInterval</para> - </listitem> - - <listitem> - <para>SixHoursRefreshInterval</para> - </listitem> - - <listitem> - <para>TwelveHoursRefreshInterval</para> - </listitem> - - <listitem> - <para>OneDayRefreshInterval</para> - </listitem> - </itemizedlist> - - <para>E.g. if you want a refresh interval of six hours the class name is: - org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$SixHoursRefreshInterval. - If you use - org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker - the refresh interval will be one hour.</para> - - <para>The spell checker dictionary is stored as a lucene index under - <emphasis role="bold">"index-dir"/spellchecker</emphasis>. If it does not - exist, a background thread will create it on startup. Similarly the - dictionary refresh is also done in a background thread to not block - regular queries.</para> - - <section> - <title>How do I use it?</title> - - <para>You can spell check a fulltext statement either with an XPath or a - SQL query:</para> - - <programlisting>// rep:spellcheck('explatform') will always evaluate to true -Query query = qm.createQuery("/jcr:root[rep:spellcheck('explatform')]/(rep:spellcheck())", Query.XPATH); -RowIterator rows = query.execute().getRows(); -// the above query will always return the root node no matter what string we check -Row r = rows.nextRow(); -// get the result of the spell checking -Value v = r.getValue("rep:spellcheck()"); -if (v == null) { - // no suggestion returned, the spelling is correct or the spell checker - // does not know how to correct it. -} else { - String suggestion = v.getString(); -}</programlisting> - - <para>And the same using SQL:</para> - - <programlisting>// SPELLCHECK('exoplatform') will always evaluate to true -Query query = qm.createQuery("SELECT rep:spellcheck() FROM nt:base WHERE jcr:path = '/' AND SPELLCHECK('explatform')", Query.SQL); -RowIterator rows = query.execute().getRows(); -// the above query will always return the root node no matter what string we check -Row r = rows.nextRow(); -// get the result of the spell checking -Value v = r.getValue("rep:spellcheck()"); -if (v == null) { - // no suggestion returned, the spelling is correct or the spell checker - // does not know how to correct it. -} else { - String suggestion = v.getString(); -}</programlisting> - </section> - </section> - - <section> - <title>Similarity (Since 1.12)</title> - - <para>Starting with version, 1.12 JCR allows you to search for nodes that - are similar to an existing node.</para> - - <para>Similarity is determined by looking up terms that are common to - nodes. There are some conditions that must be met for a term to be - considered. This is required to limit the number possibly relevant - terms.</para> - - <itemizedlist> - <listitem> - <para>Only terms with at least 4 characters are considered.</para> - </listitem> - - <listitem> - <para>Only terms that occur at least 2 times in the source node are - considered.</para> - </listitem> - - <listitem> - <para>Only terms that occur in at least 5 nodes are considered.</para> - </listitem> - </itemizedlist> - - <para>Note: The similarity functionality requires that the - supportHightlighting is enabled. Please make sure that you have the - following parameter set for the query handler in your - workspace.xml.</para> - - <programlisting>&lt;param name="support-highlighting" value="true"/&gt;</programlisting> - - <para>The functions are called rep:similar() (in XPath) and similar() (in - SQL) and have two arguments:</para> - - <para>relativePath: a relative path to a descendant node or . for the - current node. absoluteStringPath: a string literal that contains the path - to the node for which to find similar nodes.</para> - - <warning> - <para>Relative path is not supported yet.</para> - </warning> - - <para>Examples:</para> - - <programlisting>//element(*, nt:resource)[rep:similar(., '/parentnode/node.txt/jcr:content')]</programlisting> - - <para>Finds nt:resource nodes, which are similar to node by path - /parentnode/node.txt/jcr:content.</para> - </section> -</chapter> +<?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="JCR.SearchingRepositoryContent"> + <?dbhtml filename="ch-jcr-searching-repository-conten.html"?> + + <title>Searching Repository Content</title> + + <section> + <title>Introduction</title> + + <para>You can find the JCR configuration file here: + .../portal/WEB-INF/conf/jcr/repository-configuration.xml. Please read also + <link linkend="JCR.SearchConfiguration">Search Configuration</link> for + more information about index configuration.</para> + </section> + + <section> + <title>Bi-directional RangeIterator (since 1.9)</title> + + <para>QueryResult.getNodes() will return bi-directional NodeIterator + implementation.</para> + + <note> + <para>Bi-directional NodeIterator is <emphasis role="bold">not + supported</emphasis> in two cases:</para> + + <itemizedlist> + <listitem> + <para>SQL query: select * from nt:base</para> + </listitem> + + <listitem> + <para>XPath query: //* .</para> + </listitem> + </itemizedlist> + + <para>")</para> + </note> + + <para>TwoWayRangeIterator interface:</para> + + <programlisting>/** + * Skip a number of elements in the iterator. + * + * @param skipNum the non-negative number of elements to skip + * @throws java.util.NoSuchElementException if skipped past the first element + * in the iterator. + */ +public void skipBack(long skipNum);</programlisting> + + <para>Usage:</para> + + <programlisting>NodeIterator iter = queryResult.getNodes(); +while (iter.hasNext()) { + if (skipForward) { + iter.skip(10); // Skip 10 nodes in forward direction + } else if (skipBack) { + TwoWayRangeIterator backIter = (TwoWayRangeIterator) iter; + backIter.skipBack(10); // Skip 10 nodes back + } + ....... +}</programlisting> + </section> + + <section> + <title>Fuzzy Searches (since 1.0)</title> + + <para>JCR supports such features as Lucene Fuzzy Searches <ulink + url="http://lucene.apache.org/java/2_3_2/queryparsersyntax.html"... + Lucene - Query Parser Syntax</ulink>.</para> + + <para>To use it you have to form a query like described below:</para> + + <programlisting>QueryManager qman = session.getWorkspace().getQueryManager(); +Query q = qman.createQuery("select * from nt:base where contains(field, 'ccccc~')", Query.SQL); +QueryResult res = q.execute();</programlisting> + </section> + + <section id="JCR.SearchingRepositoryContent.SynonimProvider"> + <title>SynonymSearch (since 1.9)</title> + + <para>Searching with synonyms is integrated in the jcr:contains() function + and uses the same syntax as synonym searches in Google. If a search term + is prefixed by a tilde symbol ( ~ ) also synonyms of the search term are + taken into consideration. Example:</para> + + <programlisting>SQL: select * from nt:resource where contains(., '~parameter') + +XPath: //element(*, nt:resource)[jcr:contains(., '~parameter')</programlisting> + + <para>This feature is disabled per default and you need to add a + configuration parameter to the query-handler element in your jcr + configuration file to enable it.</para> + + <programlisting>&lt;param name="synonymprovider-config-path" value="..you path to configuration file....."/&gt; +&lt;param name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider"/&gt;</programlisting> + + <programlisting>/** + * &lt;code&gt;SynonymProvider&lt;/code&gt; defines an interface for a component that + * returns synonyms for a given term. + */ +public interface SynonymProvider { + + /** + * Initializes the synonym provider and passes the file system resource to + * the synonym provider configuration defined by the configuration value of + * the &lt;code&gt;synonymProviderConfigPath&lt;/code&gt; parameter. The resource may be + * &lt;code&gt;null&lt;/code&gt; if the configuration parameter is not set. + * + * @param fsr the file system resource to the synonym provider + * configuration. + * @throws IOException if an error occurs while initializing the synonym + * provider. + */ + public void initialize(InputStream fsr) throws IOException; + + /** + * Returns an array of terms that are considered synonyms for the given + * &lt;code&gt;term&lt;/code&gt;. + * + * @param term a search term. + * @return an array of synonyms for the given &lt;code&gt;term&lt;/code&gt; or an empty + * array if no synonyms are known. + */ + public String[] getSynonyms(String term); +}</programlisting> + </section> + + <section id="JCR.SearchingRepositoryContent.Highlighting"> + <title>Highlighting (Since 1.9)</title> + + <para>An ExcerptProvider retrieves text excerpts for a node in the query + result and marks up the words in the text that match the query + terms.</para> + + <para>Per default highlighting words that matched the query is disabled + because this feature requires that additional information is written to + the search index. To enable this feature you need to add a configuration + parameter to the query-handler element in your jcr configuration file to + enable it.</para> + + <programlisting>&lt;param name="support-highlighting" value="true"/&gt;</programlisting> + + <para>Additionally there is a parameter that controls the format of the + excerpt created. In JCR 1.9 the default is set to + org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt. + The configuration parameter for this setting is:</para> + + <programlisting>&lt;param name="excerptprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.DefaultXMLExcerpt"/&gt;</programlisting> + + <section> + <title>DefaultXMLExcerpt</title> + + <para>This excerpt provider creates an XML fragment of the following + form:</para> + + <programlisting>&lt;excerpt&gt; + &lt;fragment&gt; + &lt;highlight&gt;exoplatform&lt;/highlight&gt; implements both the mandatory + XPath and optional SQL &lt;highlight&gt;query&lt;/highlight&gt; syntax. + &lt;/fragment&gt; + &lt;fragment&gt; + Before parsing the XPath &lt;highlight&gt;query&lt;/highlight&gt; in + &lt;highlight&gt;exoplatform&lt;/highlight&gt;, the statement is surrounded + &lt;/fragment&gt; +&lt;/excerpt&gt;</programlisting> + </section> + + <section> + <title>DefaultHTMLExcerpt</title> + + <para>This excerpt provider creates an HTML fragment of the following + form:</para> + + <programlisting>&lt;div&gt; + &lt;span&gt; + &lt;strong&gt;exoplatform&lt;/strong&gt; implements both the mandatory XPath + and optional SQL &lt;strong&gt;query&lt;/strong&gt; syntax. + &lt;/span&gt; + &lt;span&gt; + Before parsing the XPath &lt;strong&gt;query&lt;/strong&gt; in + &lt;strong&gt;exoplatform&lt;/strong&gt;, the statement is surrounded + &lt;/span&gt; +&lt;/div&gt;</programlisting> + </section> + + <section> + <title>How to use it</title> + + <para>If you are using XPath you must use the rep:excerpt() function in + the last location step, just like you would select properties:</para> + + <programlisting>QueryManager qm = session.getWorkspace().getQueryManager(); +Query q = qm.createQuery("//*[jcr:contains(., 'exoplatform')]/(@Title|rep:excerpt(.))", Query.XPATH); +QueryResult result = q.execute(); +for (RowIterator it = result.getRows(); it.hasNext(); ) { + Row r = it.nextRow(); + Value title = r.getValue("Title"); + Value excerpt = r.getValue("rep:excerpt(.)"); +}</programlisting> + + <para>The above code searches for nodes that contain the word + exoplatform and then gets the value of the Title property and an excerpt + for each result node.</para> + + <para>It is also possible to use a relative path in the call + Row.getValue() while the query statement still remains the same. Also + you may use a relative path to a string property. The returned value + will then be an excerpt based on string value of the property.</para> + + <para>Both available excerpt provider will create fragments of about 150 + characters and up to 3 fragments.</para> + + <para>In SQL the function is called excerpt() without the rep prefix, + but the column in the RowIterator will nonetheless be labled + rep:excerpt(.)!</para> + + <programlisting>QueryManager qm = session.getWorkspace().getQueryManager(); +Query q = qm.createQuery("select excerpt(.) from nt:resource where contains(., 'exoplatform')", Query.SQL); +QueryResult result = q.execute(); +for (RowIterator it = result.getRows(); it.hasNext(); ) { + Row r = it.nextRow(); + Value excerpt = r.getValue("rep:excerpt(.)"); +}</programlisting> + </section> + </section> + + <section id="JCR.SearchingRepositoryContent.SpellChecker"> + <title>SpellChecker</title> + + <para>The lucene based query handler implementation supports a pluggable + spell checker mechanism. Per default spell checking is not available and + you have to configure it first. See parameter spellCheckerClass on page + <link linkend="JCR.SearchConfiguration">Search Configuration</link> JCR + currently provides an implementation class , which uses the <ulink + url="http://wiki.apache.org/jakarta-lucene/SpellChecker">luc... + contrib . The dictionary is derived from the fulltext indexed content of + the workspace and updated periodically. You can configure the refresh + interval by picking one of the available inner classes of + org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker:</para> + + <itemizedlist> + <listitem> + <para>OneMinuteRefreshInterval</para> + </listitem> + + <listitem> + <para>FiveMinutesRefreshInterval</para> + </listitem> + + <listitem> + <para>ThirtyMinutesRefreshInterval</para> + </listitem> + + <listitem> + <para>OneHourRefreshInterval</para> + </listitem> + + <listitem> + <para>SixHoursRefreshInterval</para> + </listitem> + + <listitem> + <para>TwelveHoursRefreshInterval</para> + </listitem> + + <listitem> + <para>OneDayRefreshInterval</para> + </listitem> + </itemizedlist> + + <para>E.g. if you want a refresh interval of six hours the class name is: + org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$SixHoursRefreshInterval. + If you use + org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker + the refresh interval will be one hour.</para> + + <para>The spell checker dictionary is stored as a lucene index under + <emphasis role="bold">"index-dir"/spellchecker</emphasis>. If it does not + exist, a background thread will create it on startup. Similarly the + dictionary refresh is also done in a background thread to not block + regular queries.</para> + + <section> + <title>How do I use it?</title> + + <para>You can spell check a fulltext statement either with an XPath or a + SQL query:</para> + + <programlisting>// rep:spellcheck('explatform') will always evaluate to true +Query query = qm.createQuery("/jcr:root[rep:spellcheck('explatform')]/(rep:spellcheck())", Query.XPATH); +RowIterator rows = query.execute().getRows(); +// the above query will always return the root node no matter what string we check +Row r = rows.nextRow(); +// get the result of the spell checking +Value v = r.getValue("rep:spellcheck()"); +if (v == null) { + // no suggestion returned, the spelling is correct or the spell checker + // does not know how to correct it. +} else { + String suggestion = v.getString(); +}</programlisting> + + <para>And the same using SQL:</para> + + <programlisting>// SPELLCHECK('exoplatform') will always evaluate to true +Query query = qm.createQuery("SELECT rep:spellcheck() FROM nt:base WHERE jcr:path = '/' AND SPELLCHECK('explatform')", Query.SQL); +RowIterator rows = query.execute().getRows(); +// the above query will always return the root node no matter what string we check +Row r = rows.nextRow(); +// get the result of the spell checking +Value v = r.getValue("rep:spellcheck()"); +if (v == null) { + // no suggestion returned, the spelling is correct or the spell checker + // does not know how to correct it. +} else { + String suggestion = v.getString(); +}</programlisting> + </section> + </section> + + <section id="JCR.SearchingRepositoryContent.Similarity"> + <title>Similarity (Since 1.12)</title> + + <para>Starting with version, 1.12 JCR allows you to search for nodes that + are similar to an existing node.</para> + + <para>Similarity is determined by looking up terms that are common to + nodes. There are some conditions that must be met for a term to be + considered. This is required to limit the number possibly relevant + terms.</para> + + <itemizedlist> + <listitem> + <para>Only terms with at least 4 characters are considered.</para> + </listitem> + + <listitem> + <para>Only terms that occur at least 2 times in the source node are + considered.</para> + </listitem> + + <listitem> + <para>Only terms that occur in at least 5 nodes are considered.</para> + </listitem> + </itemizedlist> + + <para>Note: The similarity functionality requires that the + supportHightlighting is enabled. Please make sure that you have the + following parameter set for the query handler in your + workspace.xml.</para> + + <programlisting>&lt;param name="support-highlighting" value="true"/&gt;</programlisting> + + <para>The functions are called rep:similar() (in XPath) and similar() (in + SQL) and have two arguments:</para> + + <para>relativePath: a relative path to a descendant node or . for the + current node. absoluteStringPath: a string literal that contains the path + to the node for which to find similar nodes.</para> + + <warning> + <para>Relative path is not supported yet.</para> + </warning> + + <para>Examples:</para> + + <programlisting>//element(*, nt:resource)[rep:similar(., '/parentnode/node.txt/jcr:content')]</programlisting> + + <para>Finds nt:resource nodes, which are similar to node by path + /parentnode/node.txt/jcr:content.</para> + </section> +</chapter>