[gatein-commits] gatein SVN: r7744 - in epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US: images/Advanced/Foundations and 4 other directories.

Author: smumford Date: 2011-10-14 01:24:42 -0400 (Fri, 14 Oct 2011) New Revision: 7744 Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-1.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-2.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-3.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-4.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/Advanced/Foundations/ioc.png epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/JNDI_Naming.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Management.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Specific_Services.xml Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/jcr-exo-implementation.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/jcr-namespace-altering.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/nodetype-registration.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/configuration-persister.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/exo-jcr-configuration.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/external-value-storages.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/jdbc-data-container-config.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/multilanguage-support.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/rest-services-on-groovy.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/search-configuration.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/workspace-persistence-storage.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/data-container.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/repository-creation-service.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/transaction-manager-lookup.xml Log: Partial copy-edit of new JCR 1.14 content Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-1.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-1.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-1.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -0,0 +1,69 @@ +<component> + <key>org.exoplatform.services.naming.InitialContextInitializer</key> + <type>org.exoplatform.services.naming.InitialContextInitializer</type> + <component-plugins> + <component-plugin> + <name>bind.datasource</name> + <set-method>addPlugin</set-method> + <type>org.exoplatform.services.naming.BindReferencePlugin</type> + <init-params> + <value-param> + <name>bind-name</name> + <value>jdbcjcr</value> + </value-param> + <value-param> + <name>class-name</name> + <value>javax.sql.DataSource</value> + </value-param> + <value-param> + <name>factory</name> + <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> + </value-param> + <properties-param> + <name>ref-addresses</name> + <description>ref-addresses</description> + <property name="driverClassName" value="org.hsqldb.jdbcDriver"/> + <property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/> + <property name="username" value="sa"/> + <property name="password" value=""/> + </properties-param> + </init-params> + </component-plugin> + <component-plugin> + <name>bind.datasource</name> + <set-method>addPlugin</set-method> + <type>org.exoplatform.services.naming.BindReferencePlugin</type> + <init-params> + <value-param> + <name>bind-name</name> + <value>jdbcjcr1</value> + </value-param> + <value-param> + <name>class-name</name> + <value>javax.sql.DataSource</value> + </value-param> + <value-param> + <name>factory</name> + <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> + </value-param> + <properties-param> + <name>ref-addresses</name> + <description>ref-addresses</description> + <property name="driverClassName" value="com.mysql.jdbc.Driver"/> + <property name="url" value="jdbc:mysql://exoua.dnsalias.net/jcr"/> + <property name="username" value="exoadmin"/> + <property name="password" value="exo12321"/> + <property name="maxActive" value="50"/> + <property name="maxIdle" value="5"/> + <property name="initialSize" value="5"/> + </properties-param> + </init-params> + </component-plugin> + <component-plugins> + <init-params> + <value-param> + <name>default-context-factory</name> + <value>org.exoplatform.services.naming.SimpleContextFactory</value> + </value-param> + </init-params> + </component> \ No newline at end of file Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-2.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-2.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-2.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -0,0 +1,62 @@ +<workspaces> + <workspace name="ws" auto-init-root-nodetype="nt:unstructured"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="source-name" value="jdbcjcr"/> + <property name="dialect" value="hsqldb"/> + <property name="multi-db" value="true"/> + <property name="max-buffer-size" value="200K"/> + <property name="swap-directory" value="target/temp/swap/ws"/> + </properties> + </container> + <cache enabled="true"> + <properties> + <property name="max-size" value="10K"/><!-- 10Kbytes --> + <property name="live-time" value="30m"/><!-- 30 min --> + </properties> + </cache> + <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <properties> + <property name="index-dir" value="target/temp/index"/> + </properties> + </query-handler> + <lock-manager> + <time-out>15m</time-out><!-- 15 min --> + <persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"> + <properties> + <property name="path" value="target/temp/lock/ws"/> + </properties> + </persister> + </lock-manager> + </workspace> + <workspace name="ws1" auto-init-root-nodetype="nt:unstructured"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="source-name" value="jdbcjcr1"/> + <property name="dialect" value="mysql"/> + <property name="multi-db" value="true"/> + <property name="max-buffer-size" value="200K"/> + <property name="swap-directory" value="target/temp/swap/ws1"/> + </properties> + </container> + <cache enabled="true"> + <properties> + <property name="max-size" value="10K"/> + <property name="live-time" value="5m"/> + </properties> + </cache> + <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <properties> + <property name="index-dir" value="target/temp/index"/> + </properties> + </query-handler> + <lock-manager> + <time-out>15m</time-out><!-- 15 min --> + <persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"> + <properties> + <property name="path" value="target/temp/lock/ws1"/> + </properties> + </persister> + </lock-manager> + </workspace> +</workspaces> \ No newline at end of file Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-3.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-3.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-3.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -0,0 +1,33 @@ +<external-component-plugins> + <target-component>org.exoplatform.services.naming.InitialContextInitializer</target-component> + <component-plugin> + <name>bind.datasource</name> + <set-method>addPlugin</set-method> + <type>org.exoplatform.services.naming.BindReferencePlugin</type> + <init-params> + <value-param> + <name>bind-name</name> + <value>jdbcjcr</value> + </value-param> + <value-param> + <name>class-name</name> + <value>javax.sql.DataSource</value> + </value-param> + <value-param> + <name>factory</name> + <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> + </value-param> + <properties-param> + <name>ref-addresses</name> + <description>ref-addresses</description> + <property name="driverClassName" value="org.postgresql.Driver"/> + <property name="url" value="jdbc:postgresql://exoua.dnsalias.net/portal"/> + <property name="username" value="exoadmin"/> + <property name="password" value="exo12321"/> + <property name="maxActive" value="50"/> + <property name="maxIdle" value="5"/> + <property name="initialSize" value="5"/> + </properties-param> + </init-params> + </component-plugin> + </external-component-plugins> \ No newline at end of file Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-4.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-4.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/example-4.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -0,0 +1,57 @@ +<workspaces> + <workspace name="ws" auto-init-root-nodetype="nt:unstructured"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="source-name" value="jdbcjcr"/> + <property name="dialect" value="pgsql"/> + <property name="multi-db" value="false"/> + <property name="max-buffer-size" value="200K"/> + <property name="swap-directory" value="target/temp/swap/ws"/> + </properties> + </container> + <cache enabled="true"> + <properties> + <property name="max-size" value="10K"/> + <property name="live-time" value="30m"/> + </properties> + </cache> + <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <properties> + <property name="index-dir" value="../temp/index"/> + </properties> + </query-handler> + <lock-manager> + <time-out>15m</time-out> + <persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"> + <properties> + <property name="path" value="target/temp/lock/ws"/> + </properties> + </persister> + </lock-manager> + </workspace> + <workspace name="ws1" auto-init-root-nodetype="nt:unstructured"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="source-name" value="jdbcjcr"/> + <property name="dialect" value="pgsql"/> + <property name="multi-db" value="false"/> + <property name="max-buffer-size" value="200K"/> + <property name="swap-directory" value="target/temp/swap/ws1"/> + </properties> + </container> + <cache enabled="true"> + <properties> + <property name="max-size" value="10K"/> + <property name="live-time" value="5m"/> + </properties> + </cache> + <lock-manager> + <time-out>15m</time-out> + <persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"> + <properties> + <property name="path" value="target/temp/lock/ws1"/> + </properties> + </persister> + </lock-manager> + </workspace> +</workspaces> \ No newline at end of file Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/Advanced/Foundations/ioc.png =================================================================== (Binary files differ) Property changes on: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/Advanced/Foundations/ioc.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/JNDI_Naming.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/JNDI_Naming.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/JNDI_Naming.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -0,0 +1,287 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-Reference_Guide-JNDI_naming"> + <title>JNDI naming</title> + <section id="sect-Reference_Guide-JNDI_naming-Prerequisites"> + <title>Prerequisites</title> + <para> + We need to configure JNDI environment properties and Reference binding with the eXo container standard mechanism. + </para> + <para> + The Naming service covers: + </para> + <para> + <itemizedlist> + <listitem> + <para> + Configuring the current Naming Context Factory implemented as an ExoContainer Component <envar>org.exoplatform.services.naming.InitialContextInitializer</envar>. + </para> + + </listitem> + <listitem> + <para> + Binding Objects (References) to the current Context using <envar>org.exoplatform.services.naming.BindReferencePlugin</envar> component plugin. + </para> + + </listitem> + + </itemizedlist> + </para> + + </section> + + <section id="sect-Reference_Guide-JNDI_naming-How_it_works"> + <title>How it works</title> + <para> + Make sure you understand the <ulink url="http://java.sun.com/products/jndi/1.2/javadoc/index.html"&... Naming and Directory InterfaceTM (JNDI)</ulink> concepts before using this service. + </para> + <section id="sect-Reference_Guide-How_it_works-JNDI_System_property_initialization"> + <title>JNDI System property initialization</title> + <para> + After the start time the Context Initializer (org.exoplatform.services.naming.InitialContextInitializer) traverses all initial parameters (that concern the Naming Context) configured in <envar>default-properties</envar> and <envar>mandatory-properties</envar> (see Configuration examples) and: + </para> + <itemizedlist> + <listitem> + <para> + For <envar>default-properties</envar>: Check if this property is already set as a System property (<envar>System.getProperty(name)</envar>) and set this property if it's not found. Using those properties is recommended with a third party Naming service provider. + </para> + + </listitem> + <listitem> + <para> + For <envar>mandatory-properties</envar>: Set the property without checking. + </para> + + </listitem> + + </itemizedlist> + <para> + Standard JNDI properties: + </para> + <itemizedlist> + <listitem> + <para> + <envar>java.naming.factory.initial</envar> + </para> + + </listitem> + <listitem> + <para> + <envar>java.naming.provider.url</envar> + </para> + + </listitem> + + </itemizedlist> + <para> + and others (see JNDI docs) + </para> + + </section> + + <section id="sect-Reference_Guide-How_it_works-JNDI_reference_binding"> + <title>JNDI reference binding</title> + <para> + Another responsibility of Context Initializer <envar>org.exoplatform.services.naming.InitialContextInitializer</envar> is binding of preconfigured references to the naming context. For this purpose, it uses a standard eXo component plugin mechanism and in particular the <envar>org.exoplatform.services.naming.BindReferencePlugin</envar> component plugin. The configuration of this plugin includes three mandatory value parameters: + </para> + <itemizedlist> + <listitem> + <para> + <envar>bind-name</envar>: the name of binding reference. + </para> + + </listitem> + <listitem> + <para> + <envar>class-name</envar>: the type of binding reference. + </para> + + </listitem> + <listitem> + <para> + <envar>factory</envar>: the object factory type. + </para> + + </listitem> + + </itemizedlist> + <para> + And also <envar>ref-addresses</envar> property parameter with a set of references' properties. (see Configuration examples) Context Initializer uses those parameters to bind the necessary reference automatically. + </para> + + </section> + + + </section> + + <section id="sect-Reference_Guide-JNDI_naming-Configuration_examples"> + <title>Configuration examples</title> + <para> + The <envar>InitialContextInitializer</envar> configuration example: + </para> + +<programlisting language="XML" role="XML"> &lt;component&gt; + &lt;type&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt;. + &lt;name&gt;bindings-store-path&lt;/name&gt;. + &lt;value&gt;bind-references.xml&lt;/value&gt;. + &lt;/value-param&gt;. + &lt;value-param&gt; + &lt;name&gt;overload-context-factory&lt;/name&gt; + &lt;value&gt;true&lt;/value&gt; + &lt;/value-param&gt; + &lt;properties-param&gt; + &lt;name&gt;default-properties&lt;/name&gt; + &lt;description&gt;Default initial context properties&lt;/description&gt; + &lt;property name="java.naming.factory.initial" value="org.exoplatform.services.naming.SimpleContextFactory"/&gt; + &lt;/properties-param&gt; + &lt;properties-param&gt; + &lt;name&gt;mandatory-properties&lt;/name&gt; + &lt;description&gt;Mandatory initial context properties&lt;/description&gt; + &lt;property name="java.naming.provider.url" value="rmi://localhost:9999"/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component&gt;</programlisting> + <para> + where + </para> + <para> + <emphasis role="bold">binding-store-path</emphasis> is file path which stores binded datasources in runtime + </para> + <para> + <emphasis role="bold">overload-context-factory</emphasis> allows to overload the default initial context factory by a context factory that is ExoContainer aware and that is able to delegate to the original initial context factory if it detects that it is not in the eXo scope. By default the feature is disabled since it is only required on AS that don't share the objects by default like tomcat but unlike JBoss AS + </para> + <para> + The <envar>BindReferencePlugin</envar> component plugin configuration example (for JDBC datasource): + </para> + +<programlisting language="XML" role="XML"> &lt;component-plugins&gt; + &lt;component-plugin&gt; + &lt;name&gt;bind.datasource&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;bind-name&lt;/name&gt; + &lt;value&gt;jdbcjcr&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;class-name&lt;/name&gt; + &lt;value&gt;javax.sql.DataSource&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;factory&lt;/name&gt; + &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt; + &lt;/value-param&gt; + &lt;properties-param&gt; + &lt;name&gt;ref-addresses&lt;/name&gt; + &lt;description&gt;ref-addresses&lt;/description&gt; + &lt;property name="driverClassName" value="org.hsqldb.jdbcDriver"/&gt; + &lt;property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/&gt; + &lt;property name="username" value="sa"/&gt; + &lt;property name="password" value=""/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt;</programlisting> + + </section> + + <section id="sect-Reference_Guide-JNDI_naming-Recommendations_for_Application_Developers"> + <title>Recommendations for Application Developers</title> + <para> + <itemizedlist> + <listitem> + <para> + <envar>SimpleContextFactory</envar> is created for testing purposes only, do not use it for production. + </para> + + </listitem> + <listitem> + <para> + In J2EE environment use Naming Factory objects provided with the Application Server. + </para> + + </listitem> + + </itemizedlist> + </para> + + </section> + + <section id="sect-Reference_Guide-JNDI_naming-InitialContextInitializer_API"> + <title>InitialContextInitializer API</title> + <para> + <envar>InitialContextInitalizer</envar> also provides feature of references binding in runtime. References have bind in runtime will be persisted and automatically rebinded on a next system start. + </para> + <para> + Service provides methods for binding reference. + </para> + +<programlisting language="Java" role="Java"> + public void bind(String bindName, + String className, + String factory, + String factoryLocation, + Map&lt;String, String&gt; refAddr) + throws NamingException, FileNotFoundException, XMLStreamException;</programlisting> + <itemizedlist> + <listitem> + <para> + <envar>bindName</envar>: name of binding. + </para> + + </listitem> + <listitem> + <para> + <envar>className</envar>: the fully-qualified name of the class of the object to which this Reference refers. + </para> + + </listitem> + <listitem> + <para> + <envar>factory</envar>: the name of the factory class for creating an instance of the object to which this Reference refers. + </para> + + </listitem> + <listitem> + <para> + <envar>factoryLocation</envar>: the location of the factory class. + </para> + + </listitem> + <listitem> + <para> + <envar>refAddr</envar>: object's properties map. + </para> + + </listitem> + + </itemizedlist> + <para> + Example of usage: + </para> + +<programlisting language="Java" role="Java"> + // obtain InitialContextInitializer instance from ExoContainer (e.g. PortalContainer) + InitialContextInitializer initContext = (InitialContextInitializer)container.getComponentInstanceOfType(InitialContextInitializer.class); + + Map&lt;String, String&gt; refAddr = new HashMap&lt;String, String&gt;(); + refAddr.put("driverClassName", "oracle.jdbc.OracleDriver"); + refAddr.put("url", "jdbc:oracle:thin:@oraclehost:1521:orcl"); + refAddr.put("username", "exouser"); + refAddr.put("password", "exopassword"); + + initContext.bind("jdbcexco", "javax.sql.DataSource", "org.apache.commons.dbcp.BasicDataSourceFactory", null, refAddr); + + // try to get just bound DataSource + DataSource ds = (DataSource)new InitialContext().lookup("jdbcexo");</programlisting> + + </section> + +</section> + + Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Management.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Management.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Management.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -0,0 +1,203 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-Reference_Guide-Manageability"> + <title>Manageability</title> + <section id="sect-Reference_Guide-Manageability-Introduction"> + <title>Introduction</title> + <para> + The kernel has a framework for exposing a management view of the various sub systems of the platform. The management view is a lose term for defining how we can access relevant information about the system and how we can apply management operations. JMX is the de facto standard for exposing a management view in the Java Platform but we take in consideration other kind of views such as REST web services. Therefore, the framework is not tied to JMX, yet it provides a JMX part to define more precisely details related to the JMX management view. The legacy framework is still in use but is deprecated in favor of the new framework as it is less tested and less efficient. It will be removed by sanitization in the future. + </para> + + </section> + + <section id="sect-Reference_Guide-Manageability-Managed_framework_API"> + <title>Managed framework API</title> + <para> + The managed frameworks defines an API for exposing a management view of objects. The API is targeted for internal use and is not a public API. The framework leverages Java 5 annotations to describe the management view from an object. + </para> + <section id="sect-Reference_Guide-Managed_framework_API-Annotations"> + <title>Annotations</title> + <section id="sect-Reference_Guide-Annotations-org.exoplatform.management.annotations.Managed_annotation"> + <title&gt;(a)org.exoplatform.management.annotations.Managed annotation</title> + <para> + The @Managed annotates elements that wants to expose a management view to a management layer. + </para> + <para> + <emphasis role="bold">@Managed for objects</emphasis> + </para> + <para> + The framework will export a management view for the objects annotated. + </para> + <para> + <emphasis role="bold">@Managed for getter/setter</emphasis> + </para> + <para> + Defines a managed property. An annotated getter defines a read property, an annotated setter defines a write property and if matching getter/setter are annotated it defines a read/write property. + </para> + <para> + <emphasis role="bold">@Managed on method</emphasis> + </para> + <para> + Defines a managed operation. + </para> + + </section> + + <section id="sect-Reference_Guide-Annotations-org.exoplatform.management.annotations.ManagedDescription"> + <title&gt;(a)org.exoplatform.management.annotations.ManagedDescription&lt;/title&gt; + <para> + The @ManagedDescription annotation provides a description of a managed element. It is valid to annotated object or methods. It takes as sole argument a string that is the description value. + </para> + + </section> + + <section id="sect-Reference_Guide-Annotations-org.exoplatform.management.annotations.ManagedName"> + <title&gt;(a)org.exoplatform.management.annotations.ManagedName&lt;/title&gt; + <para> + The @ManagedName annotation provides an alternative name for managed properties. It is used to accomodate legacy methods of an object that can be renamed for compatibility reasons. It takes as sole argument a string that is the name value. + </para> + + </section> + + <section id="sect-Reference_Guide-Annotations-org.exoplatform.management.annotations.ManagedBy"> + <title&gt;(a)org.exoplatform.management.annotations.ManagedBy&lt;/title&gt; + <para> + The @ManagedBy annotation defines a delegate class for exposing a management view. The sole argument of the annotation are class literals. The delegate class must provide a constructor with the managed object as argument. + </para> + + </section> + + + </section> + + + </section> + + <section id="sect-Reference_Guide-Manageability-JMX_Management_View"> + <title>JMX Management View</title> + <section id="sect-Reference_Guide-JMX_Management_View-JMX_Annotations"> + <title>JMX Annotations</title> + <section id="sect-Reference_Guide-JMX_Annotations-org.exoplatform.management.jmx.annotations.Property_annotation"> + <title&gt;(a)org.exoplatform.management.jmx.annotations.Property annotation</title> + <para> + The @Property annotation is used to within other annotations such as @NameTemplate or @NamingContext. It should be seen as a structural way for a list of properties. A property is made of a key and a value. The value can either be a string literal or it can be surrounded by curly brace to be a dynamic property. A dynamic property is resolved against the instance of the object at runtime. + </para> + + </section> + + <section id="sect-Reference_Guide-JMX_Annotations-org.exoplatform.management.jmx.annotations.NameTemplate_annotation"> + <title&gt;(a)org.exoplatform.management.jmx.annotations.NameTemplate annotation</title> + <para> + The @NameTemplate defines a template that is used at registration time of a managed object to create the JMX object name. The template is formed of properties. + </para> + +<programlisting language="Java" role="Java">@NameTemplate({ + @Property(key="container", value="workspace"), + @Property(key="name", value="{Name}")})</programlisting> + + </section> + + <section id="sect-Reference_Guide-JMX_Annotations-org.exoplatform.management.jmx.annotations.NamingContext_annotation"> + <title&gt;(a)org.exoplatform.management.jmx.annotations.NamingContext annotation</title> + <para> + The @NamingContext annotations defines a set of properties which are used within a management context. It allows to propagate properties down to managed objects which are defined by an object implementing the ManagementAware interface. The goal is to scope different instances of the same class that would have the same object name otherwise. + </para> + +<programlisting language="Java" role="Java">@NamingContext(@Property(key="workspace", value="{Name}"))</programlisting> + + </section> + + + </section> + + + </section> + + <section id="sect-Reference_Guide-Manageability-Example"> + <title>Example</title> + <section id="sect-Reference_Guide-Example-CacheService_example"> + <title>CacheService example</title> + <para> + The cache service delegates most of the work to the CacheServiceManaged class by using the @ManagedBy annotation. At runtime when a new cache is created, it calls the CacheServiceManaged class in order to let the CacheServiceManaged object register the cache. + </para> + +<programlisting language="Java" role=&quot;Java&quot;&gt;(a)ManagedBy(CacheServiceManaged.class) +public class CacheServiceImpl implements CacheService { + + CacheServiceManaged managed; + ... + synchronized private ExoCache createCacheInstance(String region) throws Exception { + ... + if (managed != null) { + managed.registerCache(simple); + } + ... + } +}</programlisting> + <para> + The ExoCache interface is annotated to define its management view. The @NameTemplate is used to produce object name values when ExoCache instance are registered. + </para> + +<programlisting language="Java" role="Java">@Managed +@NameTemplate({@Property(key="service", value="cache"), @Property(key="name", value="{Name}")}) +@ManagedDescription("Exo Cache") +public interface ExoCache { + + @Managed + @ManagedName("Name") + @ManagedDescription("The cache name") + public String getName(); + + @Managed + @ManagedName("Capacity") + @ManagedDescription("The maximum capacity") + public int getMaxSize(); + + @Managed + @ManagedDescription("Evict all entries of the cache") + public void clearCache() throws Exception; + + ... +}</programlisting> + <para> + The CacheServiceManaged is the glue code between the CacheService and the management view. The main reason is that only exo services are registered automatically against the management view. Any other managed bean must be registered manually for now. Therefore, it needs to know about the management layer via the management context. The management context allows an object implementing the ManagementAware interface to receive a context to perform further registration of managed objects. + </para> + +<programlisting language="Java" role="Java">@Managed +public class CacheServiceManaged implements ManagementAware { + + /** . */ + private ManagementContext context; + + /** . */ + private CacheServiceImpl cacheService; + + public CacheServiceManaged(CacheServiceImpl cacheService) { + this.cacheService = cacheService; + + // + cacheService.managed = this; + } + + public void setContext(ManagementContext context) { + this.context = context; + } + + void registerCache(ExoCache cache) { + if (context != null) { + context.register(cache); + } + } +}</programlisting> + + </section> + + + </section> + +</section> + + Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Specific_Services.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Specific_Services.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Specific_Services.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -0,0 +1,858 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> +%BOOK_ENTITIES; +]> +<section> + <title>Specific Services</title> + <section id="sect-Reference_Guide-ListenerService"> + <title>ListenerService</title> + <section id="sect-Reference_Guide-ListenerService-Asynchronous_Event_Broadcast"> + <title>Asynchronous Event Broadcast</title> + <para> + Basicaly, ListenerService used to store Listeners and broadcast events to them. + </para> + <para> + ListenerService event broadcasting works in next way - it takes a destination listeners and executes event on those listeners. + </para> + <para> + But, some events may take a lot of time, so idea to make event processing asynchronous is useful. + </para> + <blockquote> + <para> + What do I need to make my listener asynchronous? + </para> + + </blockquote> + <para> + - It's very simple, just mark your Listener implementation as <classname>@Asynchronous</classname>. + </para> + +<programlisting language="Java" role="Java">@Asynchronous +class AsynchListenerWithException&lt;S,D&gt; extends Listener&lt;S,D&gt; +{ + @Override + public void onEvent(Event&lt;S,D&gt; event) throws Exception + { + // some expensive operation + } +}</programlisting> + <para> + Now, our AsynchListener will be executed in separate thread by <classname>ExecutorService</classname>. + </para> + <para> + By default, <classname>ExecutoreService</classname> configured with thread pool size 1, you can change it in configuration: + </para> + +<programlisting language="XML" role="XML"> &lt;component&gt; + &lt;key&gt;org.exoplatform.services.listener.ListenerService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.listener.ListenerService&lt;/type&gt; + + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;asynchPoolSize&lt;/name&gt; + &lt;value&gt;5&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; + + &lt;/component&gt;</programlisting> + + </section> + +</section> + + <section id="sect-Reference_Guide-Understanding_the_ListenerService"> + <title>Understanding the ListenerService</title> + + <section id="sect-Reference_Guide-Understanding_the_ListenerService-Objectives"> + <title>Objectives</title> + <para> + This article will first describe how the ListenerService works and then it will show you how to configure the ListenerService. + </para> + + </section> + + <section id="sect-Reference_Guide-Understanding_the_ListenerService-What_is_the_ListenerService_"> + <title>What is the ListenerService ?</title> + <para> + Inside eXo, an event mechanism allows to trigger and listen to events under specific conditions. This mechanism is used in several places in eXo such as login/logout time. + </para> + + </section> + + <section id="sect-Reference_Guide-Understanding_the_ListenerService-How_does_it_work"> + <title>How does it work?</title> + <para> + Listeners must be subclasses of org.exoplatform.services.listener.Listener registered by the ListenerService. + </para> + <section id="sect-Reference_Guide-How_does_it_work-Registering_a_listener"> + <title>Registering a listener</title> + <para> + To register a listener, you need to call the addListener() method. + </para> + +<programlisting language="Java" role="Java">/** + * This method is used to register a listener with the service. The method + * should: 1. Check to see if there is a list of listener with the listener + * name, create one if the listener list doesn't exit 2. Add the new listener + * to the listener list + * + * @param listener +*/ +public void addListener(Listener listener) { + ... +}</programlisting> + <para> + By convention, we use the listener name as the name of the event to listen to. + </para> + + </section> + + <section id="sect-Reference_Guide-How_does_it_work-Triggering_an_event"> + <title>Triggering an event</title> + <para> + To trigger an event, an application can call one of the broadcast() methods of ListenerService. + </para> + +<programlisting language="Java" role="Java">/** + * This method is used to broadcast an event. This method should: 1. Check if + * there is a list of listener that listen to the event name. 2. If there is a + * list of listener, create the event object with the given name , source and + * data 3. For each listener in the listener list, invoke the method + * onEvent(Event) + * + * @param &lt;S&gt; The type of the source that broadcast the event + * @param &lt;D&gt; The type of the data that the source object is working on + * @param name The name of the event + * @param source The source object instance + * @param data The data object instance + * @throws Exception + */ +public &lt;S, D&gt; void broadcast(String name, S source, D data) throws Exception { + ... +} + +/** + * This method is used when a developer want to implement his own event object + * and broadcast the event. The method should: 1. Check if there is a list of + * listener that listen to the event name. 2. If there is a list of the + * listener, For each listener in the listener list, invoke the method + * onEvent(Event) + * + * @param &lt;T&gt; The type of the event object, the type of the event object has + * to be extended from the Event type + * @param event The event instance + * @throws Exception + */ +public &lt;T extends Event&gt; void broadcast(T event) throws Exception { + ... +}</programlisting> + <para> + The boadcast() methods retrieve the name of the event and find the registered listeners with the same name and call the method onEvent() on each listener found. + </para> + <para> + Each listener is a class that extends org.exoplatform.services.listener.Listener, as you can see below: + </para> + +<programlisting language="Java" role="Java">public abstract class Listener&lt;S, D&gt; extends BaseComponentPlugin { + + /** + * This method should be invoked when an event with the same name is + * broadcasted + */ + public abstract void onEvent(Event&lt;S, D&gt; event) throws Exception; +}</programlisting> + <warning> + <para> + As you can see we use generics to limit the source of the event to the type 'S' and the data of the event to the type 'D', so we expect that listeners implement the method onEvent() with the corresponding types + </para> + + </warning> + <para> + Each listener is also a ComponentPlugin with a name and a description, in other words, the name of the listener will be the name given in the configuration file, for more details see the next section. + </para> + +<programlisting language="Java" role="Java">public interface ComponentPlugin { + public String getName(); + + public void setName(String name); + + public String getDescription(); + + public void setDescription(String description); +}</programlisting> + + </section> + + + </section> + + <section id="sect-Reference_Guide-Understanding_the_ListenerService-How_to_configure_a_listener"> + <title>How to configure a listener?</title> + <para> + All listeners are in fact a ComponentPlugin so it must be configured as below: + </para> + +<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt; +&lt;configuration&gt; +... + &lt;external-component-plugins&gt; + &lt;!-- The full qualified name of the ListenerService --&gt; + &lt;target-component&gt;org.exoplatform.services.listener.ListenerService&lt;/target-component&gt; + + &lt;component-plugin&gt; + &lt;!-- The name of the listener that is also the name of the target event --&gt; + &lt;name&gt;${name-of-the-target-event}&lt;/name&gt; + &lt;!-- The name of the method to call on the ListenerService in order to register the Listener --&gt; + &lt;set-method&gt;addListener&lt;/set-method&gt; + &lt;!-- The full qualified name of the Listener --&gt; + &lt;type&gt;${the-FQN-of-the-listener}&lt;/type&gt; + &lt;/component-plugin&gt; + + &lt;/external-component-plugins&gt; +&lt;/configuration&gt;</programlisting> + + </section> + + <section id="sect-Reference_Guide-Understanding_the_ListenerService-Concrete_Example"> + <title>Concrete Example</title> + <para> + The org.exoplatform.services.security.ConversationRegistry uses the ListenerService to notify that a user has just signed in or just left the application. For example, when a new user signs in, the following code is called: + </para> + +<programlisting language="Java" role="Java">listenerService.broadcast("exo.core.security.ConversationRegistry.register", this, state);</programlisting> + <para> + This code will in fact create a new Event which name is "exo.core.security.ConversationRegistry.register", which source is the current instance of ConversationRegistry and which data is the given state. The ListenerService will call the method onEvent(Event&lt;ConversationRegistry, ConversationState&gt; event) on all the listeners which name is "exo.core.security.ConversationRegistry.register". + </para> + <para> + In the example below, we define a Listener that will listen the event "exo.core.security.ConversationRegistry.register". + </para> + +<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt; +&lt;configuration&gt; +... + &lt;external-component-plugins&gt; + &lt;!-- The full qualified name of the ListenerService --&gt; + &lt;target-component&gt;org.exoplatform.services.listener.ListenerService&lt;/target-component&gt; + + &lt;component-plugin&gt; + &lt;!-- The name of the listener that is also the name of the target event --&gt; + &lt;name&gt;exo.core.security.ConversationRegistry.register&lt;/name&gt; + &lt;!-- The name of the method to call on the ListenerService in order to register the Listener --&gt; + &lt;set-method&gt;addListener&lt;/set-method&gt; + &lt;!-- The full qualified name of the Listener --&gt; + &lt;type&gt;org.exoplatform.forum.service.AuthenticationLoginListener&lt;/type&gt; + &lt;/component-plugin&gt; + + &lt;/external-component-plugins&gt; +&lt;/configuration&gt; +...</programlisting> + + </section> + +</section> + +<section id="sect-Reference_Guide-Job_Schedule"> + <!-- This document was created with Syntext Serna Free. --> <title>Job Schedule</title> + <section id="sect-Reference_Guide-Job_Schedule-What_is_Job_Scheduler"> + <title>What is Job Scheduler?</title> + <para> + <emphasis role="bold">Job scheduler</emphasis> defines a job to execute a given number of times during a given period. It is a service that is in charge of unattended background executions, commonly known for historical reasons as batch processing. It is used to create and run jobs automatically and continuously, to schedule event-driven jobs and reports. + </para> + + </section> + + <section id="sect-Reference_Guide-Job_Schedule-Where_is_Job_Scheduler_Service_used_in_eXo_Products"> + <title>Where is Job Scheduler Service used in eXo Products?</title> + <para> + Job Scheduler Service is widely used in many eXo products such as Social, DMS, WCM, eXo Knowledge and eXo Collaboration. + </para> + <para> + In eXo products, Job Schedulers are used to do some tasks as below: + </para> + <itemizedlist> + <listitem> + <para> + Automatically send notification, such as task/event reminder in the Calendar application of eXo Collaboration. + </para> + + </listitem> + <listitem> + <para> + Automatically save chat messages from Openfire Server to History in the Chat application of eXo Collaboration. + </para> + + </listitem> + <listitem> + <para> + Inactivate topics in the Forum application of eXo Knowledge. + </para> + + </listitem> + <listitem> + <para> + Calculate the number of active and online users in the Forum application of eXo Knowledge. + </para> + + </listitem> + <listitem> + <para> + Automatically collect RSS items from various RSS resources to post to the activity stream of users and spaces in eXo Social. + </para> + + </listitem> + <listitem> + <para> + Automatically send Newsletters to users in WCM. + </para> + + </listitem> + + </itemizedlist> + <para> + Also, it is used in Schedule lifecycle in DMS. + </para> + <para> + By using Job Scheduler Service in eXo kernel, many kinds of job can be configured to run, such as, addPeriodJob, addCronJob, addGlobalJobListener, addJobListener and many more. Just write a job (a class implements Job interface of quartz library and configures plug-in for JobSchedulerService and you're done. + </para> + + </section> + + <section id="sect-Reference_Guide-Job_Schedule-How_does_Job_Scheduler_work"> + <title>How does Job Scheduler work?</title> + <para> + Jobs are scheduled to run when a given Trigger occurs. Triggers can be created with nearly any combination of the following directives: + </para> + <itemizedlist> + <listitem> + <para> + at a certain time of day (to the millisecond) + </para> + + </listitem> + <listitem> + <para> + on certain days of the week + </para> + + </listitem> + + </itemizedlist> + <itemizedlist> + <listitem> + <para> + on certain days of the month + </para> + + </listitem> + <listitem> + <para> + on certain days of the year + </para> + + </listitem> + + </itemizedlist> + <itemizedlist> + <listitem> + <para> + not on certain days listed within a registered Calendar (such as business holidays) + </para> + + </listitem> + + </itemizedlist> + <itemizedlist> + <listitem> + <para> + repeated a specific number of times + </para> + + </listitem> + + </itemizedlist> + <itemizedlist> + <listitem> + <para> + repeated until a specific time/date + </para> + + </listitem> + <listitem> + <para> + repeated indefinitely + </para> + + </listitem> + + </itemizedlist> + <itemizedlist> + <listitem> + <para> + repeated with a delay interval + </para> + + </listitem> + + </itemizedlist> + <para> + Jobs are given names by their creator and can also be organized into named groups. Triggers may also be given names and placed into groups, in order to easily organize them within the scheduler. Jobs can be added to the scheduler once, but registered with multiple Triggers. Within a J2EE environment, Jobs can perform their work as part of a distributed (XA) transaction. + </para> + <para> + (Source: quartz-scheduler.org) + </para> + <section id="sect-Reference_Guide-How_does_Job_Scheduler_work-How_can_Job_Scheduler_Service_be_used_in_Kernel"> + <title>How can Job Scheduler Service be used in Kernel?</title> + <para> + Kernel leverages <ulink url="http://www.quartz-scheduler.org">Quartz</ulink> for its scheduler service and wraps <classname>org.quartz.Scheduler</classname> in <classname>org.exoplatform.services.scheduler.impl.QuartzSheduler</classname> for easier service wiring and configuration like any other services. To work with Quartz in Kernel, you will mostly work with <classname>org.exoplatform.services.scheduler.JobSchedulerService</classname> (implemented by <classname>org.exoplatform.services.scheduler.impl.JobSchedulerServiceImpl</classname>. + </para> + <para> + To use <classname>JobSchedulerService</classname>, you can configure it as a component in the configuration.xml. Because <classname>JobSchedulerService</classname> requires <classname>QuartzSheduler</classname> and <classname>QueueTasks</classname>, you also have to configure these two components. + </para> + +<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;configuration + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"&gt; + + &lt;component&gt; + &lt;type&gt;org.exoplatform.services.scheduler.impl.QuartzSheduler&lt;/type&gt; + &lt;/component&gt; + + &lt;component&gt; + &lt;type&gt;org.exoplatform.services.scheduler.QueueTasks&lt;/type&gt; + &lt;/component&gt; + + &lt;component&gt; + &lt;key&gt;org.exoplatform.services.scheduler.JobSchedulerService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.scheduler.impl.JobSchedulerServiceImpl&lt;/type&gt; + &lt;/component&gt; + +&lt;/configuration&gt;</programlisting> + + </section> + + <section id="sect-Reference_Guide-How_does_Job_Scheduler_work-Samples"> + <title>Samples</title> + <note> + <para> + You can download the project code from <ulink url="https://github.com/hoatle/job-scheduler-service-tutorial"&... + </para> + + </note> + <para> + Work with <classname>JobSchedulerService</classname> by creating a sample project and use GateIn-3.1.0-GA for testing. + </para> + <para> + Firstly, create a project by using maven archetype plugin: + </para> + +<programlisting>mvn archetype:generate +</programlisting> + <itemizedlist> + <listitem> + <para> + For project type: select <emphasis role="bold">maven-archetype-quickstart </emphasis> + </para> + + </listitem> + <listitem> + <para> + For groupId: select <emphasis role="bold">org.exoplatform.samples</emphasis> + </para> + + </listitem> + <listitem> + <para> + For artifactId: select <emphasis role="bold">exo.samples.scheduler</emphasis> + </para> + + </listitem> + <listitem> + <para> + For version: select<emphasis role="bold"> 1.0.0-SNAPSHOT</emphasis> + </para> + + </listitem> + <listitem> + <para> + For package: select <emphasis role="bold">org.exoplatform.samples.scheduler</emphasis> + </para> + + </listitem> + + </itemizedlist> + <para> + Edit the pom.xml as follows: + </para> + +<programlisting language="XML" role="XML">&lt;project + xmlns="http://maven.apache.org/POM/4.0.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"&gt; + + &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt; + + &lt;parent&gt; + &lt;artifactId&gt;exo.portal.parent&lt;/artifactId&gt; + &lt;groupId&gt;org.exoplatform.portal&lt;/groupId&gt; + &lt;version&gt;3.1.0-GA&lt;/version&gt; + &lt;/parent&gt; + + &lt;groupId&gt;org.exoplatform.samples&lt;/groupId&gt; + &lt;artifactId&gt;exo.samples.scheduler&lt;/artifactId&gt; + &lt;version&gt;1.0.0-SNAPSHOT&lt;/version&gt; + &lt;name&gt;eXo Samples For Scheduler&lt;/name&gt; + &lt;description&gt;eXo Samples Code For Scheduler&lt;/description&gt; +&lt;/project&gt;</programlisting> + <para> + Generate an eclipse project by using maven eclipse plugin and then import into eclipse: + </para> + +<programlisting>mvn eclipse:eclipse</programlisting> + <para> + eXo Kernel makes it easier to work with job scheduler service. All you need is just to define your "job" class to be performed by implementing <emphasis role="italic">org.quartz.Job</emphasis> interface and add configuration for it. + </para> + <section id="sect-Reference_Guide-Samples-Define_a_job"> + <title>Define a job</title> + <para> + To define a job, do as follows: + </para> + <para> + Define your job to be performed. For example, the job <emphasis role="italic">DumbJob</emphasis> is defined as follows: + </para> + +<programlisting language="Java" role="Java">package org.exoplatform.samples.scheduler.jobs; + +import org.exoplatform.services.log.ExoLogger; +import org.exoplatform.services.log.Log; +import org.quartz.Job; +import org.quartz.JobExecutionContext; +import org.quartz.JobExecutionException; + +/** + * DumbJob for executing a defined dumb job. + */ +public class DumbJob implements Job { + + /** + * The logger + */ + private static final Log LOG = ExoLogger.getLogger(DumbJob.class); + + /** + * The job of the DumbJob will be done by executing this method. + * + * @param context + * @throws JobExecutionException + */ + public void execute(JobExecutionContext context) throws JobExecutionException { + LOG.info("DumbJob is executing..."); + } +}</programlisting> + <para> + All jobs are required to implement the method <emphasis role="italic">execute</emphasis> from <emphasis role="italic">org.quartz.Job</emphasis> interface. This method will be called whenever a job is performed. With <emphasis role="italic">DumbJob</emphasis>, you just use logging to see that it will work. By looking at the terminal, you will see the log message: "DumbJob is executing..." + </para> + + </section> + + <section id="sect-Reference_Guide-Samples-Job_configuration"> + <title>Job configuration</title> + <para> + After defining the "job", the only next step is to configure it by using <emphasis role="italic">external-component-plugin</emphasis> configuration for <emphasis role="italic">org.exoplatform.services.scheduler.JobSchedulerService</emphasis>. You can use these methods below for setting component plugin: + </para> + +<programlisting language="Java" role="Java">public void addPeriodJob(ComponentPlugin plugin) throws Exception;</programlisting> + <para> + The component plugin for this method must be the type of <emphasis role="italic">org.exoplatform.services.scheduler.PeriodJob</emphasis>. This type of job is used to perform actions that are executed in a period of time. You have to define when this job is performed, when it ends, when it performs the first action, how many times it is executed and the period of time to perform the action. See the configuration sample below to understand more clearly: + </para> + +<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.scheduler.JobSchedulerService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;PeriodJob Plugin&lt;/name&gt; + &lt;set-method&gt;addPeriodJob&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.scheduler.PeriodJob&lt;/type&gt; + &lt;description&gt;period job configuration&lt;/description&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;job.info&lt;/name&gt; + &lt;description&gt;dumb job executed periodically&lt;/description&gt; + &lt;property name="jobName" value="DumbJob"/&gt; + &lt;property name="groupName" value="DumbJobGroup"/&gt; + &lt;property name="job" value="org.exoplatform.samples.scheduler.jobs.DumbJob"/&gt; + &lt;property name="repeatCount" value="0"/&gt; + &lt;property name="period" value="60000"/&gt; + &lt;property name="startTime" value="+45"/&gt; + &lt;property name="endTime" value=""/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt;</programlisting> + +<programlisting language="Java" role="Java">public void addCronJob(ComponentPlugin plugin) throws Exception;</programlisting> + <para> + The component plugin for this method must be the type of <emphasis role="italic">org.exoplatform.services.scheduler.CronJob</emphasis>. This type of job is used to perform actions at specified time with Unix 'cron-like' definitions. The plugin uses "expression" field for specifying the 'cron-like' definitions to execute the job. This is considered as the most powerful and flexible job to define when it will execute. For example, at 12pm every day =&gt; "0 0 12 * * ?"; or at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday =&gt; "0 15 10 ? * MON-FRI". To see more about Cron expression, please refer to this article: <ulink url="http://en.wikipedia.org/wiki/CRON_expression">CRON expression</ulink>. See the configuration sample below to understand more clearly: + </para> + +<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.scheduler.JobSchedulerService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;CronJob Plugin&lt;/name&gt; + &lt;set-method&gt;addCronJob&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.scheduler.CronJob&lt;/type&gt; + &lt;description&gt;cron job configuration&lt;/description&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;job.info&lt;/name&gt; + &lt;description&gt;dumb job executed by cron expression&lt;/description&gt; + &lt;property name="jobName" value="DumbJob"/&gt; + &lt;property name="groupName" value="DumbJobGroup"/&gt; + &lt;property name="job" value="org.exoplatform.samples.scheduler.jobs.DumbJob"/&gt; + &lt;!-- The job will be performed at 10:15am every day --&gt; + &lt;property name="expression" value="0 15 10 * * ?"/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt;</programlisting> + +<programlisting language="Java" role="Java">public void addGlobalJobListener(ComponentPlugin plugin) throws Exception;</programlisting> + +<programlisting language="Java" role="Java">public void addJobListener(ComponentPlugin plugin) throws Exception;</programlisting> + <para> + The component plugin for two methods above must be the type of <emphasis role="italic">org.quartz.JobListener.</emphasis> This job listener is used so that it will be informed when a <emphasis role="italic">org.quartz.JobDetail</emphasis> executes. + </para> + +<programlisting language="Java" role="Java">public void addGlobalTriggerListener(ComponentPlugin plugin) throws Exception;</programlisting> + +<programlisting language="Java" role="Java">public void addTriggerListener(ComponentPlugin plugin) throws Exception;</programlisting> + <para> + The component plugin for two methods above must be the type of <emphasis role="italic">org.quartz.TriggerListener</emphasis>. This trigger listener is used so that it will be informed when a <emphasis role="italic">org.quartz.Trigger</emphasis> fires. + </para> + + </section> + + <section id="sect-Reference_Guide-Samples-Run_the_project"> + <title>Run the project</title> + <para> + Create <emphasis role="italic">conf.portal</emphasis> package in your sample project. Add the configuration.xml file with the content as follows: + </para> + +<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;configuration + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"&gt; + + &lt;component&gt; + &lt;type&gt;org.exoplatform.services.scheduler.impl.QuartzSheduler&lt;/type&gt; + &lt;/component&gt; + &lt;component&gt; + &lt;type&gt;org.exoplatform.services.scheduler.QueueTasks&lt;/type&gt; + &lt;/component&gt; + &lt;component&gt; + &lt;key&gt;org.exoplatform.services.scheduler.JobSchedulerService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.scheduler.impl.JobSchedulerServiceImpl&lt;/type&gt; + &lt;/component&gt; + + &lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.scheduler.JobSchedulerService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;PeriodJob Plugin&lt;/name&gt; + &lt;set-method&gt;addPeriodJob&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.scheduler.PeriodJob&lt;/type&gt; + &lt;description&gt;period job configuration&lt;/description&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;job.info&lt;/name&gt; + &lt;description&gt;dumb job executed periodically&lt;/description&gt; + &lt;property name="jobName" value="DumbJob"/&gt; + &lt;property name="groupName" value="DumbJobGroup"/&gt; + &lt;property name="job" value="org.exoplatform.samples.scheduler.jobs.DumbJob"/&gt; + &lt;property name="repeatCount" value="0"/&gt; + &lt;property name="period" value="60000"/&gt; + &lt;property name="startTime" value="+45"/&gt; + &lt;property name="endTime" value=""/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt; +&lt;/configuration&gt;</programlisting> + <para> + <emphasis role="italic">mvn clean install </emphasis>the project. Copy .jar file to<emphasis role="italic"> lib</emphasis> in tomcat bundled with GateIn-3.1.0-GA. Run <emphasis role="italic">bin/gatein.sh</emphasis> to see the <emphasis role="italic">DumbJob</emphasis> to be executed on the terminal when portal containers are initialized. Please look at the terminal to see the log message of <emphasis role="italic">DumbJob</emphasis>. + </para> + <para> + From now on, you can easily create any job to be executed in GateIn's portal by defining your job and configuring it. + </para> + + </section> + + + </section> + + + </section> + + <section id="sect-Reference_Guide-Job_Schedule-Reference"> + <title>Reference</title> + <para> + To further understand about Job Scheduler, you can refer the following links: + </para> + <itemizedlist> + <listitem> + <para> + <ulink url="http://www.quartz-scheduler.org/">http://www.quartz-sch... + </para> + + </listitem> + <listitem> + <para> + <ulink url="http://en.wikipedia.org/wiki/Job_scheduler">http://en.w... + </para> + + </listitem> + <listitem> + <para> + <ulink url="http://www.theserverside.com/news/1364726/Job-Scheduling-in-J2E... + </para> + + </listitem> + <listitem> + <para> + <ulink url="http://technet.microsoft.com/en-us/library/cc720070%28WS.10%29.... + </para> + + </listitem> + + </itemizedlist> + + </section> +</section> + +<section id="sect-Reference_Guide-The_data_source_provider"> + <title>The data source provider</title> + <section id="sect-Reference_Guide-The_data_source_provider-Description"> + <title>Description</title> + <para> + The <emphasis>DataSourceProvider</emphasis> is a service used to give access to a data source in an uniform manner in order to be able to support data sources that are managed by the application server. + </para> + <para> + <table id="tabl-Reference_Guide-Description-List_methods"> + <title>List methods</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> + getDataSource(String dataSourceName) + </entry> + <entry> + Tries to get the data source from a JNDI lookup. If it can be found and the data source is defined as managed, the service will wrap the original <emphasis>DataSource</emphasis> instance in a new <emphasis>DataSource</emphasis> instance that is aware of its <emphasis>managed</emphasis> state otherwise it will return the original <emphasis>DataSource</emphasis> instance. + </entry> + + </row> + <row> + <entry> + isManaged(String dataSourceName) + </entry> + <entry> + Indicates whether or not the given data source is managed. + </entry> + + </row> + + </tbody> + + </tgroup> + + </table> + </para> + + </section> + + <section id="sect-Reference_Guide-The_data_source_provider-Configuration"> + <title>Configuration</title> + <para> + The configuration of the <emphasis>DataSourceProvider</emphasis> should be defined only if you use managed data sources since by default all the data sources are considered as not managed. See below the default configuration + </para> + +<programlisting>&lt;configuration&gt; +.... + &lt;component&gt; + &lt;key&gt;org.exoplatform.services.jdbc.DataSourceProvider&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.jdbc.impl.DataSourceProviderImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;!-- Indicates that the data source needs to check if a tx is active + to decide if the provided connection needs to be managed or not. + If it is set to false, the data source will provide only + managed connections if the data source itself is managed. --&gt; + &lt;!--value-param&gt; + &lt;name&gt;check-tx-active&lt;/name&gt; + &lt;value&gt;true&lt;/value&gt; + &lt;/value-param--&gt; + &lt;!-- Indicates that all the data sources are managed + If set to true the parameter never-managed and + managed-data-sources will be ignored --&gt; + &lt;!--value-param&gt; + &lt;name&gt;always-managed&lt;/name&gt; + &lt;value&gt;true&lt;/value&gt; + &lt;/value-param--&gt; + &lt;!-- Indicates the list of all the data sources that are + managed, each value tag can contain a list of + data source names separated by a comma, in the + example below we will register ds-foo1, ds-foo2 + and ds-foo3 as managed data source. If always-managed + and/or never-managed is set true this parameter is ignored --&gt; + &lt;!--values-param&gt; + &lt;name&gt;managed-data-sources&lt;/name&gt; + &lt;value&gt;ds-foo1, ds-foo2&lt;/value&gt; + &lt;value&gt;ds-foo3&lt;/value&gt; + &lt;/values-param--&gt; + &lt;/init-params&gt; + &lt;/component&gt; +... +&lt;/configuration&gt;</programlisting> + <table id="tabl-Reference_Guide-Configuration-Fields_description-2"> + <title>Fields description</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>check-tx-active</emphasis> + </entry> + <entry> + This parameter indicates that the data source needs to check if a transaction is active to decide if the provided connection needs to be managed or not. If it is set to <emphasis>false</emphasis>, the data source will provide only managed connections if the data source itself is managed. By default, this parameter is set to <emphasis>true</emphasis>. If this parameter is set to <emphasis>true</emphasis>, it will need the <emphasis>TransactionService</emphasis> to work properly, so please ensure that the <emphasis>TransactionService</emphasis> is defined in your configuration. + </entry> + + </row> + <row> + <entry> + <emphasis>always-managed</emphasis> + </entry> + <entry> + This parameter indicates that all the data sources are managed. If set to <emphasis>true</emphasis> the parameter <emphasis>never-managed</emphasis> and <emphasis>managed-data-sources</emphasis> will be ignored, so it will consider all the data sources as managed. By default, this parameter is set to <emphasis>false</emphasis>. + </entry> + + </row> + <row> + <entry> + <emphasis>managed-data-sources</emphasis> + </entry> + <entry> + This parameter indicates the list of all the data sources that are managed, each value tag can contain a list of data source names separated by a comma. If <emphasis>always-managed</emphasis> and/or <emphasis>never-managed</emphasis> is set <emphasis>true</emphasis> this parameter is ignored. + </entry> + + </row> + + </tbody> + + </tgroup> + + </table> + + </section> + +</section> + + +</section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/jcr-exo-implementation.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/jcr-exo-implementation.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/jcr-exo-implementation.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -6,8 +6,6 @@ <section id="sect-Reference_Guide-Implementation"> <!-- This document was created with Syntext Serna Free. --> <title>Implementation</title> - <section id="sect-Reference_Guide-Implementation-How_it_works"> - <title>How it works</title> <para> The relationships between the eXo Repository Service components are shown in the picture below: </para> @@ -75,7 +73,6 @@ </para> </step> </procedure> - </section> <section id="sect-Reference_Guide-Implementation-Workspace_Data_Model"> <title>Workspace Data Model</title> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/jcr-namespace-altering.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/jcr-namespace-altering.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/jcr-namespace-altering.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -4,36 +4,41 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Namespace_Altering"> - <!-- This document was created with Syntext Serna Free. --> <title>Namespace Altering</title> - <para> - Since version 1.11, eXo JCR implementation supports namespaces altering. - </para> - <section id="sect-Reference_Guide-Namespace_Altering-Adding_new_namespace"> - <title>Adding new namespace</title> - + <!-- This document was created with Syntext Serna Free. --> <title>Namespace Altering</title> + <para> + Since version 1.11, eXo JCR implementation supports namespaces altering. + </para> + <formalpara> + <title>Adding new namespace</title> + <para> + Add a new namespace with: + </para> + + </formalpara> <programlisting language="Java" role="Java">ExtendedNamespaceRegistry namespaceRegistry = (ExtendedNamespaceRegistry) workspace.getNamespaceRegistry(); namespaceRegistry.registerNamespace("newMapping", "http://dumb.uri/jcr");</programlisting> - </section> - - <section id="sect-Reference_Guide-Namespace_Altering-Changing_existing_namespace"> - <title>Changing existing namespace</title> - + + + <formalpara> + <title>Changing existing namespace</title> + <para> + Change an existing namespace with: + </para> + </formalpara> <programlisting language="Java" role="Java">ExtendedNamespaceRegistry namespaceRegistry = (ExtendedNamespaceRegistry) workspace.getNamespaceRegistry(); namespaceRegistry.registerNamespace("newMapping", "http://dumb.uri/jcr"); namespaceRegistry.registerNamespace("newMapping2", "http://dumb.uri/jcr");</programlisting> - </section> - - <section id="sect-Reference_Guide-Namespace_Altering-Removing_existing_namespace"> - <title>Removing existing namespace</title> - + <formalpara> + <title>Removing existing namespace</title> + <para> + Remove an existing namespace with: + </para> + </formalpara> <programlisting language="Java" role="Java">ExtendedNamespaceRegistry namespaceRegistry = (ExtendedNamespaceRegistry) workspace.getNamespaceRegistry(); namespaceRegistry.registerNamespace("newMapping", "http://dumb.uri/jcr"); namespaceRegistry.unregisterNamespace("newMapping");</programlisting> - - </section> - </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/nodetype-registration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/nodetype-registration.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/concepts/nodetype-registration.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -4,33 +4,33 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-NodeType_Registration"> - <!-- This document was created with Syntext Serna Free. --> <title>NodeType Registration</title> - <para> - eXo JCR implementation supports two ways of Nodetypes registration: - </para> - <itemizedlist> - <listitem> - <para> - From a NodeTypeValue POJO - </para> + <!-- This document was created with Syntext Serna Free. --> <title>NodeType Registration</title> + <para> + eXo JCR implementation supports two ways of Nodetypes registration: + </para> + <itemizedlist> + <listitem> + <para> + From a <literal>NodeTypeValue</literal> POJO. Refer to <xref linkend="exam-Reference_Guide-Node_type_registration-Run_time_registration_using_NodeTypeValue"/> + </para> - </listitem> - <listitem> - <para> - From an XML document (stream) - </para> + </listitem> + <listitem> + <para> + From an XML document. Refer to <xref linkend="exam-Reference_Guide-Node_type_registration-Run_time_registration_from_xml_file"/>. + </para> - </listitem> + </listitem> - </itemizedlist> - <section id="sect-Reference_Guide-NodeType_Registration-Interfaces_and_methods"> - <title>Interfaces and methods</title> - <section id="sect-Reference_Guide-Interfaces_and_methods-ExtendedNodeTypeManager"> - <title>ExtendedNodeTypeManager</title> - <para> - The ExtendedNodeTypeManager (from JCR 1.11) interface provides the following methods related to registering node types: - </para> - + </itemizedlist> + <section id="sect-Reference_Guide-NodeType_Registration-Interfaces_and_methods"> + <title>Interfaces and methods</title> + <section id="sect-Reference_Guide-Interfaces_and_methods-ExtendedNodeTypeManager"> + <title>ExtendedNodeTypeManager</title> + <para> + The <literal>ExtendedNodeTypeManager</literal> (from JCR 1.11) interface provides the following methods related to registering node types: + </para> + <programlisting language="Java" role="Java">public static final int IGNORE_IF_EXISTS = 0; public static final int FAIL_IF_EXISTS = 2; @@ -78,14 +78,14 @@ NoSuchNodeTypeException, RepositoryException;</programlisting> - </section> - - <section id="sect-Reference_Guide-Interfaces_and_methods-NodeTypeValue"> - <title>NodeTypeValue</title> - <para> - The NodeTypeValue interface represents a simple container structure used to define node types which are then registered through the ExtendedNodeTypeManager.registerNodeType method. The implementation of this interface does not contain any validation logic. - </para> - + </section> + + <section id="sect-Reference_Guide-Interfaces_and_methods-NodeTypeValue"> + <title>NodeTypeValue</title> + <para> + The NodeTypeValue interface represents a simple container structure used to define node types which are then registered through the ExtendedNodeTypeManager.registerNodeType method. The implementation of this interface does not contain any validation logic. + </para> + <programlisting language="Java" role="Java">/** * @return Returns the declaredSupertypeNames. */ @@ -163,14 +163,14 @@ */ public void setDeclaredPropertyDefinitionValues(List&lt;PropertyDefinitionValue&gt; declaredPropertyDefinitionValues);</programlisting> - </section> - - <section id="sect-Reference_Guide-Interfaces_and_methods-NodeDefinitionValue"> - <title>NodeDefinitionValue</title> - <para> - The NodeDefinitionValue interface extends ItemDefinitionValue with the addition of writing methods, enabling the characteristics of a child node definition to be set, after that the NodeDefinitionValue is added to a NodeTypeValue. - </para> - + </section> + + <section id="sect-Reference_Guide-Interfaces_and_methods-NodeDefinitionValue"> + <title>NodeDefinitionValue</title> + <para> + The NodeDefinitionValue interface extends ItemDefinitionValue with the addition of writing methods, enabling the characteristics of a child node definition to be set, after that the NodeDefinitionValue is added to a NodeTypeValue. + </para> + <programlisting language="Java" role="Java">/** * @return Returns the declaredSupertypeNames. */ @@ -250,14 +250,16 @@ </programlisting> - </section> - - <section id="sect-Reference_Guide-Interfaces_and_methods-PropertyDefinitionValue"> - <title>PropertyDefinitionValue</title> - <para> - The PropertyDefinitionValue interface extends ItemDefinitionValue with the addition of writing methods, enabling the characteristics of a child property definition to be set, after that the PropertyDefinitionValue is added to a NodeTypeValue. - </para> - + </section> + + <section id="sect-Reference_Guide-Interfaces_and_methods-PropertyDefinitionValue"> + <title>PropertyDefinitionValue</title> + <para> + The <literal>PropertyDefinitionValue</literal> interface extends <literal>ItemDefinitionValue</literal> with the addition of writing methods, enabling the characteristics of a child property definition to be set, after that the <literal>PropertyDefinitionValue</literal> is added to a <literal>NodeTypeValue</literal>. + </para> + + <example> + <title>PropertyDefinitionValue</title> <programlisting language="Java" role="Java">/** * @return Returns the defaultValues. */ @@ -297,12 +299,10 @@ * @param valueConstraints The valueConstraints to set. */ public void setValueConstraints(List&lt;String&gt; valueConstraints);</programlisting> + </example> - </section> - - <section id="sect-Reference_Guide-Interfaces_and_methods-ItemDefinitionValue"> - <title>ItemDefinitionValue</title> - + <example> + <title>ItemDefinitionValue</title> <programlisting language="Java" role="Java"> /** * @return Returns the autoCreate. */ @@ -352,30 +352,28 @@ * @param readOnly The readOnly to set. */ public void setReadOnly(boolean readOnly);</programlisting> +</example> - </section> - - - </section> - - <section id="sect-Reference_Guide-NodeType_Registration-Node_type_registration"> - <title>Node type registration</title> - <para> - eXo JCR implementation supports various methods of the node-type registration. - </para> - <section id="sect-Reference_Guide-Node_type_registration-Run_time_registration_from_xml_file."> - <title>Run time registration from xml file.</title> - + </section> + + <section id="sect-Reference_Guide-NodeType_Registration-Node_type_registration"> + <title>Node type registration</title> + <para> + The eXo JCR implementation supports various methods of the node-type registration. + </para> + + <example id="exam-Reference_Guide-Node_type_registration-Run_time_registration_from_xml_file"> + <title>Run time registration from xml file</title> <programlisting language="Java" role="Java">ExtendedNodeTypeManager nodeTypeManager = (ExtendedNodeTypeManager) session.getWorkspace() .getNodeTypeManager(); InputStream is = MyClass.class.getResourceAsStream("mynodetypes.xml"); nodeTypeManager.registerNodeTypes(is,ExtendedNodeTypeManager.IGNORE_IF_EXISTS );</programlisting> + </example> - </section> - - <section id="sect-Reference_Guide-Node_type_registration-Run_time_registration_using_NodeTypeValue."> - <title>Run time registration using NodeTypeValue.</title> - + + + <example id="exam-Reference_Guide-Node_type_registration-Run_time_registration_using_NodeTypeValue"> + <title>Run time registration using NodeTypeValue</title> <programlisting language="Java" role="Java">ExtendedNodeTypeManager nodeTypeManager = (ExtendedNodeTypeManager) session.getWorkspace() .getNodeTypeManager(); NodeTypeValue testNValue = new NodeTypeValue(); @@ -398,44 +396,35 @@ testNValue.setDeclaredPropertyDefinitionValues(props); nodeTypeManager.registerNodeType(testNValue, ExtendedNodeTypeManager.FAIL_IF_EXISTS);</programlisting> - - </section> - - - </section> - - <section id="sect-Reference_Guide-NodeType_Registration-Changing_existing_node_type"> - <title>Changing existing node type</title> - <para> - If you want to replace existing node type definition, you should pass ExtendedNodeTypeManager.REPLACE_IF_EXISTS as a second parameter for the method ExtendedNodeTypeManager.registerNodeType. - </para> - + </example> + </section> + + <section id="sect-Reference_Guide-NodeType_Registration-Changing_existing_node_type"> + <title>Changing existing node type</title> + <para> + To replace an existing node type definition pass <literal>ExtendedNodeTypeManager.REPLACE_IF_EXISTS</literal> as a second parameter for the method <literal>ExtendedNodeTypeManager.registerNodeType</literal>. + </para> + <programlisting language="Java" role="Java">ExtendedNodeTypeManager nodeTypeManager = (ExtendedNodeTypeManager) session.getWorkspace() .getNodeTypeManager(); InputStream is = MyClass.class.getResourceAsStream("mynodetypes.xml"); ..... nodeTypeManager.registerNodeTypes(is,ExtendedNodeTypeManager.REPLACE_IF_EXISTS );</programlisting> - </section> - - <section id="sect-Reference_Guide-NodeType_Registration-Removing_node_type"> - <title>Removing node type</title> - <note> - <para> - Node type is only possibly removed when the repository does not contain this node type. - </para> + </section> + + <section id="sect-Reference_Guide-NodeType_Registration-Removing_node_type"> + <title>Removing node type</title> + <para> + A node type cannot be removed if the repository contains an instance of that node type. + </para> + +<programlisting language="Java" role="Java">nodeTypeManager.unregisterNodeType(<literal>myNodeType</literal>);</programlisting> - </note> - -<programlisting language="Java" role="Java">nodeTypeManager.unregisterNodeType("myNodeType");</programlisting> - - </section> - - <section id="sect-Reference_Guide-NodeType_Registration-Practical_How_to"> - <title>Practical How to</title> - <section id="sect-Reference_Guide-Practical_How_to-Adding_new_PropertyDefinition"> - <title>Adding new PropertyDefinition</title> - + </section> + <section id="sect-Reference_Guide-Practical_How_to-Adding_new_PropertyDefinition"> + <title>Adding new PropertyDefinition</title> + <programlisting language="Java" role="Java"> NodeTypeValue myNodeTypeValue = nodeTypeManager.getNodeTypeValue(myNodeTypeName); List&lt;PropertyDefinitionValue&gt; props = new ArrayList&lt;PropertyDefinitionValue&gt;(); @@ -452,11 +441,13 @@ nodeTypeManager.registerNodeType(myNodeTypeValue, ExtendedNodeTypeManager.REPLACE_IF_EXISTS);</programlisting> - </section> - - <section id="sect-Reference_Guide-Practical_How_to-Adding_new_child_NodeDefinition"> - <title>Adding new child NodeDefinition</title> - + </section> + + <section id="sect-Reference_Guide-Practical_How_to-Adding_new_child_NodeDefinition"> + <title>Adding new child NodeDefinition</title> + <para> + Use the code below to add a new child <literal>NodeDefinition</literal>. + </para> <programlisting language="Java" role="Java">NodeTypeValue myNodeTypeValue = nodeTypeManager.getNodeTypeValue(myNodeTypeName); List&lt;NodeDefinitionValue&gt; nodes = new ArrayList&lt;NodeDefinitionValue&gt;(); @@ -472,67 +463,63 @@ nodeTypeManager.registerNodeType(myNodeTypeValue, ExtendedNodeTypeManager.REPLACE_IF_EXISTS);</programlisting> - </section> - - <section id="sect-Reference_Guide-Practical_How_to-Changing_or_removing_existing_PropertyDefinition_or_child_NodeDefinition"> - <title>Changing or removing existing PropertyDefinition or child NodeDefinition</title> - <para> - Note that the existing data must be consistent before changing or removing a existing definition . JCR <emphasis role="bold">does not allow</emphasis> you to change the node type in the way in which the existing data would be incompatible with a new node type. But if these changes are needed, you can do it in several phases, consistently changing the node type and the existing data. - </para> - <para> - For example: - </para> - <para> - Add a new residual property definition with name "downloadCount" to the existing node type "myNodeType". - </para> - <para> - There are two limitations that do not allow us to make the task with a single call of registerNodeType method. - </para> - <itemizedlist> - <listitem> - <para> - Existing nodes of the type "myNodeType", which does not contain properties "downloadCount" that conflicts with node type what we need. - </para> + </section> + + <section id="sect-Reference_Guide-Practical_How_to-Changing_or_removing_existing_PropertyDefinition_or_child_NodeDefinition"> + <title>Edit existing PropertyDefinition or child NodeDefinition</title> + <para> + Note that the existing data must be consistent before changing or removing a existing definition. + </para> + <para> + The JCR does not allow you to change the node type in any way in which the existing data would be incompatible with the new node type. + </para> + <para> + But if these changes are necessary, an incremental process (which consistently changes the node type and the existing data) can achieve node type changes that would not be possible in a direct call. + </para> + <para> + For example: If you wanted to add a new residual property definition called <literal>downloadCount</literal> to the existing node type <literal>myNodeType</literal>, you would encounter two limitations that would not allow you to execute the task with a single call of registerNodeType method. + </para> + <itemizedlist> + <listitem> + <para> + Existing nodes of the type <literal>myNodeType</literal>, which does not contain properties <literal>downloadCount</literal> that conflicts with node type what we need. + </para> - </listitem> - <listitem> - <para> - Registered node type "myNodeType" will not allow us to add properties "downloadCount" because it has no such specific properties. - </para> - - </listitem> - - </itemizedlist> - <para> - To complete the task, we need to make 3 steps: - </para> - <itemizedlist> - <listitem> - <para> - Change the existing node type "myNodeType" by adding the mandatory property "downloadCount". - </para> - - </listitem> - <listitem> - <para> - Add the node type "myNodeType" with the property "downloadCount" to all the existing node types. - </para> - - </listitem> - <listitem> - <para> - Change the definition of the property "downloadCount" of the node type "myNodeType" to mandatory. - </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide-Practical_How_to-Changing_the_list_of_super_types"> - <title>Changing the list of super types</title> - + </listitem> + <listitem> + <para> + Registered node type <literal>myNodeType</literal> will not allow us to add properties <literal>downloadCount</literal> because it has no such specific properties. + </para> + </listitem> + </itemizedlist> + <para> + The task could be executed, however, with the following steps: + </para> + <procedure> + <title></title> + <step> + <para> + Change the existing node type <literal>myNodeType</literal> by adding the mandatory property <literal>downloadCount</literal>. + </para> + </step> + <step> + <para> + Add the node type <literal>myNodeType</literal> with the property <literal>downloadCount</literal> to all the existing node types. + </para> + </step> + <step> + <para> + Change the definition of the property <literal>downloadCount</literal> of the node type <literal>myNodeType</literal> to mandatory. + </para> + </step> + </procedure> + </section> + + <section id="sect-Reference_Guide-Practical_How_to-Changing_the_list_of_super_types"> + <title>Changing the list of super types</title> + <para> + Use the following code to change the list of super types: + </para> <programlisting language="Java" role="Java">NodeTypeValue testNValue = nodeTypeManager.getNodeTypeValue("exo:myNodeType"); List&lt;String&gt; superType = testNValue.getDeclaredSupertypeNames(); @@ -541,11 +528,6 @@ nodeTypeManager.registerNodeType(testNValue, ExtendedNodeTypeManager.REPLACE_IF_EXISTS);</programlisting> - </section> - - - </section> - -</section> - - + </section> + </section> +</section> \ No newline at end of file Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/configuration-persister.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/configuration-persister.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/configuration-persister.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -6,10 +6,14 @@ <section id="sect-Reference_Guide-JCR_Configuration_persister"> <title>JCR Configuration persister</title> <section id="sect-Reference_Guide-JCR_Configuration_persister-Idea"> - <title>Idea</title> + <title>Concept</title> <para> - JCR Repository Service uses <classname>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</classname> component to read its configuration. + The JCR Repository Service uses the <literal>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</literal> component for its configuration. </para> +<programlistingco> + <areaspec> + <area coords="8" id="area-Reference_Guide-JCR_Configuration_persister-Idea-config" /> + </areaspec> <programlisting language="XML" role="XML">&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; @@ -21,26 +25,35 @@ &lt;/value-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> + <calloutlist> + <!--#1--> + <callout arearefs="area-Reference_Guide-JCR_Configuration_persister-Idea-config"> + <para> + In this example, the Repository Service will read the configuration from the file <filename>war:/conf/jcr/repository-configuration.xml</filename>. + </para> + </callout> + </calloutlist> +</programlistingco> <para> - In the example, Repository Service will read the configuration from the file <filename>war:/conf/jcr/repository-configuration.xml</filename>. + In some cases a change in the configuration is required while the component is in use. To ensure the new configuration is used and, without modifying the original file, eXo JCR uses the configuration persister feature which allows to store the configuration in different locations. </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 id="sect-Reference_Guide-JCR_Configuration_persister-Usage"> <title>Usage</title> <para> - On startup <classname>RepositoryServiceConfiguration</classname> component checks if a configuration persister was configured. In that case, it uses the provided <classname>ConfigurationPersister</classname> implementation class to instantiate the persister object. + On start up the <literal>RepositoryServiceConfiguration</literal> component checks if a configuration persister was configured. If one has been, it uses the provided <literal>ConfigurationPersister</literal> implementation class to instantiate the persister object. </para> <para> Configuration with persister: </para> +<programlistingco> + <areaspec> + <area coords="13" id="area-Reference_Guide-JCR_Configuration_persister-Usage-source_name" /> + <area coords="14" id="area-Reference_Guide-JCR_Configuration_persister-Usage-dialect" /> + <area coords="15" id="area-Reference_Guide-JCR_Configuration_persister-Usage-persister_class_name" /> + </areaspec> <programlisting language="XML" role="XML">&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; @@ -60,32 +73,30 @@ &lt;/init-params&gt; &lt;/component&gt; </programlisting> - <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 <xref linkend="sect-Reference_Guide-JDBC_Data_Container_Config" />. - </para> + <calloutlist> + <!--#1--> + <callout arearefs="area-Reference_Guide-JCR_Configuration_persister-Usage-source_name"> + <para> + <parameter><replaceable>source-name</replaceable></parameter>: The JNDI source name is configured in the <literal>InitialContextInitializer</literal> component. This was known as <parameter>sourceName</parameter> in versions prior to 1.9. Refer to <xref linkend="sect-Reference_Guide-JDBC_Data_Container_Config" /> for more information. + </para> + </callout> + <!--#2--> + <callout arearefs="area-Reference_Guide-JCR_Configuration_persister-Usage-dialect"> + <para> + <parameter><replaceable>dialect</replaceable></parameter>: The SQL dialect which will be used with the database from <parameter><replaceable>source-name</replaceable></parameter>. Refer to <xref linkend="sect-Reference_Guide-JDBC_Data_Container_Config" /> for more information. + </para> + </callout> + <!--#3--> + <callout arearefs="area-Reference_Guide-JCR_Configuration_persister-Usage-persister_class_name"> + <para> + <parameter><replaceable>persister-class-name</replaceable></parameter>: The class name of the <literal>ConfigurationPersister</literal> interface implementation. This was known as <parameter>persisterliteral</parameter> in versions prior to 1.9. + </para> + </callout> + </calloutlist> +</programlistingco> - </listitem> - <listitem> - <para> - <parameter>dialect</parameter>: SQL dialect which will be used with database from <parameter>source-name</parameter>. Find more in <xref linkend="sect-Reference_Guide-JDBC_Data_Container_Config" />. - </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: + The <literal>ConfigurationPersister</literal> interface: </para> <programlisting language="Java" role="Java">/** @@ -114,14 +125,14 @@ boolean hasConfig() throws RepositoryConfigurationException; </programlisting> <para> - JCR Core implementation contains a persister which stores the repository configuration in the relational database using JDBC calls - <classname>org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister</classname>. + The JCR Core implementation contains a persister which stores the repository configuration in the relational database using JDBC calls: <literal>org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister</literal>. </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> + Developers can implement a custom persister for individual use cases. + </para> </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/exo-jcr-configuration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/exo-jcr-configuration.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/exo-jcr-configuration.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -11,7 +11,7 @@ <programlisting language="Java" role="Java"><xi:include href="../../../../../extras/Advanced_Development_JCR_Configuration/NMTOKEN.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - To modify the configuration of the JCR Service, you would need to modify the file found at <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + To modify the configuration of the JCR Service, you need to modify the file found at <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> <programlisting> @@ -48,19 +48,19 @@ </listitem> <listitem> <para> - <literal>portal-work</literal>: To store elements that are temporary such as tokens + <literal>portal-work</literal>: To store elements that are temporary such as tokens. </para> </listitem> <listitem> <para> - <literal>wsrp-system</literal>: To store WSRP related data + <literal>wsrp-system</literal>: To store WSRP related data. </para> </listitem> <listitem> <para> - <literal>wsrp-system</literal>: To store Portlet Container related data (such as portlet preferences + <literal>wsrp-system</literal>: To store Portlet Container related data (such as portlet preferences). </para> </listitem> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/external-value-storages.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/external-value-storages.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/external-value-storages.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -4,85 +4,85 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-External_Value_Storages"> - <title>External Value Storages</title> - <section id="sect-Reference_Guide-External_Value_Storages-Introduction"> - <title>Introduction</title> - <para> - JCR values are stored in the Workspace Data container by default. eXo JCR offers an additional option of storing JCR values separately from the Workspace Data container which can help keep Binary Large Objects (BLOBs) separate. - </para> - <para> - Value storage configuration is a part of the repository configuration. Refer to <xref linkend="sect-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace" /> for more details. - </para> - <para> - Tree-based storage is recommended in most cases. - </para> - <!-- Not sure this is necessary + <title>External Value Storages</title> + <section id="sect-Reference_Guide-External_Value_Storages-Introduction"> + <title>Introduction</title> + <para> + JCR values are stored in the Workspace Data container by default. The eXo JCR offers an additional option of storing JCR values separately from the Workspace Data container which can help keep Binary Large Objects (BLOBs) separate. + </para> + <para> + Value storage configuration is a part of the repository configuration. Refer to <xref linkend="sect-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace" /> for more details. + </para> + <para> + Tree-based storage is recommended in most cases. + </para> + <!-- Not sure this is necessary <para> If you run an application on Amazon EC2 - the S3 option may be interesting for architecture. Simple 'flat' storage is good in speed of creation/deletion of values, it might be a compromise for a small storages. </para> --> - </section> - - <section id="sect-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage"> - <title>Tree File Value Storage</title> - <para> - Tree File Value Storage holds values in tree-like file system files. <property>Path</property> property points to the root directory to store the files. - </para> - <para> - This is a recommended type of external storage because it can contain large amount of files limited only by disk/volume free space. - </para> - <para> - However, using Tree File Value Storage can result in a higher time on value deletion, due to the removal of unused tree-nodes. - </para> - <programlistingco> - <areaspec> - <area coords="1" id="area-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-id" /> - <area coords="3" id="area-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-path" /> + </section> + + <section id="sect-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage"> + <title>Tree File Value Storage</title> + <para> + Tree File Value Storage holds values in tree-like file system files. <property>Path</property> property points to the root directory to store the files. + </para> + <para> + This is a recommended type of external storage because it can contain large amount of files limited only by disk/volume free space. + </para> + <para> + However, using Tree File Value Storage can result in a higher time on value deletion, due to the removal of unused tree-nodes. + </para> + <programlistingco> + <areaspec> + <area coords="1" id="area-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-id" /> + <area coords="3" id="area-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-path" /> - </areaspec> - + </areaspec> + <programlisting language="XML" role="XML"><xi:include href="../../../../../extras/Advanced_Development_JCR_external-value-storages/default25.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-id"> - <para> - The <emphasis role="bold">id</emphasis> is the value storage unique identifier, used for linking with properties stored in a workspace container - </para> + <calloutlist> + <callout arearefs="area-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-id"> + <para> + The <emphasis role="bold">id</emphasis> is the value storage unique identifier, used for linking with properties stored in a workspace container + </para> - </callout> - <callout arearefs="area-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-path"> - <para> - <emphasis role="bold">path</emphasis> is a location where value files will be stored. - </para> + </callout> + <callout arearefs="area-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-path"> + <para> + <emphasis role="bold">path</emphasis> is a location where value files will be stored. + </para> - </callout> + </callout> - </calloutlist> + </calloutlist> - </programlistingco> - - <para> - Each file value storage can have the <function>filters</function> for incoming values. A filter can match values by <property>property-type</property>, <property>property-name</property>, <property>ancestor-path</property>. It can also match the size of values stored (<property>min-value-size</property>) in bytes. - </para> - <para> - In the previous example a filter with <property>property-type</property> and <property>min-value-size</property> has been used. This results in storage for binary values with size greater of 1MB. - </para> - <para> - It is recommended that properties with large values are stored in file value storage only. - </para> - <para> - The example below shows a value storage with different locations for large files (<property>min-value-size</property> a 20Mb-sized filter). - </para> - <para> - A value storage uses ORed logic in the process of filter selection. This means the first filter in the list will be called first and if it is not matched the next will be called, and so on. - </para> - <para> - In this example a value matches the 20MB filter <property>min-value-size</property> and will be stored in the path "<literal>data/20Mvalues</literal>". All other filters will be stored in "<literal>data/values</literal>". - </para> - + </programlistingco> + + <para> + Each file value storage can have the <function>filters</function> for incoming values. A filter can match values by <property>property-type</property>, <property>property-name</property>, <property>ancestor-path</property>. It can also match the size of values stored (<property>min-value-size</property>) in bytes. + </para> + <para> + In the previous example a filter with <property>property-type</property> and <property>min-value-size</property> has been used. This results in storage for binary values with size greater of 1MB. + </para> + <para> + It is recommended that properties with large values are stored in file value storage only. + </para> + <para> + The example below shows a value storage with different locations for large files (<property>min-value-size</property> a 20Mb-sized filter). + </para> + <para> + A value storage uses ORed logic in the process of filter selection. This means the first filter in the list will be called first and if it is not matched the next will be called, and so on. + </para> + <para> + In this example a value matches the 20MB filter <property>min-value-size</property> and will be stored in the path "<literal>data/20Mvalues</literal>". All other filters will be stored in "<literal>data/values</literal>". + </para> + <programlisting language="XML" role="XML"><xi:include href="../../../../../extras/Advanced_Development_JCR_external-value-storages/default26.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - - <!-- <section id="sect-Reference_Guide-External_Value_Storages-Simple_File_Value_Storage"> + </section> + + <!-- <section id="sect-Reference_Guide-External_Value_Storages-Simple_File_Value_Storage"> <title>Simple File Value Storage</title> <note> <para> @@ -105,98 +105,98 @@ &lt;/filters&gt; </programlisting> </section> --> <section id="sect-Reference_Guide-External_Value_Storages-Content_Addressable_Value_storage_CAS_support"> - <title>Content Addressable Value storage (CAS) support</title> - <para> - eXo JCR supports the <phrase>Content-addressable storage</phrase> feature for <phrase>values</phrase> storing. - </para> - <para> - Content-addressable storage, also referred to as associative storage and abbreviated as <emphasis role="bold">CAS</emphasis>, is a mechanism for storing information that can be retrieved based on its content, not its storage location. - </para> - <para> - It is typically used for high-speed storage and retrieval of fixed content, such as documents stored for compliance with government regulations. - </para> - <para> - Content-addressable value storage stores unique content once. Different properties (values) with same content will be stored as one data file shared between those values. We can tell the value content will be shared across some values in storage and will be stored in one physical file. - </para> - <para> - Storage size will be decreased for applications which govern potentially same data in the content. - </para> - <para> - As an example; if 100 different properties contain the same data (mail attachments for example) the storage stores only one single file. The file will be shared with all referencing properties. - </para> - <para> - If a property value changes it is stored in an additional file. Alternatively the file is shared with other values, pointing to the same content. - </para> - <para> - The storage calculates value content address each time the property was changed. CAS write operations are more expensive compared to the non-CAS storages. - </para> - <para> - Content address calculation is based on <literal>java.security.MessageDigest</literal> hash computation and has been tested with MD5 and SHA1 algorithms. - </para> - <note> - <para> - CAS storage works most efficiently on data that does not change often. For data that changes frequently CAS is not as efficient as location-based addressing. - </para> + <title>Content Addressable Value storage (CAS) support</title> + <para> + eXo JCR supports the <phrase>Content-addressable storage</phrase> feature for <phrase>values</phrase> storing. + </para> + <para> + Content-addressable storage, also referred to as associative storage and abbreviated as <emphasis role="bold">CAS</emphasis>, is a mechanism for storing information that can be retrieved based on its content, not its storage location. + </para> + <para> + It is typically used for high-speed storage and retrieval of fixed content, such as documents stored for compliance with government regulations. + </para> + <para> + Content-addressable value storage stores unique content once. Different properties (values) with same content will be stored as one data file shared between those values. We can tell the value content will be shared across some values in storage and will be stored in one physical file. + </para> + <para> + Storage size will be decreased for applications which govern potentially same data in the content. + </para> + <para> + As an example; if 100 different properties contain the same data (mail attachments for example) the storage stores only one single file. The file will be shared with all referencing properties. + </para> + <para> + If a property value changes it is stored in an additional file. Alternatively the file is shared with other values, pointing to the same content. + </para> + <para> + The storage calculates value content address each time the property was changed. CAS write operations are more expensive compared to the non-CAS storages. + </para> + <para> + Content address calculation is based on <literal>java.security.MessageDigest</literal> hash computation and has been tested with MD5 and SHA1 algorithms. + </para> + <note> + <para> + CAS storage works most efficiently on data that does not change often. For data that changes frequently CAS is not as efficient as location-based addressing. + </para> - </note> - <para> - CAS support can be enabled for <phrase>Tree</phrase> and <phrase>Simple File Value Storage</phrase> types. - </para> - <para> - To enable CAS support just configure it in the JCR Repositories configuration with other Value Storages. - </para> - + </note> + <para> + CAS support can be enabled for <phrase>Tree</phrase> and <phrase>Simple File Value Storage</phrase> types. + </para> + <para> + To enable CAS support just configure it in the JCR Repositories configuration with other Value Storages. + </para> + <programlisting language="XML" role="XML"><xi:include href="../../../../../extras/Advanced_Development_JCR_external-value-storages/default28.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <variablelist id="vari-Reference_Guide-Content_Addressable_Value_storage_CAS_support-CAS_Properties"> - <title>CAS Properties</title> - <varlistentry> - <term>digest-algo</term> - <listitem> - <para> - Digest hash algorithm (MD5 and SHA1 were tested). - </para> + <variablelist id="vari-Reference_Guide-Content_Addressable_Value_storage_CAS_support-CAS_Properties"> + <title>CAS Properties</title> + <varlistentry> + <term>digest-algo</term> + <listitem> + <para> + Digest hash algorithm (MD5 and SHA1 were tested). + </para> - </listitem> + </listitem> - </varlistentry> - <varlistentry> - <term>vcas-type</term> - <listitem> - <para> - Value CAS internal data type, JDBC backed is currently implemented: - </para> - <para> - <literal>org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImpl</literal> - </para> + </varlistentry> + <varlistentry> + <term>vcas-type</term> + <listitem> + <para> + Value CAS internal data type, JDBC backed is currently implemented: + </para> + <para> + <literal>org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImpl</literal> + </para> - </listitem> + </listitem> - </varlistentry> - <varlistentry> - <term>jdbc-source-name</term> - <listitem> - <para> - A <literal>JDBCValueContentAddressStorageImpl</literal> specific parameter, a database will be used to save CAS metadata. - </para> + </varlistentry> + <varlistentry> + <term>jdbc-source-name</term> + <listitem> + <para> + A <literal>JDBCValueContentAddressStorageImpl</literal> specific parameter, a database will be used to save CAS metadata. + </para> - </listitem> + </listitem> - </varlistentry> - <varlistentry> - <term>jdbc-dialect</term> - <listitem> - <para> - A <literal>DBCValueContentAddressStorageImpl</literal> specific parameter defining database dialect. - </para> + </varlistentry> + <varlistentry> + <term>jdbc-dialect</term> + <listitem> + <para> + A <literal>DBCValueContentAddressStorageImpl</literal> specific parameter defining database dialect. + </para> - </listitem> + </listitem> - </varlistentry> + </varlistentry> - </variablelist> + </variablelist> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/jdbc-data-container-config.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/jdbc-data-container-config.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/jdbc-data-container-config.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -12,6 +12,7 @@ </para> <para> Currently the data container is tested with the following RDBMS: + </para> <itemizedlist> <listitem> <para> @@ -57,21 +58,20 @@ </listitem> </itemizedlist> - </para> - <para> <note> + <title>Isolation Levels</title> <para> - Please note, that JCR requires at least READ_COMMITED isolation level and other RDBMS configurations can cause some side-effects and issues. So, please, make sure proper isolation level is configured on database server side. + The JCR requires at least the <parameter>READ_COMMITED</parameter> isolation level and other RDBMS configurations can cause some side-effects and issues. So, please, make sure proper isolation level is configured on database server side. </para> - </note> - Each database software supports ANSI SQL standards but also has its own specifics. So, each database has its own configuration in eXo JCR as a database dialect parameter. If you need a more detailed configuration of the database, it's possible to do that by editing the metadata SQL-script files. + <para> + Each database software supports ANSI SQL standards but also has its own specifics. Therefore each database has its own configuration setting in the eXo JCR as a database dialect parameter. More detailed configuration of the database can be set by editing the metadata SQL-script files. </para> <para> - SQL-scripts you can obtain from jar-file exo.jcr.component.core-XXX.XXX.jar:conf/storage/. They also can be found at SVN <ulink url="https://anonsvn.jboss.org/repos/exo-jcr/jcr/trunk/exo.jcr.compo... + You can find SQL-scripts in <filename>conf/storage/</filename> directory of the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>jboss-as/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/lib/exo.jcr.component.core-XXX.XXX.jar</filename> file . </para> <para> - In the next two tables correspondence between the scripts and databases is shown. + The following tables show the correspondence between the scripts and databases: </para> <table id="tabl-Reference_Guide-Introduction-Single_database"> <title>Single-database</title> @@ -94,7 +94,7 @@ MySQL DB </entry> <entry> - jcr-sjdbc.mysql.sql + <filename>jcr-sjdbc.mysql.sql</filename> </entry> </row> @@ -103,7 +103,7 @@ MySQL DB with utf-8 </entry> <entry> - jcr-sjdbc.mysql-utf8.sql + <filename>jcr-sjdbc.mysql-utf8.sql</filename> </entry> </row> @@ -112,7 +112,7 @@ PostgresSQL </entry> <entry> - jcr-sjdbc.pqsql.sql + <filename>jcr-sjdbc.pqsql.sql</filename> </entry> </row> @@ -121,7 +121,7 @@ Oracle DB </entry> <entry> - jcr-sjdbc.ora.sql + <filename>jcr-sjdbc.ora.sql</filename> </entry> </row> @@ -130,7 +130,7 @@ DB2 9.7 </entry> <entry> - jcr-sjdbc.db2.sql + <filename>jcr-sjdbc.db2.sql</filename> </entry> </row> @@ -139,7 +139,7 @@ MS SQL Server </entry> <entry> - jcr-sjdbc.mssql.sql + <filename>jcr-sjdbc.mssql.sql</filename> </entry> </row> @@ -148,7 +148,7 @@ Sybase </entry> <entry> - jcr-sjdbc.sybase.sql + <filename>jcr-sjdbc.sybase.sql</filename> </entry> </row> @@ -157,7 +157,7 @@ HSQLDB </entry> <entry> - jcr-sjdbc.sql + <filename>jcr-sjdbc.sql</filename> </entry> </row> @@ -188,7 +188,7 @@ MySQL DB </entry> <entry> - jcr-mjdbc.mysql.sql + <filename>jcr-mjdbc.mysql.sql</filename> </entry> </row> @@ -197,7 +197,7 @@ MySQL DB with utf-8 </entry> <entry> - jcr-mjdbc.mysql-utf8.sql + <filename>jcr-mjdbc.mysql-utf8.sql</filename> </entry> </row> @@ -206,7 +206,7 @@ PostgresSQL </entry> <entry> - jcr-mjdbc.pqsql.sql + <filename>jcr-mjdbc.pqsql.sql</filename> </entry> </row> @@ -215,7 +215,7 @@ Oracle DB </entry> <entry> - jcr-mjdbc.ora.sql + <filename>jcr-mjdbc.ora.sql</filename> </entry> </row> @@ -224,7 +224,7 @@ DB2 9.7 </entry> <entry> - jcr-mjdbc.db2.sql + <filename>jcr-mjdbc.db2.sql</filename> </entry> </row> @@ -233,7 +233,7 @@ MS SQL Server </entry> <entry> - jcr-mjdbc.mssql.sql + <filename>jcr-mjdbc.mssql.sql</filename> </entry> </row> @@ -242,7 +242,7 @@ Sybase </entry> <entry> - jcr-mjdbc.sybase.sql + <filename>jcr-mjdbc.sybase.sql</filename> </entry> </row> @@ -251,26 +251,24 @@ HSQLDB </entry> <entry> - jcr-mjdbc.sql + <filename>jcr-mjdbc.sql</filename> </entry> - </row> - </tbody> - </tgroup> - </table> <para> - In case the non-ANSI node name is used, it's necessary to use a database with MultiLanguage support[TODO link to MultiLanguage]. Some JDBC drivers need additional parameters for establishing a Unicode friendly connection. E.g. under mysql it's necessary to add an additional parameter for the JDBC driver at the end of JDBC URL. For instance: <code>jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8<... + If a non-ANSI node name is used, you must use a database with MultiLanguage support. Some JDBC drivers need additional parameters for establishing a Unicode friendly connection. For example under mysql it is necessary to add an additional parameter for the JDBC driver at the end of JDBC URL: </para> +<example> + <title>Example Parameter</title> +<programlisting><code>jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8</code> +</programlisting> +</example> <para> - There are preconfigured configuration files for HSQLDB. Look for these files in the source-distribution of eXo JCR implementation. + By default, the configuration files are located in service jars <filename>/conf/portal/configuration.xml</filename> (eXo services including JCR Repository Service) and <filename>exo-jcr-config.xml</filename> (repositories configuration). In JBoss Enterprise Portal Platform, the JCR is configured in portal web application <filename>portal/WEB-INF/conf/jcr/jcr-configuration.xml</filename> (JCR Repository Service and related services) and <filename>repository-configuration.xml</filename> (repositories configuration). </para> <para> - By default, the configuration files are located in service jars <filename>/conf/portal/configuration.xml</filename> (eXo services including JCR Repository Service) and <filename>exo-jcr-config.xml</filename> (repositories configuration). In eXo portal product, JCR is configured in portal web application <filename>portal/WEB-INF/conf/jcr/jcr-configuration.xml</filename> (JCR Repository Service and related serivces) and repository-configuration.xml (repositories configuration). - </para> - <para> Read more about <xref linkend="sect-Reference_Guide-JCR_configuration" />. </para> @@ -279,410 +277,188 @@ <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Multi_database_Configuration"> <title>Multi-database Configuration</title> <para> - You need to configure each workspace in a repository. You may have each one on different remote servers as far as you need. + You need to configure each workspace in a repository as part of multi-database configuration. Databases may reside on remote servers as required. </para> - <para> - First of all configure the data containers in the <classname>org.exoplatform.services.naming.InitialContextInitializer</classname> service. It's the JNDI context initializer which registers (binds) naming resources (DataSources) for data containers. - </para> - <para> - For example (two data containers <parameter>jdbcjcr</parameter> - local HSQLDB, <parameter>jdbcjcr1</parameter> - remote MySQL): - </para> -<programlisting language="XML" role="XML">&lt;component&gt; - &lt;key&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/type&gt; - &lt;component-plugins&gt; - &lt;component-plugin&gt; - &lt;name&gt;bind.datasource&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;bind-name&lt;/name&gt; - &lt;value&gt;jdbcjcr&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;class-name&lt;/name&gt; - &lt;value&gt;javax.sql.DataSource&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;factory&lt;/name&gt; - &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt; - &lt;/value-param&gt; - &lt;properties-param&gt; - &lt;name&gt;ref-addresses&lt;/name&gt; - &lt;description&gt;ref-addresses&lt;/description&gt; - &lt;property name="driverClassName" value="org.hsqldb.jdbcDriver"/&gt; - &lt;property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/&gt; - &lt;property name="username" value="sa"/&gt; - &lt;property name="password" value=""/&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;component-plugin&gt; - &lt;name&gt;bind.datasource&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;bind-name&lt;/name&gt; - &lt;value&gt;jdbcjcr1&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;class-name&lt;/name&gt; - &lt;value&gt;javax.sql.DataSource&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;factory&lt;/name&gt; - &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt; - &lt;/value-param&gt; - &lt;properties-param&gt; - &lt;name&gt;ref-addresses&lt;/name&gt; - &lt;description&gt;ref-addresses&lt;/description&gt; - &lt;property name="driverClassName" value="com.mysql.jdbc.Driver"/&gt; - &lt;property name="url" value="jdbc:mysql://exoua.dnsalias.net/jcr"/&gt; - &lt;property name="username" value="exoadmin"/&gt; - &lt;property name="password" value="exo12321"/&gt; - &lt;property name="maxActive" value="50"/&gt; - &lt;property name="maxIdle" value="5"/&gt; - &lt;property name="initialSize" value="5"/&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;component-plugins&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;default-context-factory&lt;/name&gt; - &lt;value&gt;org.exoplatform.services.naming.SimpleContextFactory&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; - &lt;/component&gt; -</programlisting> - <para> - We configure the database connection parameters: - <itemizedlist> - <listitem> + <procedure> + <title></title> + <step> <para> - <parameter>driverClassName</parameter>, e.g. "org.hsqldb.jdbcDriver", "com.mysql.jdbc.Driver", "org.postgresql.Driver" + Configure the data containers in the <literal>org.exoplatform.services.naming.InitialContextInitializer</literal> service. It's the JNDI context initializer which registers (binds) naming resources (DataSources) for data containers. </para> - - </listitem> - <listitem> - <para> - <parameter>url</parameter>, e.g. "jdbc:hsqldb:file:target/temp/data/portal", "jdbc:mysql://exoua.dnsalias.net/jcr" + <para> + For example (two data containers <parameter>jdbcjcr</parameter> - local HSQLDB, <parameter>jdbcjcr1</parameter> - remote MySQL): </para> +<programlisting role="XML" language="XML"> +<xi:include parse="text" href="../../../../../extras/Advanced_Development_JCR_Configuration/example-1.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <substeps> + <step> + <para> + Configure the database connection parameters: + </para> + <itemizedlist> + <listitem> + <para> + <parameter>driverliteral</parameter>, e.g. "org.hsqldb.jdbcDriver", "com.mysql.jdbc.Driver", "org.postgresql.Driver" + </para> - </listitem> - <listitem> - <para> - <parameter>username</parameter>, e.g. "sa", "exoadmin" - </para> + </listitem> + <listitem> + <para> + <parameter>url</parameter>, e.g. "jdbc:hsqldb:file:target/temp/data/portal", "jdbc:mysql://exoua.dnsalias.net/jcr" + </para> - </listitem> - <listitem> - <para> - <parameter>password</parameter>, e.g. "", "exo12321" - </para> + </listitem> + <listitem> + <para> + <parameter>username</parameter>, e.g. "sa", "exoadmin" + </para> - </listitem> + </listitem> + <listitem> + <para> + <parameter>password</parameter>, e.g. "", "exo12321" + </para> - </itemizedlist> - </para> - <para> - There can be connection pool configuration parameters (org.apache.commons.dbcp.BasicDataSourceFactory): - <itemizedlist> - <listitem> - <para> - <parameter>maxActive</parameter>, e.g. 50 - </para> + </listitem> - </listitem> - <listitem> - <para> - <parameter>maxIdle</parameter>, e.g. 5 + </itemizedlist> + </step> + </substeps> + <para> + There can be connection pool configuration parameters (org.apache.commons.dbcp.BasicDataSourceFactory): </para> - - </listitem> - <listitem> + <itemizedlist> + <listitem> + <para> + <parameter>maxActive</parameter>, e.g. 50 + </para> + </listitem> + <listitem> + <para> + <parameter>maxIdle</parameter>, e.g. 5 + </para> + </listitem> + <listitem> + <para> + <parameter>initialSize</parameter>, e.g. 5 + </para> + </listitem> + <listitem> + <para> + and other according to <ulink url="http://jakarta.apache.org/commons/dbcp/configuration.html"... DBCP configuration</ulink> + </para> + </listitem> + </itemizedlist> + </step> + <step> <para> - <parameter>initialSize</parameter>, e.g. 5 + Configure the repository service. Each workspace will be configured for its own data container. </para> - - </listitem> - <listitem> <para> - and other according to <ulink url="http://jakarta.apache.org/commons/dbcp/configuration.html"... DBCP configuration</ulink> + For example (two workspaces <parameter>ws</parameter> - jdbcjcr, <parameter>ws1</parameter> - jdbcjcr1): </para> +<programlisting role="XML" language="XML"> +<xi:include parse="text" href="../../../../../extras/Advanced_Development_JCR_Configuration/example-2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <itemizedlist> + <listitem> + <para> + <parameter>source-name</parameter>: A javax.sql.DataSource name configured in InitialContextInitializer component (was <parameter>sourceName</parameter> prior JCR 1.9); + </para> - </listitem> + </listitem> + <listitem> + <para> + <parameter>dialect</parameter>: A database dialect, one of "hsqldb", "mysql", "mysql-utf8", "pgsql", "oracle", "oracle-oci", "mssql", "sybase", "derby", "db2", "db2v8" or "auto" for dialect autodetection; + </para> - </itemizedlist> - </para> - <para> - When the data container configuration is done, we can configure the repository service. Each workspace will be configured for its own data container. - </para> - <para> - For example (two workspaces <parameter>ws</parameter> - jdbcjcr, <parameter>ws1</parameter> - jdbcjcr1): - </para> - -<programlisting language="XML" role="XML">&lt;workspaces&gt; - &lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr"/&gt; - &lt;property name="dialect" value="hsqldb"/&gt; - &lt;property name="multi-db" value="true"/&gt; - &lt;property name="max-buffer-size" value="200K"/&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws"/&gt; - &lt;/properties&gt; - &lt;/container&gt; - &lt;cache enabled="true"&gt; - &lt;properties&gt; - &lt;property name="max-size" value="10K"/&gt;&lt;!-- 10Kbytes --&gt; - &lt;property name="live-time" value="30m"/&gt;&lt;!-- 30 min --&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="target/temp/index"/&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; - &lt;lock-manager&gt; - &lt;time-out&gt;15m&lt;/time-out&gt;&lt;!-- 15 min --&gt; - &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; - &lt;properties&gt; - &lt;property name="path" value="target/temp/lock/ws"/&gt; - &lt;/properties&gt; - &lt;/persister&gt; - &lt;/lock-manager&gt; - &lt;/workspace&gt; - &lt;workspace name="ws1" auto-init-root-nodetype="nt:unstructured"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr1"/&gt; - &lt;property name="dialect" value="mysql"/&gt; - &lt;property name="multi-db" value="true"/&gt; - &lt;property name="max-buffer-size" value="200K"/&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws1"/&gt; - &lt;/properties&gt; - &lt;/container&gt; - &lt;cache enabled="true"&gt; - &lt;properties&gt; - &lt;property name="max-size" value="10K"/&gt; - &lt;property name="live-time" value="5m"/&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="target/temp/index"/&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; - &lt;lock-manager&gt; - &lt;time-out&gt;15m&lt;/time-out&gt;&lt;!-- 15 min --&gt; - &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; - &lt;properties&gt; - &lt;property name="path" value="target/temp/lock/ws1"/&gt; - &lt;/properties&gt; - &lt;/persister&gt; - &lt;/lock-manager&gt; - &lt;/workspace&gt; -&lt;/workspaces&gt; -</programlisting> - <itemizedlist> - <listitem> - <para> - <parameter>source-name</parameter>: A javax.sql.DataSource name configured in InitialContextInitializer component (was <parameter>sourceName</parameter> prior JCR 1.9); - </para> + </listitem> + <listitem> + <para> + <parameter>multi-db</parameter>: Enable multi-database container with this parameter (set value "true"); + </para> - </listitem> - <listitem> - <para> - <parameter>dialect</parameter>: A database dialect, one of "hsqldb", "mysql", "mysql-utf8", "pgsql", "oracle", "oracle-oci", "mssql", "sybase", "derby", "db2", "db2v8" or "auto" for dialect autodetection; - </para> + </listitem> + <listitem> + <para> + <parameter>max-buffer-size: A</parameter> a threshold (in bytes) after which a javax.jcr.Value content will be swapped to a file in a temporary storage. I.e. swap for pending changes. + </para> - </listitem> - <listitem> - <para> - <parameter>multi-db</parameter>: Enable multi-database container with this parameter (set value "true"); - </para> + </listitem> + <listitem> + <para> + <parameter>swap-directory</parameter>: A path in the file system used to swap the pending changes. + </para> - </listitem> - <listitem> - <para> - <parameter>max-buffer-size: A</parameter> a threshold (in bytes) after which a javax.jcr.Value content will be swapped to a file in a temporary storage. I.e. swap for pending changes. - </para> + </listitem> - </listitem> - <listitem> - <para> - <parameter>swap-directory</parameter>: A path in the file system used to swap the pending changes. - </para> - - </listitem> - - </itemizedlist> - <para> - In this way, we have configured two workspace which will be persisted in two different databases (ws in HSQLDB, ws1 in MySQL). + </itemizedlist> + </step> + </procedure> + <para> + This procedure configures two workspace which will be persistent in two different databases (<emphasis>ws</emphasis> in HSQLDB and <emphasis>ws1</emphasis> in MySQL). </para> - <note> - <para> - Starting from v.1.9 <xref linkend="sect-Reference_Guide-JCR_configuration" /> parameters supports human-readable formats of values (e.g. 200K - 200 Kbytes, 30m - 30 minutes etc) - </para> - - </note> - + </section> <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Single_database_configuration"> - <title>Single-database configuration</title> + <title>Single-database Configuration</title> <para> - It's more simple to configure a single-database data container. We have to configure one naming resource. + Configuring a single-database data container is easier than configuring a multi-database data container as only one naming resource must be configured. </para> + +<example> + <title><parameter>jdbcjcr</parameter> Data Container</title> +<programlisting language="XML" role="XML"> +<xi:include parse="text" href="../../../../../extras/Advanced_Development_JCR_Configuration/example-3.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> +</example> <para> - For example (embedded mode for <parameter>jdbcjcr</parameter> data container): + Configure repository workspaces with this one database. The <parameter>multi-db</parameter> parameter must be set as <literal>false</literal>. </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; - &lt;target-component&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;name&gt;bind.datasource&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;bind-name&lt;/name&gt; - &lt;value&gt;jdbcjcr&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;class-name&lt;/name&gt; - &lt;value&gt;javax.sql.DataSource&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;factory&lt;/name&gt; - &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt; - &lt;/value-param&gt; - &lt;properties-param&gt; - &lt;name&gt;ref-addresses&lt;/name&gt; - &lt;description&gt;ref-addresses&lt;/description&gt; - &lt;property name="driverClassName" value="org.postgresql.Driver"/&gt; - &lt;property name="url" value="jdbc:postgresql://exoua.dnsalias.net/portal"/&gt; - &lt;property name="username" value="exoadmin"/&gt; - &lt;property name="password" value="exo12321"/&gt; - &lt;property name="maxActive" value="50"/&gt; - &lt;property name="maxIdle" value="5"/&gt; - &lt;property name="initialSize" value="5"/&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;/external-component-plugins&gt; -</programlisting> <para> - And configure repository workspaces in repositories configuration with this one database. Parameter "multi-db" must be switched off (set value "false"). - </para> - <para> For example (two workspaces <parameter>ws</parameter> - jdbcjcr, <parameter>ws1</parameter> - jdbcjcr): </para> - -<programlisting language="XML" role="XML">&lt;workspaces&gt; - &lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr"/&gt; - &lt;property name="dialect" value="pgsql"/&gt; - &lt;property name="multi-db" value="false"/&gt; - &lt;property name="max-buffer-size" value="200K"/&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws"/&gt; - &lt;/properties&gt; - &lt;/container&gt; - &lt;cache enabled="true"&gt; - &lt;properties&gt; - &lt;property name="max-size" value="10K"/&gt; - &lt;property name="live-time" value="30m"/&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="../temp/index"/&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; - &lt;lock-manager&gt; - &lt;time-out&gt;15m&lt;/time-out&gt; - &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; - &lt;properties&gt; - &lt;property name="path" value="target/temp/lock/ws"/&gt; - &lt;/properties&gt; - &lt;/persister&gt; - &lt;/lock-manager&gt; - &lt;/workspace&gt; - &lt;workspace name="ws1" auto-init-root-nodetype="nt:unstructured"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; - &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr"/&gt; - &lt;property name="dialect" value="pgsql"/&gt; - &lt;property name="multi-db" value="false"/&gt; - &lt;property name="max-buffer-size" value="200K"/&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws1"/&gt; - &lt;/properties&gt; - &lt;/container&gt; - &lt;cache enabled="true"&gt; - &lt;properties&gt; - &lt;property name="max-size" value="10K"/&gt; - &lt;property name="live-time" value="5m"/&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;lock-manager&gt; - &lt;time-out&gt;15m&lt;/time-out&gt; - &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; - &lt;properties&gt; - &lt;property name="path" value="target/temp/lock/ws1"/&gt; - &lt;/properties&gt; - &lt;/persister&gt; - &lt;/lock-manager&gt; - &lt;/workspace&gt; -&lt;/workspaces&gt; -</programlisting> +<example> + <title>Example</title> +<programlisting language="XML" role="XML"> +<xi:include parse="text" href="../../../../../extras/Advanced_Development_JCR_Configuration/example-4.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> +</example> <para> - In this way, we have configured two workspaces which will be persisted in one database (PostgreSQL). + This configures two persistent workspaces in one database (PostgreSQL). </para> <section id="sect-Reference_Guide-Single_database_configuration-Configuration_without_DataSource"> <title>Configuration without DataSource</title> <para> - Repository configuration without using of the <classname>javax.sql.DataSource</classname> bounded in JNDI. + It is possible to configure the repository without binding <literal>javax.sql.DataSource</literal> in the JNDI service if you have a dedicated JDBC driver implementation with special features like XA transactions, statements/connections pooling etc: </para> - <para> - This case may be usable if you have a dedicated JDBC driver implementation with special features like XA transactions, statements/connections pooling etc: - <itemizedlist> - <listitem> + <procedure> + <title></title> + <step> <para> - You have to remove the configuration in <classname>InitialContextInitializer</classname> for your database and configure a new one directly in the workspace container. + Remove the configuration in <literal>InitialContextInitializer</literal> for your database and configure a new one directly in the workspace container. </para> - - </listitem> - <listitem> + </step> + <step> <para> Remove parameter "source-name" and add next lines instead. Describe your values for a JDBC driver, database url and username. </para> - - </listitem> - - </itemizedlist> - </para> - <note> - <para> - But be careful in this case JDBC driver should implement and provide connection pooling. Connection pooling is very recommended for use with JCR to prevent a database overload. - </para> - - </note> + </step> + </procedure> + <warning> + <title>Connection Pooling</title> + <para> + Ensure the JDBC driver provides connection pooling. Connection pooling is strongly recommended for use with the JCR to prevent a database overload. + </para> + </warning> <programlisting language="XML" role="XML">&lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; &lt;properties&gt; &lt;property name="dialect" value="hsqldb"/&gt; - &lt;property name="driverClassName" value="org.hsqldb.jdbcDriver"/&gt; + &lt;property name="driverliteral" value="org.hsqldb.jdbcDriver"/&gt; &lt;property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/&gt; &lt;property name="username" value="su"/&gt; &lt;property name="password" value=""/&gt; ......</programlisting> - </section> <section id="sect-Reference_Guide-Single_database_configuration-Dynamic_Workspace_Creation"> @@ -692,23 +468,20 @@ </para> <para> This can be performed in two steps: - <itemizedlist> - <listitem> + </para> + <procedure> + <title></title> + <step> <para> - Firstly, <classname>ManageableRepository.configWorkspace(WorkspaceEntry wsConfig)</classname> - register a new configuration in RepositoryContainer and create a WorkspaceContainer. + <literal>ManageableRepository.configWorkspace(WorkspaceEntry wsConfig)</literal>: Register a new configuration in RepositoryContainer and create a WorkspaceContainer. </para> - - </listitem> - <listitem> + </step> + <step> <para> - Secondly, the main step, <classname>ManageableRepository.createWorkspace(String workspaceName)</classname> - creation of a new workspace. + <literal>ManageableRepository.createWorkspace(String workspaceName)</literal>: Rreation a new workspace. </para> - - </listitem> - - </itemizedlist> - </para> - + </step> + </procedure> </section> @@ -717,10 +490,29 @@ <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Simple_and_Complex_queries"> <title>Simple and Complex queries</title> <para> - eXo JCR provides two ways for interact with Database - <classname>JDBCStorageConnection</classname> that uses simple queries and <classname>CQJDBCStorageConection</classname> that uses complex queries for reducing amount of database callings. + eXo JCR provides two ways for interact with the database; </para> + <variablelist> + <title></title> + <varlistentry> + <term><literal>JDBCStorageConnection</literal></term> + <listitem> + <para> + Which uses simple queries. Simple queries do not use sub queries, left or right joins. They are implemented in such a way as to support as many database dialects as possible. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>CQJDBCStorageConection</literal></term> + <listitem> + <para> + Which uses complex queries. Complex queries are optimized to reduce the number of database calls. + </para> + </listitem> + </varlistentry> + </variablelist> <para> - Simple queries will be used if you chose <classname>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</classname>: + Simple queries will be used if you chose <literal>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</literal>: </para> <programlisting language="XML" role="XML">&lt;workspaces&gt; @@ -731,7 +523,7 @@ &lt;/worksapces&gt; </programlisting> <para> - Complex queries will be used if you chose <classname>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</classname>: + Complex queries will be used if you chose <literal>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</literal>: </para> <programlisting language="XML" role="XML">&lt;workspaces&gt; @@ -740,29 +532,16 @@ ... &lt;/workspace&gt; &lt;/worksapces&gt;</programlisting> - <para> - Why we should use a Complex Queries? - <simplelist> - <member>They are optimised to reduce amount of requests to database.</member> - </simplelist> - Why we should use a Simple Queries? - <simplelist> - <member>Simple queries implemented in way to support as many database dialects as possible.</member> - <member>Simple queries do not use sub queries, left or right joins.</member> - - </simplelist> - </para> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Forse_Query_Hints"> - <title>Forse Query Hints</title> + <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Force_Query_Hints"> + <title>Force Query Hints</title> <para> - Some databases supports hints to increase query performance (like Oracle, MySQL, etc). eXo JCR have separate Complex Query implementation for Orcale dialect, that uses query hints to increase performance for few important queries. + Some databases, such as Oracle and MySQL, support hints to increase query performance. The eXo JCR has separate Complex Query implementations for the Orcale database dialect, which uses query hints to increase performance for few important queries. </para> <para> - To enable this option put next configuration property: + To enable this option, use the following configuration property: </para> <programlisting language="XML" role="XML">&lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; @@ -771,47 +550,48 @@ &lt;property name="dialect" value="oracle"/&gt; &lt;property name="force.query.hints" value="true" /&gt; ......</programlisting> + <para> - Query hints enabled by default. + Query hints are only used for Complex Queries with the Oracle dialect. For all other dialects this parameter is ignored. </para> - <para> - eXo JCR uses query hints only for Complex Query Oracle dialect. For all other dialects this parameter is ignored. - </para> </section> <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Notes_for_Microsoft_Windows_users"> <title>Notes for Microsoft Windows users</title> <para> - The current configuration of eXo JCR uses <ulink url="http://commons.apache.org/dbcp/">Apache DBCP</ulink> connection pool (<classname>org.apache.commons.dbcp.BasicDataSourceFactory</classname>). It's possible to set a big value for maxActive parameter in <filename>configuration.xml</filename>. That means usage of lots of TCP/IP ports from a client machine inside the pool (i.e. JDBC driver). As a result, the data container can throw exceptions like "Address already in use". To solve this problem, you have to configure the client's machine networking software for the usage of shorter timeouts for opened TCP/IP ports. + The current configuration of eXo JCR uses <ulink url="http://commons.apache.org/dbcp/">Apache DBCP</ulink> connection pool (<literal>org.apache.commons.dbcp.BasicDataSourceFactory</literal>). + </para> + <para> + It is possible to set a high value for the <parameter>maxActive</parameter> parameter in the <filename>configuration.xml</filename> file. This creates a high use of TCP/IP ports from a client machine inside the pool (the JDBC driver, for example). As a result, the data container can throw exceptions like "<emphasis>Address already in use</emphasis>". + </para> + <para> + To solve this problem, you must configure the client's machine networking software to use shorter timeouts for open TCP/IP ports. </para> - <para> - Microsoft Windows has <parameter>MaxUserPort</parameter>, <parameter>TcpTimedWaitDelay</parameter> registry keys in the node <parameter>HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesTcpipParameters</parameter>, by default these keys are unset, set each one with values like these: - <itemizedlist> - <listitem> + <para> + This is done by editing two registry keys within the <parameter>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters</parameter> node. Both of these keys are unset by default. To set the keys as required: + </para> + <procedure> + <title></title> + <step> <para> - "TcpTimedWaitDelay"=dword:0000001e, sets TIME_WAIT parameter to 30 seconds, default is 240. + Set the <parameter>MaxUserPort</parameter> registry key to <parameter>=dword:00001b58</parameter>. This sets the maximum of open ports to 7000 or higher (the default is 5000). </para> - - </listitem> - <listitem> + </step> + <step> <para> - "MaxUserPort"=dword:00001b58, sets the maximum of open ports to 7000 or higher, default is 5000. + Set <parameter>TcpTimedWaitDelay</parameter> to <parameter>=dword:0000001e</parameter>. This sets <parameter>TIME_WAIT</parameter> parameter to 30 seconds (the default is 240). </para> - - </listitem> - - </itemizedlist> - </para> - <para> - A sample registry file is below: - </para> - + </step> + </procedure> +<example> + <title>Sample Registry File</title> <programlisting>Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters] "MaxUserPort"=dword:00001b58 "TcpTimedWaitDelay"=dword:0000001e</programlisting> +</example> </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/multilanguage-support.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/multilanguage-support.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/multilanguage-support.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -4,70 +4,70 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end"> - <title>Multi-language support in eXo JCR RDB back end</title> - <para> - Whenever a relational database is used to store multilingual text data in the eXo Java Content Repository the configuration must be adapted to support UTF-8 encoding. Dialect is automatically detected for certified database. You can still enforce it in case of failure, see below. - </para> - <para> - The following sections describe enabling UTF-8 support with various databases. - </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-Oracle" /> - </para> + <title>Multi-language Support the JCR RDB</title> + <para> + Whenever a relational database is used to store multilingual text data in the eXo Java Content Repository the configuration must be adapted to support UTF-8 encoding. Dialect is automatically detected for certified database. You can still enforce it in case of failure, see below. + </para> + <para> + The following sections describe enabling UTF-8 support with various databases. + </para> + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-Oracle" /> + </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-DB2" /> - </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-DB2" /> + </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-MySQL" /> - </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-MySQL" /> + </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-PostgreSQL" /> - </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-PostgreSQL" /> + </para> - </listitem> + </listitem> - </itemizedlist> - <note> - <orderedlist> - <listitem> - <para> - The configuration file to be modified for these changes is:<filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> - </para> + </itemizedlist> + <note> + <itemizedlist> + <listitem> + <para> + The configuration file to be modified for these changes is <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + </para> - </listitem> - <listitem> - <para> - The datasource <parameter>jdbcjcr</parameter> used in the following examples can be configured via the <classname>InitialContextInitializer</classname> component. - </para> + </listitem> + <listitem> + <para> + The datasource <parameter>jdbcjcr</parameter> used in the following examples can be configured via the <literal>InitialContextInitializer</literal> component. + </para> - </listitem> + </listitem> - </orderedlist> + </itemizedlist> - </note> - <section id="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-Oracle"> - <title>Oracle</title> - <para> - In order to run multilanguage JCR on an Oracle backend Unicode encoding for characters set should be applied to the database. Other Oracle globalization parameters don't make any impact. The only property to modify is <literal>NLS_CHARACTERSET</literal>. - </para> - <para> - We have tested <literal>NLS_CHARACTERSET</literal> = <literal>AL32UTF8</literal> and it works well for many European and Asian languages. - </para> - <para> - Example of database configuration (used for JCR testing): - </para> - + </note> + <section id="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-Oracle"> + <title>Oracle</title> + <para> + In order to run multilanguage JCR on an Oracle backend Unicode encoding for characters set should be applied to the database. Other Oracle globalization parameters do not have any effect. The property to modify is <literal>NLS_CHARACTERSET</literal>. + </para> + <para> + The <literal>NLS_CHARACTERSET = AL32UTF8</literal> entry has been successfully tested with many European and Asian languages. + </para> + <para> + Example of database configuration: + </para> + <programlisting>NLS_LANGUAGE AMERICAN NLS_TERRITORY AMERICA NLS_CURRENCY $ @@ -87,101 +87,101 @@ NLS_LENGTH_SEMANTICS BYTE NLS_NCHAR_CONV_EXCP FALSE NLS_NCHAR_CHARACTERSET AL16UTF16</programlisting> - <warning> - <para> - JCR 1.12.x doesn't use NVARCHAR columns, so that the value of the parameter NLS_NCHAR_CHARACTERSET does not matter for JCR. - </para> + <!--<warning> + <para> + JCR 1.12.x doesn't use NVARCHAR columns, so that the value of the parameter NLS_NCHAR_CHARACTERSET does not matter for JCR. + </para> - </warning> - <para> - Create database with Unicode encoding and use Oracle dialect for the Workspace Container: - </para> - + </warning>--> + <para> + Create database with Unicode encoding and use Oracle dialect for the Workspace Container: + </para> + <programlisting language="XML" role="XML"><xi:include href="../../../../../extras/Advanced_Development_JCR_multilanguage-support/default54.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - - <section id="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-DB2"> - <title>DB2</title> - <para> - DB2 Universal Database (DB2 UDB) supports <ulink url="http://publib.boulder.ibm.com/infocenter/db2luw/v9/index.jsp?to... and UTF-16/UCS-2</ulink>. When a Unicode database is created, <parameter>CHAR</parameter>, <parameter>VARCHAR</parameter> and <parameter>LONG VARCHAR</parameter> data are stored in UTF-8 form. - </para> - <para> - This enables JCR multi-lingual support. - </para> - <para> - Below is an example of creating a UTF-8 database using the <parameter>db2</parameter> dialect for a workspace container with DB2 version 9 and higher: - </para> - + </section> + + <section id="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-DB2"> + <title>DB2</title> + <para> + DB2 Universal Database (DB2 UDB) supports <ulink url="http://publib.boulder.ibm.com/infocenter/db2luw/v9/index.jsp?to... and UTF-16/UCS-2</ulink>. When a Unicode database is created, <parameter>CHAR</parameter>, <parameter>VARCHAR</parameter> and <parameter>LONG VARCHAR</parameter> data are stored in UTF-8 form. + </para> + <para> + This enables JCR multi-lingual support. + </para> + <para> + Below is an example of creating a UTF-8 database using the <parameter>db2</parameter> dialect for a workspace container with DB2 version 9 and higher: + </para> + <programlisting>DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US </programlisting> - + <programlisting language="XML" role="XML"><xi:include href="../../../../../extras/Advanced_Development_JCR_multilanguage-support/default56.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <note> - <para> - For DB2 version 8.<replaceable>x</replaceable> support change the property "dialect" to db2v8. - </para> + <note> + <para> + For DB2 version 8.<replaceable>x</replaceable> support change the property "dialect" to db2v8. + </para> - </note> + </note> - </section> - - <section id="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-MySQL"> - <title>MySQL</title> - <para> - Using JCR with a MySQL-back end requires a special dialect <ulink url="http://jira.exoplatform.org/browse/JCR-375">MySQL-UTF8&... to be used for internationalization support. - </para> - <para> - The database default charset should be <parameter>latin1</parameter> so as to use limited index space effectively (1000 bytes for an <literal>MyISAM</literal> engine and 767 for <literal>InnoDB</literal>). - </para> - <para> - If the database default charset is multibyte, a JCR database initialization error is encountered concerning index creation failure. - </para> - <para> - JCR can work on any single byte default charset of database, with UTF8 supported by MySQL server. However it has only been tested using the <parameter>latin1</parameter> charset. - </para> - <para> - An example entry: - </para> - + </section> + + <section id="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-MySQL"> + <title>MySQL</title> + <para> + Using JCR with a MySQL-back end requires a special dialect <ulink url="http://jira.exoplatform.org/browse/JCR-375">MySQL-UTF8&... to be used for internationalization support. + </para> + <para> + The database default charset should be <parameter>latin1</parameter> so as to use limited index space effectively (1000 bytes for an <literal>MyISAM</literal> engine and 767 for <literal>InnoDB</literal>). + </para> + <para> + If the database default charset is multibyte, a JCR database initialization error is encountered concerning index creation failure. + </para> + <para> + JCR can work on any single byte default charset of database, with UTF8 supported by MySQL server. However it has only been tested using the <parameter>latin1</parameter> charset. + </para> + <para> + An example entry: + </para> + <programlisting language="XML" role="XML"><xi:include href="../../../../../extras/Advanced_Development_JCR_multilanguage-support/default57.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - - <section id="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-PostgreSQL"> - <title>PostgreSQL</title> - <para> - Multilingual support can be enabled with a PostgreSQL-back end in <ulink url="http://www.postgresql.org/docs/8.3/interactive/charset.html&quo... ways</ulink>: - </para> - <orderedlist> - <listitem> - <para> - Using the locale features of the operating system to provide locale-specific collation order, number formatting, translated messages, and other aspects. - </para> - <para> - UTF-8 is widely used on Linux distributions by default, so it can be useful in such cases. - </para> + </section> + + <section id="sect-Reference_Guide-Multi_language_support_in_eXo_JCR_RDB_back_end-PostgreSQL"> + <title>PostgreSQL</title> + <para> + Multilingual support can be enabled with a PostgreSQL-back end in <ulink url="http://www.postgresql.org/docs/8.3/interactive/charset.html&quo... ways</ulink>: + </para> + <orderedlist> + <listitem> + <para> + Using the locale features of the operating system to provide locale-specific collation order, number formatting, translated messages, and other aspects. + </para> + <para> + UTF-8 is widely used on Linux distributions by default, so it can be useful in such cases. + </para> - </listitem> - <listitem> - <para> - Providing a number of different character sets defined in the PostgreSQL server, including multiple-byte character sets, to support storing text any language, and providing character set translation between client and server. - </para> - <para> - Using UTF-8 database charset is recommended as it will allow any-to-any conversations and make this issue transparent for the JCR. - </para> + </listitem> + <listitem> + <para> + Providing a number of different character sets defined in the PostgreSQL server, including multiple-byte character sets, to support storing text any language, and providing character set translation between client and server. + </para> + <para> + Using UTF-8 database charset is recommended as it will allow any-to-any conversations and make this issue transparent for the JCR. + </para> - </listitem> + </listitem> - </orderedlist> - <para> - Example of a database with UTF-8 encoding using PgSQL dialect for the Workspace Container: - </para> - + </orderedlist> + <para> + Example of a database with UTF-8 encoding using PgSQL dialect for the Workspace Container: + </para> + <programlisting language="XML" role="XML"><xi:include href="../../../../../extras/Advanced_Development_JCR_multilanguage-support/default58.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/rest-services-on-groovy.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/rest-services-on-groovy.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/rest-services-on-groovy.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -5,28 +5,13 @@ ]> <section id="sect-Reference_Guide-REST_Services_on_Groovy"> <title>REST Services on Groovy</title> - <section id="sect-Reference_Guide-REST_Services_on_Groovy-Concept"> - <title>Concept</title> - <para> - Starting from version 1.9, JCR Service supports REST services creation on <ulink url="http://groovy.codehaus.org">Groovy script</ulink>. - </para> - <para> - The feature bases on RESTful framework and uses ResourceContainer concept. - </para> - - </section> <section id="sect-Reference_Guide-REST_Services_on_Groovy-Usage"> <title>Usage</title> <para> - Scripts should extend ResourceContainer and should be stored in JCR as a node of type exo:groovyResourceContainer. + Groovy scripts should extend <literal>ResourceContainer</literal> and should be stored in the JCR as an <literal>exo:groovyResourceContainer</literal> node type. </para> <para> - Detailed REST services step-by-step implementation check there <remark>xref to RestServiceTutorial</remark> - <!-- <xref linkend="WS.RestServiceTutorial">RESTful - framework</link> -->. - </para> - <para> Component configuration enables Groovy services loader: </para> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/search-configuration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/search-configuration.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/search-configuration.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -9,7 +9,7 @@ The search function in JCR can be configured to perform in specific ways. This section will discuss configuring the search function to improve search performance and results. </para> <para> - Below is an example of the configuration file that governs search behaviors. Refer to <xref linkend="sect-Reference_Guide-Search_Configuration-Global_Search_Index" /> for how searching operates in JCR and discussions about customized searches. + Below is an example of the configuration file that governs search behaviors. Refer to <xref linkend="sect-Reference_Guide-Search_Configuration-Global_Search_Index" /> for how searching operates in JCR and information about customized searches. </para> <para> The JCR index configuration file is located at <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. @@ -603,9 +603,6 @@ Allows JCR to convert an existing index into the new format. It is also possible to set this property via system property. </para> <para> - For example: <command>-Dupgrade-index=true</command> - </para> - <para> Indexes prior to eXo JCR 1.12 will not run with eXo JCR 1.12. You must run an automatic migration. </para> <para> @@ -704,7 +701,7 @@ <programlisting language="XML" role="XML">&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; </programlisting> <para> - The same analyzer should always be used for indexing and for querying in lucene. Results may be unpredictable in other instances. eXo JCR does this automatically. The StandardAnalyzer (configured by default) can, however, be replaced with another. + The same analyzer should always be used for indexing and for querying in lucene otherwise results may be unpredictable. eXo JCR does this automatically. The StandardAnalyzer (configured by default) can, however, be replaced with another. </para> <para> A customized QueryHandler can also be easily created. Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/workspace-persistence-storage.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/workspace-persistence-storage.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/workspace-persistence-storage.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -4,11 +4,22 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Workspace_Data_Container"> - <title>Workspace Data Container</title> - <para> - Each Workspace of JCR has its own persistent storage to hold workspace's items data. eXo Content Repository can be configured so that it can use one or more workspaces that are logical units of the repository content. Physical data storage mechanism is configured using mandatory element <emphasis role="bold">container</emphasis>. The type of container is described in the attribute <emphasis role="bold">class</emphasis> = fully qualified name of org.exoplatform.services.jcr.storage.WorkspaceDataContainer subclass like - </para> - + <title>Workspace Data Container</title> + <para> + Each Workspace of the JCR has its own persistent storage to hold that workspace's items data. The eXo JCR can be configured so that it can use one or more workspaces that are logical units of the repository content. + </para> + <para> + The physical data storage mechanism is configured using mandatory element <emphasis role="bold">container</emphasis>. The type of container is described in the attribute <emphasis role="bold">class = <replaceable>fully qualified name of org.exoplatform.services.jcr.storage.WorkspaceDataContainer subclass</replaceable></emphasis>. For example: + </para> + +<programlistingco> + <areaspec> + <area coords="3" id="area-Reference_Guide-Workspace_Data_Container-source_name" /> + <area coords="4" id="area-Reference_Guide-Workspace_Data_Container-dialect" /> + <area coords="5" id="area-Reference_Guide-Workspace_Data_Container-multidb" /> + <area coords="6" id="area-Reference_Guide-Workspace_Data_Container-maxbuffer" /> + <area coords="7" id="area-Reference_Guide-Workspace_Data_Container-swap" /> + </areaspec> <programlisting language="XML" role="XML">&lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; &lt;properties&gt; &lt;property name="source-name" value="jdbcjcr1"/&gt; @@ -17,31 +28,55 @@ &lt;property name="max-buffer-size" value="200K"/&gt; &lt;property name="swap-directory" value="target/temp/swap/ws"/&gt; &lt;/properties&gt;</programlisting> - <para> - Properties are Container specific parameters: - </para> - <para> - <emphasis role="bold">source-name</emphasis>: JDBC data source name, registered in JDNI by InitialContextInitializer. ( <emphasis role="bold">sourceName</emphasis> prior v.1.9) - </para> - <para> - <emphasis role="bold">dialect</emphasis>: Database dialect, one of "hsqldb", "mysql", "mysql-utf8", "pgsql", "oracle", "oracle-oci", "mssql", "sybase", "derby", "db2", "db2v8" - </para> - <para> - <emphasis role="bold">multi-db</emphasis>: Enable multi-database container with this parameter (if "true"). - </para> - <para> - <emphasis role="bold">max-buffer-size</emphasis>: A threshold in bytes, if a value size is greater, then it will be spooled to a temporary file. - </para> - <para> - <emphasis role="bold">swap-directory</emphasis>: A location where the value will be spooled if no value storage is configured but a max-buffer-size is exceeded. - </para> - <para> - eXo JCR has an RDB (JDBC) based, production ready <emphasis role="bold">Workspace Data Container</emphasis>. - </para> - <para> - Workspace Data Container MAY support external storages for javax.jcr.Value (which can be the case for BLOB values for example) using the optional element <emphasis role="bold">value-storages</emphasis>. Data Container will try to read or write Value using underlying value storage plugin if the filter criteria (see below) match the current property. - </para> - + <calloutlist> + <!--#--> + <callout arearefs="area-Reference_Guide-Workspace_Data_Container-source_name"> + <para> + <literal>source-name</literal>: The JDBC data source name which is registered in JDNI by InitialContextInitializer. This was known as <literal>sourceName</literal> in versions prior to 1.9. + </para> + </callout> + <!--#--> + <callout arearefs="area-Reference_Guide-Workspace_Data_Container-dialect"> + <para> + <literal>dialect</literal>: The database dialect. Must be one of the following: <literal>hsqldb</literal>, <literal>mysql</literal>, <literal>mysql-utf8</literal>, <literal>pgsql</literal>, <literal>oracle</literal>, <literal>oracle-oci</literal>, <literal>mssql</literal>, <literal>sybase</literal>, <literal>derby</literal>, <literal>db2</literal> or <literal>db2v8</literal>). + </para> + </callout> + <!--#--> + <callout arearefs="area-Reference_Guide-Workspace_Data_Container-multidb"> + <para> + <literal>multi-db</literal>: This parameter, if <literal>true</literal>, enables multi-database container. + </para> + </callout> + <!--#--> + <callout arearefs="area-Reference_Guide-Workspace_Data_Container-maxbuffer"> + <para> + <literal>max-buffer-size</literal>: A threshold in bytes. If a value size is greater than this setting, then it will be spooled to a temporary file. + </para> + </callout> + <!--#--> + <callout arearefs="area-Reference_Guide-Workspace_Data_Container-swap"> + <para> + <literal>swap-directory</literal>: A location where the value will be spooled if no value storage is configured but a <literal>max-buffer-size</literal> is exceeded. + </para> + </callout> + </calloutlist> +</programlistingco> + + <para> + The eXo JCR has a JDBC-based, relational database, production ready <emphasis role="bold">Workspace Data Container</emphasis>. + </para> + <para> + Workspace Data Container <emphasis>may</emphasis> support external storages for <literal>javax.jcr.Value</literal> (which can be the case for BLOB values for example) using the optional element <literal>value-storages</literal>. + </para> + <para> + The Data Container will try to read or write a Value using the underlying value storage plugin if the filter criteria (see below) match the current property. + </para> + +<programlistingco> + <areaspec> + <area coords="2" id="area-Reference_Guide-Workspace_Data_Container-value_storage" /> + <area coords="6" id="area-Reference_Guide-Workspace_Data_Container-filters" /> + </areaspec> <programlisting language="XML" role="XML">&lt;value-storages&gt; &lt;value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; &lt;properties&gt; @@ -52,21 +87,29 @@ &lt;/filters&gt; ......... &lt;/value-storages&gt;</programlisting> - <para> - Where <emphasis role="bold">value-storage</emphasis> is the subclass of org.exoplatform.services.jcr.storage.value.ValueStoragePlugin and <emphasis role="bold">properties</emphasis> are optional plugin specific parameters. - </para> - <para> - <emphasis role="bold">filters</emphasis> : Each file value storage can have the filter(s) for incoming values. If there are several filter criteria, they all have to match (AND-Condition). - </para> - <para> - A filter can match values by property type (property-type), property name (property-name), ancestor path (ancestor-path) and/or the size of values stored (min-value-size, e.g. 1M, 4.2G, 100 (bytes)). - </para> - <para> - In a code sample, we use a filter with property-type and min-value-size only. That means that the storage is only for binary values whose size is greater than 1Mbyte. - </para> - <para> - It's recommended to store properties with large values in a file value storage only. - </para> -</section> - - + <calloutlist> + <!--#--> + <callout arearefs="area-Reference_Guide-Workspace_Data_Container-value_storage"> + <para> + <literal>value-storage</literal> is the subclass of <literal>org.exoplatform.services.jcr.storage.value.ValueStoragePlugin</literal> and <literal>properties</literal> are optional plugin specific parameters. + </para> + </callout> + <!--#--> + <callout arearefs="area-Reference_Guide-Workspace_Data_Container-filters"> + <para> + <literal>filters</literal>: Each file value storage can have the filter(s) for incoming values. If there are several filter criteria, they all have to match (AND-Condition). + </para> + <para> + A filter can match values by property type (property-type), property name (property-name), ancestor path (ancestor-path) and/or the size of values stored (min-value-size, e.g. 1M, 4.2G, 100 (bytes)). + </para> + <para> + In a code sample, we use a filter with property-type and min-value-size only. That means that the storage is only for binary values whose size is greater than 1Mbyte. + </para> + <para> + It's recommended to store properties with large values in a file value storage only. + </para> + </callout> + </calloutlist> +</programlistingco> + +</section> \ No newline at end of file Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/data-container.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/data-container.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/data-container.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -11,7 +11,7 @@ <itemizedlist> <listitem> <para> - Covers the requirements on Workspace Data Container implementation + Covers the requirements on Workspace Data Container implementation. </para> </listitem> @@ -23,7 +23,7 @@ </listitem> <listitem> <para> - Describes relations between container and high-level DataManagers + Describes relations between container and high-level DataManagers. </para> </listitem> </itemizedlist> @@ -128,35 +128,35 @@ <title>Read operations</title> <listitem> <para> - Read <literal>ItemData</literal> from the storage by item identifier. + Read <literal>ItemData</literal> from the storage by item identifier: </para> <programlisting language="Java" role="Java">ItemData getItemData(String identifier) throws RepositoryException, IllegalStateException; </programlisting> </listitem> <listitem> <para> - Read <literal>ItemData</literal> from the storage by using the parent and name of the item, related to the parent location. + Read <literal>ItemData</literal> from the storage by using the parent and name of the item, related to the parent location: </para> <programlisting language="Java" role="Java">ItemData getItemData(NodeData parentData, QPathEntry name) throws RepositoryException,IllegalStateException; </programlisting> </listitem> <listitem> <para> - Read List of <literal>NodeData</literal> from the storage by using the parent location of the item. + Read List of <literal>NodeData</literal> from the storage by using the parent location of the item: </para> <programlisting language="Java" role="Java">List&lt;NodeData&gt; getChildNodesData(NodeData parent) throws RepositoryException, IllegalStateException; </programlisting> </listitem> <listitem> <para> - Read List of <literal>PropertyData</literal> from the storage by using the parent location of the item. + Read List of <literal>PropertyData</literal> from the storage by using the parent location of the item: </para> <programlisting language="Java" role="Java">List&lt;PropertyData&gt; getChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException; </programlisting> </listitem> <listitem> <para> - Read List of <literal>PropertyData</literal> with empty <literal>ValueData</literal> from the storage by using the parent location of the item. + Read List of <literal>PropertyData</literal> with empty <literal>ValueData</literal> from the storage by using the parent location of the item: </para> <para> This method is specifically dedicated to non-content modification operations (Items delete, for example). @@ -166,7 +166,7 @@ </listitem> <listitem> <para> - Read List of <literal>PropertyData</literal> from the storage by using the parent location of the item. + Read List of <literal>PropertyData</literal> from the storage by using the parent location of the item: </para> <para> It's REFERENCE type: Properties referencing Node with given <literal>nodeIdentifier</literal>. See more in <literal>javax.jcr.Node.getReferences()</literal> @@ -187,42 +187,42 @@ </listitem> <listitem> <para> - Add single <literal>PropertyData</literal>. + Add single <literal>PropertyData</literal>: </para> <programlisting language="Java" role="Java">void add(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> </listitem> <listitem> <para> - Update <literal>NodeData</literal>. + Update <literal>NodeData</literal>: </para> <programlisting language="Java" role="Java">void update(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> </listitem> <listitem> <para> - Update <literal>PropertyData</literal>. + Update <literal>PropertyData</literal>: </para> <programlisting language="Java" role="Java">void update(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> </listitem> <listitem> <para> - Rename <literal>NodeData</literal> by using Node identifier and new name and indexing from the data. + Rename <literal>NodeData</literal> by using Node identifier and new name and indexing from the data: </para> <programlisting language="Java" role="Java">void rename(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> </listitem> <listitem> <para> - Delete <literal>NodeData</literal>. + Delete <literal>NodeData</literal>: </para> <programlisting language="Java" role="Java">void delete(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> </listitem> <listitem> <para> - Delete <literal>PropertyData</literal>. + Delete <literal>PropertyData</literal>: </para> <programlisting language="Java" role="Java">void delete(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> @@ -250,7 +250,7 @@ <title>State operations</title> <listitem> <para> - Return true if connection can be used. + Return true if connection can be used: </para> <programlisting language="Java" role="Java">boolean isOpened(); </programlisting> @@ -336,9 +336,9 @@ <itemizedlist> <title>Consistency of save</title> <listitem> - <para> - The container (connection) should implement consistency of Commit (Rollback) in <emphasis role="bold">transaction manner</emphasis>. I.e. If a set of operations was 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> + <para> + The container (connection) should implement consistency of Commit (Rollback) to allow a reversion of applied changes should an operation fail before a commit. + </para> </listitem> </itemizedlist> @@ -349,19 +349,19 @@ <title>Storages provider:</title> <listitem> <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: + The container implementation obtains Values Storages options via the <literal>ValueStoragePluginProvider</literal> component. The <literal>ValueStoragePluginProvider</literal> acts as a factory for 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. + Return <literal>ValueIOChannel</literal> matched this property and <literal>valueOrderNumer</literal>. Null will be returned if no channel matches. </para> <programlisting language="Java" role="Java">ValueIOChannel getApplicableChannel(PropertyData property, int valueOrderNumer) throws IOException; </programlisting> </listitem> <listitem> <para> - Return ValueIOChannel associated with given storageId. + Return <literal>ValueIOChannel</literal> associated with given storageId. </para> <programlisting language="Java" role="Java">ValueIOChannel getChannel(String storageId) throws IOException, ValueStorageNotFoundException; </programlisting> @@ -370,7 +370,7 @@ </listitem> <listitem> <para> - There is also method for consistency check, but this method doesn't used anywhere and storage implementations has it empty. + There is also a method for a consistency check, however this method is not used in this storage implementation. </para> </listitem> </itemizedlist> @@ -380,28 +380,28 @@ <title>Value storage plugin</title> <listitem> <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: + The provider implementation should use the <literal>ValueStoragePlugin</literal> abstract class as a base for all storage implementations. Plugins provide support for provider implementation methods. A plugin's methods should be implemented as follows: </para> </listitem> <listitem> <itemizedlist> <listitem> <para> - Initialize this plugin. Used at start time in ValueStoragePluginProvider. + Initialize the plugin to be used at start up in <literal>ValueStoragePluginProvider</literal>. </para> <programlisting language="Java" role="Java">public abstract void init(Properties props, ValueDataResourceHolder resources) throws RepositoryConfigurationException, IOException; </programlisting> </listitem> <listitem> <para> - Open ValueIOChannel.Used in ValueStoragePluginProvider.getApplicableChannel(PropertyData, int) and getChannel(String) + Open <literal>ValueIOChannel</literal>. Used in <literal>ValueStoragePluginProvider.getApplicableChannel(PropertyData, int)</literal> and <literal>getChannel(String)</literal>: </para> <programlisting language="Java" role="Java">public abstract ValueIOChannel openIOChannel() throws IOException; </programlisting> </listitem> <listitem> <para> - Return true if this storage has the same storageId. + Return <literal>true</literal> if this storage has the same <literal>storageId</literal>. </para> <programlisting language="Java" role="Java">public abstract boolean isSame(String valueDataDescriptor); </programlisting> @@ -415,28 +415,28 @@ <title>Value I/O channel</title> <listitem> <para> - Channel should implement ValueIOChannel interface. CRUD operation for Value Storage: + The channel should implement an <literal>ValueIOChannel</literal> interface. The CRUD operation for Value Storage are: </para> </listitem> <listitem> <itemizedlist> <listitem> <para> - Read Property value. + Read Property value: </para> <programlisting language="Java" role="Java">ValueData read(String propertyId, int orderNumber, int maxBufferSize) throws IOException; </programlisting> </listitem> <listitem> <para> - Add or update Property value. + Add or update Property value: </para> <programlisting language="Java" role="Java">void write(String propertyId, ValueData data) throws IOException; </programlisting> </listitem> <listitem> <para> - Delete Property all values. + Delete All Property values: </para> <programlisting language="Java" role="Java">void delete(String propertyId) throws IOException; </programlisting> @@ -457,14 +457,14 @@ <itemizedlist> <listitem> <para> - Commit channel changes. + Commit channel changes: </para> <programlisting language="Java" role="Java">void commit() throws IOException; </programlisting> </listitem> <listitem> <para> - Rollback channel changes. + Rollback channel changes: </para> <programlisting language="Java" role="Java">void rollback() throws IOException; </programlisting> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/repository-creation-service.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/repository-creation-service.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/repository-creation-service.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -4,68 +4,32 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-RepositoryCreationService"> - <title>RepositoryCreationService</title> + <title><literal>RepositoryCreationService</literal></title> <section id="sect-Reference_Guide-RepositoryCreationService-Intro"> <title>Intro</title> <para> - RepositoryCreationService is the service for creation repositories in runtime. + The <parameter>RepositoryCreationService</parameter> is the service for creating repositories during runtime. </para> + <procedure> + <title></title> + <step> + <para> + Execute <code>reserveRepositoryName(String repositoryName)</code>. The client-node will call the coordinator-node to reserve <literal><replaceable>repositoryName</replaceable></literal>. If the name is already reserved or a repository with the name already exists, the client-node will fetch <literal>RepositoryCreationException</literal>. Otherwise the client will get the token string. + </para> + </step> + <step> + <para> + Execute <literal>createRepository(String backupId, RepositoryEntry rEntry, String token)</literal>. The Coordinator-node will check the token, and create Repository. + </para> + </step> + <step> + <para> + When repository has been created the user-node will broadcast a message to all <literal>clusterNodes</literal> with the <literal>RepositoryEntry</literal>. Wach cluster node will start a new Repository. + </para> + </step> + </procedure> - </section> - - <!--<section id="sect-Reference_Guide-RepositoryCreationService-Dependencies"> - <title>Dependencies</title> <para> - RepositoryConfigurationService depends to next components: - </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Database_Creator" /> DBCreator used to create new database for each unbinded datasource. - </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-eXo_JCR_Backup_Service" /> BackupManager used to created repository from backup. - </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-RPC_Service" /> - RPCService used for communication between cluster-nodes - </para> - - </listitem> - - </itemizedlist> - - </section> --> - - <section id="sect-Reference_Guide-RepositoryCreationService-How_it_works"> - <title>How it works</title> - <itemizedlist> - <listitem> - <para> - User executes reserveRepositoryName(String repositoryName) - client-node calls coordinator-node to reserve repositoryName. If this name is already reserved or repository with this name exist, client-node will fetch RepositoryCreationException. If not Client will get token string. - </para> - - </listitem> - <listitem> - <para> - Then user executes createRepository(String backupId, RepositoryEntry rEntry, String token). Coordinator-node checks the token, and creates Repository. - </para> - - </listitem> - <listitem> - <para> - When repository become created - user-node broadcast message to all clusterNodes with RepositoryEntry, so each cluster node starts new Repository. - </para> - - </listitem> - - </itemizedlist> - <para> There is two ways to create repositry: make it in single step - just call createRepository(String backupId, RepositoryEntry); or reserve repositoryName at first (reserveRepositoryName(String repositoryName)), than create reserved repository (createRepository(String backupId, RepositoryEntry rEntry, String token)). </para> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/transaction-manager-lookup.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/transaction-manager-lookup.xml 2011-10-13 22:56:18 UTC (rev 7743) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/transaction-manager-lookup.xml 2011-10-14 05:24:42 UTC (rev 7744) @@ -8,7 +8,7 @@ <section id="sect-Reference_Guide-TransactionManagerLookup-Configuration"> <title>Configuration</title> <para> - It's JBossCache class registered as eXo container component in configuration.xml file. + <literal>TransactionManagerLookup</literal> is a JBossCache class registered as an eXo container component in the <filename>configuration.xml</filename> file. </para> <programlisting language="XML" role="XML"> &lt;component&gt;