[gatein-commits] gatein SVN: r7917 - in epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US: modules/Advanced/eXoJCR and 7 other directories.

Author: smumford Date: 2011-11-01 00:44:39 -0400 (Tue, 01 Nov 2011) New Revision: 7917 Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/conversationstate-when-membership-changed.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/core.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-configuration-hibernate.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-creator-service.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-schema-creator-service.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/digest-auth.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/ldap-configuration.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service-initalizer.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service-listener.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/security-service.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/spring-security-integration.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/tika-document-reader-service.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/framework-for-cross-domain-ajax.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/groovy-scripts-as-rest-services.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/introduction-to-rest.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/overwrite-default-providers.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/restservicelist-service.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/ws.xml Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/orig.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/faq/jcr-faq.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/backup-client.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/backup-clonsole-dist.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/exojcr-backup-service.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/cluster-config.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/rest-services-on-groovy.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/jbosscache-configuration-templates.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/jta.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/query-handler-config.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/aggregation-rule.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/and-constraint.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/child-node-constraint.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/date-property-comparison.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/escaping-like-statements.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/exact-path-constraint.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-all-descendant-nodes.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-all-nodes.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-by-mixin-type.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-by-primary-type.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-case-insensitive.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-similar-nodes.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/fulltext-search-by-all-properties.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/fulltext-search-by-property.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/higlight.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/ignore-accent-symbols.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/like-constraint.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/multivalue-property-comparison.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/node-name-constraint.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/node-scope-index.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/not-constraint.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/or-constraint.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-descendant.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-property.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-score.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/property-comparison.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/property-existance-constraint.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/regexp-indexing-rule.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/statistics.xml Log: Continuing edits of eXo JCR 1.14.3 docs content. Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/orig.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/orig.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/extras/Advanced_Development_JCR_Configuration/orig.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -1,3 +1,14 @@ +<repository-service default-repository="repository"> + <repositories> + <repository name="repository" system-workspace="system" default-workspace="portal-system"> + <security-domain>gatein-domain</security-domain> + <access-control>optional</access-control> + <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy> + ... + <!-- System --> + <workspaces> + ... + <!-- Portal system data --> <workspace name="portal-system"> <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/conversationstate-when-membership-changed.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/conversationstate-when-membership-changed.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/conversationstate-when-membership-changed.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,36 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.ConversationStateUserMembershipUpdated"> + <?dbhtml filename="ch-conversationstate-when-membership-changed.html"?> + + <title>Update ConversationState when user's Membership changed</title> + + <para>When a user logged in portal in ConversationRegistry added + ConversationSate for this user. ConversationState keeps user's Identity that + is actual for logged in time. In this case even user's Membership updated in + OrganizationService ConversationState still keeps old (not actual Identity). + User must logged out and loggin in again to update Identity. To fix this + issue, need add special listener in configuration of OrganizationServicer. + This listener is extended MembershipEventListener.</para> + + <para>Example of configuration.</para> + + <programlisting language="xml">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt; +&lt;configuration + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd http://www.exoplatform.org/xml/ns/kernel_1_2.xsd" + xmlns="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd"&gt; + &lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.organization.OrganizationService&lt;/target-component&gt; +..... +..... + &lt;component-plugin&gt; + &lt;name&gt;MembershipUpdateListener&lt;/name&gt; + &lt;set-method&gt;addListenerPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.organization.impl.MembershipUpdateListener&lt;/type&gt; + &lt;/component-plugin&gt; + + &lt;external-component-plugins&gt; +&lt;/configuration&gt;</programlisting> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/core.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/core.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/core.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core"> + <?dbhtml filename="ch-core.html"?> + + <title>eXo Core</title> + + <section> + <title>eXo Core introduction</title> + + <para>The eXo Core is a set of common services that are used by eXo + products and modules, it also can be used in the business logic.</para> + + <para>It's Authentication and Security, Organization, Database, Logging, + JNDI, LDAP, Document reader and other services.</para> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-configuration-hibernate.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-configuration-hibernate.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-configuration-hibernate.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,117 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.DatabaseConfigurationforHibernate"> + <?dbhtml filename="ch-db-configuration-hibernate.html"?> + + <title>Database Configuration for Hibernate</title> + + <para>As usual, it is quite simple to use our configuration XML syntax to + configure and parametrize different Databases for eXo tables but also for + your own use.</para> + + <section> + <title>Generic configuration</title> + + <para>The default DB configuration uses HSQLDB, a Java Database quite + useful for demonstrations.</para> + + <programlisting language="xml">&lt;component&gt; + &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt; + &lt;jmx-name&gt;exo-service:type=HibernateService&lt;/jmx-name&gt; + &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;hibernate.properties&lt;/name&gt; + &lt;description&gt;Default Hibernate Service&lt;/description&gt; + &lt;property name="hibernate.show_sql" value="false"/&gt; + &lt;property name="hibernate.cglib.use_reflection_optimizer" value="true"/&gt; + &lt;property name="hibernate.connection.url" value="jdbc:hsqldb:file:../temp/data/portal"/&gt; + &lt;property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/&gt; + &lt;property name="hibernate.connection.autocommit" value="true"/&gt; + &lt;property name="hibernate.connection.username" value="sa"/&gt; + &lt;property name="hibernate.connection.password" value=""/&gt; + &lt;property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/&gt; + &lt;property name="hibernate.c3p0.min_size" value="5"/&gt; + &lt;property name="hibernate.c3p0.max_size" value="20"/&gt; + &lt;property name="hibernate.c3p0.timeout" value="1800"/&gt; + &lt;property name="hibernate.c3p0.max_statements" value="50"/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</programlisting> + + <para>In the init parameter section, we define the default hibernate + properties including the DB URL, the driver and the credentials in + use.</para> + + <para>For any portals that configuration can be overridden, depending on + the needs of your environment.</para> + + <para>Several databases have been tested and can be used in + production....which is not the case of HSQLDB, HSQLDB can only be used for + development environments and for demonstrations.</para> + </section> + + <section> + <title>Example DB configuration</title> + + <para>For MySQL</para> + + <programlisting language="xml">&lt;component&gt; + &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt; + &lt;jmx-name&gt;database:type=HibernateService&lt;/jmx-name&gt; + &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;hibernate.properties&lt;/name&gt; + &lt;description&gt;Default Hibernate Service&lt;/description&gt; + &lt;property name="hibernate.show_sql" value="false"/&gt; + &lt;property name="hibernate.cglib.use_reflection_optimizer" value="true"/&gt; + &lt;property name="hibernate.connection.url" value="jdbc:mysql://localhost:3306/exodb?relaxAutoCommit=true&amp;amp;amp;autoReconnect=true&amp;amp;amp;useUnicode=true&amp;amp;amp;characterEncoding=utf8"/&gt; + &lt;property name="hibernate.connection.driver_class" value="com.mysql.jdbc.Driver"/&gt; + &lt;property name="hibernate.connection.autocommit" value="true"/&gt; + &lt;property name="hibernate.connection.username" value="exo"/&gt; + &lt;property name="hibernate.connection.password" value="exo"/&gt; + &lt;property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/&gt; + &lt;property name="hibernate.c3p0.min_size" value="5"/&gt; + &lt;property name="hibernate.c3p0.max_size" value="20"/&gt; + &lt;property name="hibernate.c3p0.timeout" value="1800"/&gt; + &lt;property name="hibernate.c3p0.max_statements" value="50"/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</programlisting> + </section> + + <section> + <title>Registering custom Hibernate XML files into the service</title> + + <para>It is possible to use the eXo hibernate service and register your + hibernate hbm.xml files to leverage some add-on features of the service + such as the table automatic creation as well as the cache of the hibernate + session in a ThreadLocal object during all the request lifecycle. To do + so, you just have to add a plugin and indicate the location of your + files.</para> + + <programlisting language="xml">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt; +&lt;configuration&gt; + &lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.database.HibernateService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;add.hibernate.mapping&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.database.impl.AddHibernateMappingPlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;values-param&gt; + &lt;name&gt;hibernate.mapping&lt;/name&gt; + &lt;value&gt;org/exoplatform/services/organization/impl/UserImpl.hbm.xml&lt;/value&gt; + &lt;value&gt;org/exoplatform/services/organization/impl/MembershipImpl.hbm.xml&lt;/value&gt; + &lt;value&gt;org/exoplatform/services/organization/impl/GroupImpl.hbm.xml&lt;/value&gt; + &lt;value&gt;org/exoplatform/services/organization/impl/MembershipTypeImpl.hbm.xml&lt;/value&gt; + &lt;value&gt;org/exoplatform/services/organization/impl/UserProfileData.hbm.xml&lt;/value&gt; + &lt;/values-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt; +&lt;/configuration&gt;</programlisting> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-creator-service.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-creator-service.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-creator-service.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,209 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.DBCreatorService"> + <?dbhtml filename="ch-db-creator-service.html"?> + + <title>Database Creator</title> + + <section> + <title>About</title> + + <para>Database creator<envar> DBCreator</envar> is responsible for + execution DDL script in runtime. A DDL script may contain templates for + database name, user name and password which will be replaced by real + values at execution time.</para> + + <para>Three templates supported:</para> + + <itemizedlist> + <listitem> + <para><envar>${database}</envar> for database name;</para> + </listitem> + + <listitem> + <para><envar>${username}</envar> for user name;</para> + </listitem> + + <listitem> + <para><envar>${password}</envar> for user's password;</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>API</title> + + <para>Service provide method for execute script for new database creation. + Database name which are passed as parameter will be substituted in DDL + script instead of <envar>${database}</envar> template. Returns + <envar>DBConnectionInfo</envar> object (with all neccesary information of + new database's connection) or throws <envar>DBCreatorException</envar> + exception if any errors occurs in other case.</para> + + <programlisting language="java">public DBConnectionInfo createDatabase(String dbName) throws DBCreatorException; +</programlisting> + + <para>For MSSQL and Sybase servers, use autocommit mode to set true for + connection. It's due to after execution "create database" command newly + created database not available for "use" command and therefore you can't + create new user inside database per one script.</para> + + <programlisting language="java">public DBConnectionInfo getDBConnectionInfo(String dbName) throws DBCreatorException; +</programlisting> + + <para>Return database connection information without database + creation.</para> + </section> + + <section> + <title>A configuration examples</title> + + <para>Service's configuration.</para> + + <programlisting language="xml"> &lt;component&gt; + &lt;key&gt;org.exoplatform.services.database.creator.DBCreator&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.database.creator.DBCreator&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;db-connection&lt;/name&gt; + &lt;description&gt;database connection properties&lt;/description&gt; + &lt;property name="driverClassName" value="com.mysql.jdbc.Driver" /&gt; + &lt;property name="url" value="jdbc:mysql://localhost/" /&gt; + &lt;property name="username" value="root" /&gt; + &lt;property name="password" value="admin" /&gt; + &lt;property name="additional_property" value="value"&gt; + ... + &lt;property name="additional_property_n" value="value"&gt; + &lt;/properties-param&gt; + &lt;properties-param&gt; + &lt;name&gt;db-creation&lt;/name&gt;. + &lt;description&gt;database creation properties&lt;/description&gt;. + &lt;property name="scriptPath" value="script.sql" /&gt; + &lt;property name="username" value="testuser" /&gt; + &lt;property name="password" value="testpwd" /&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component&gt;</programlisting> + + <para><envar>db-connection</envar> properties section contains parameters + needed for connection to database server</para> + + <para>There is four reserved and mandatory properties + <emphasis>driverClassName</emphasis>, <emphasis>url</emphasis>, + <emphasis>username</emphasis> and <emphasis>password</emphasis>. But + db-connection may contain additonal properties.</para> + + <para>For example, next additional proprites allows reconnect to MySQL + database when connection was refused:</para> + + <programlisting language="xml"> &lt;properties-param&gt; + &lt;name&gt;db-connection&lt;/name&gt; + ... + &lt;property name="validationQuery" value="select 1"/&gt; + &lt;property name="testOnReturn" value="true"/&gt; + ... + &lt;/properties-param&gt;</programlisting> + + <para><envar>db-creation</envar> properties section contains paramaters + for database creation using DDL script:</para> + + <itemizedlist> + <listitem> + <para><envar>scriptPath</envar>: absolute path to DDL script + file;</para> + </listitem> + + <listitem> + <para><envar>username:</envar> user name for substitution + <envar>${username}</envar> template in DDL script;</para> + </listitem> + + <listitem> + <para><envar>password</envar>: user's password for substitution + <envar>${password}</envar> template in DDL script;</para> + </listitem> + </itemizedlist> + + <para>Specific <envar>db-connection</envar> properties section for + different databases.</para> + + <para>MySQL:</para> + + <programlisting language="xml">&lt;property name="driverClassName" value="com.mysql.jdbc.Driver" /&gt; +&lt;property name="url" value="jdbc:mysql://localhost/" /&gt; +&lt;property name="username" value="root" /&gt; +&lt;property name="password" value="admin" /&gt;</programlisting> + + <para>PostgreSQL:</para> + + <programlisting language="xml">&lt;property name="driverClassName" value="org.postgresql.Driver" /&gt; +&lt;property name="url" value="jdbc:postgresql://localhost/" /&gt; +&lt;property name="username" value="root" /&gt; +&lt;property name="password" value="admin" /&gt;</programlisting> + + <para>MSSQL:</para> + + <programlisting language="xml">&lt;property name="driverClassName" value="com.microsoft.sqlserver.jdbc.SQLServerDriver"/&gt; +&lt;property name="url" value="jdbc:sqlserver://localhost:1433;"/&gt; +&lt;property name="username" value="root"/&gt; +&lt;property name="password" value="admin"/&gt;</programlisting> + + <para>Sybase:</para> + + <programlisting language="xml">&lt;property name="driverClassName" value="com.sybase.jdbc3.jdbc.SybDriver" /&gt; +&lt;property name="url" value="jdbc:sybase:Tds:localhost:5000/"/&gt; +&lt;property name="username" value="root"/&gt; +&lt;property name="password" value="admin"/&gt;</programlisting> + + <para>Oracle:</para> + + <programlisting language="xml">&lt;property name="driverClassName" value="oracle.jdbc.OracleDriver" /&gt; +&lt;property name="url" value="jdbc:oracle:thin:@db2.exoua-int:1521:orclvm" /&gt; +&lt;property name="username" value="root" /&gt; +&lt;property name="password" value="admin" /&gt;</programlisting> + </section> + + <section> + <title>An examples of a DDL script</title> + + <para>MySQL:</para> + + <programlisting>CREATE DATABASE ${database}; +USE ${database}; +CREATE USER '${username}' IDENTIFIED BY '${password}'; +GRANT SELECT,INSERT,UPDATE,DELETE ON ${database}.* TO '${username}';</programlisting> + + <para>PostgreSQL:</para> + + <programlisting>CREATE USER ${username} WITH PASSWORD '${password}'; +CREATE DATABASE ${database} WITH OWNER ${username};</programlisting> + + <para>MSSQL:</para> + + <programlisting>USE MASTER; +CREATE DATABASE ${database}; +USE ${database}; +CREATE LOGIN ${username} WITH PASSWORD = '${password}'; +CREATE USER ${username} FOR LOGIN ${username};</programlisting> + + <para>Sybase:</para> + + <programlisting>sp_addlogin ${username}, ${password}; +CREATE DATABASE ${database}; +USE ${database}; +sp_adduser ${username};</programlisting> + + <para>Oracle:</para> + + <programlisting>CREATE TABLESPACE "${database}" DATAFILE '/var/oracle_db/orclvm/${database}' SIZE 10M AUTOEXTEND ON NEXT 6M MAXSIZE UNLIMITED LOGGING EXTENT MANAGEMENT LOCAL SEGMENT SPACE MANAGEMENT AUTO; +CREATE TEMPORARY TABLESPACE "${database}.TEMP" TEMPFILE '/var/oracle_db/orclvm/${database}.temp' SIZE 5M AUTOEXTEND ON NEXT 5M MAXSIZE UNLIMITED EXTENT MANAGEMENT LOCAL UNIFORM SIZE 1M; +CREATE USER "${username}" PROFILE "DEFAULT" IDENTIFIED BY "${password}" DEFAULT TABLESPACE "${database}" TEMPORARY TABLESPACE "${database}.TEMP" ACCOUNT UNLOCK; +GRANT CREATE SEQUENCE TO "${username}"; +GRANT CREATE TABLE TO "${username}"; +GRANT CREATE TRIGGER TO "${username}"; +GRANT UNLIMITED TABLESPACE TO "${username}"; +GRANT "CONNECT" TO "${username}"; +GRANT "RESOURCE" TO "${username}";</programlisting> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-schema-creator-service.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-schema-creator-service.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/db-schema-creator-service.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.DBSchemacreatorserviceJDBCimplementation"> + <?dbhtml filename="ch-db-schema-creator-service.html"?> + + <title>DB Schema creator service (JDBC implementation)</title> + + <para>DB Schema Creator is responsible for creating database schema, using a + DDL script inside service configuration or in an external file, + calling:</para> + + <programlisting language="java"> org.exoplatform.services.database.jdbc.DBSchemaCreator.createTables(String dsName, String script)</programlisting> + + <para>via</para> + + <programlisting>org.exoplatform.services.database.jdbc.CreateDBSchemaPlugin component plugin</programlisting> + + <para>A configuration example:</para> + + <programlisting language="xml">&lt;component&gt; + &lt;key&gt;org.exoplatform.services.database.jdbc.DBSchemaCreator&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.database.jdbc.DBSchemaCreator&lt;/type&gt; + &lt;component-plugins&gt; + &lt;component-plugin&gt; + &lt;name&gt;jcr.dbschema&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.database.jdbc.CreateDBSchemaPlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;data-source&lt;/name&gt; + &lt;value&gt;jdbcjcr&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;script-file&lt;/name&gt; + &lt;value&gt;conf/storage/jcr-mjdbc.sql&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + ........</programlisting> + + <para>An example of a DDL script:</para> + + <programlisting>CREATE TABLE JCR_MITEM( + ID VARCHAR(255) NOT NULL PRIMARY KEY, + VERSION INTEGER NOT NULL, + PATH VARCHAR(1024) NOT NULL + ); +CREATE INDEX JCR_IDX_MITEM_PATH ON JCR_MITEM(PATH);</programlisting> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/digest-auth.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/digest-auth.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/digest-auth.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,166 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter> + <title>Digest Authentication</title> + + <section> + <title>Overview</title> + + <para>Digest access authentication is one of the agreed methods a web + server can use to negotiate credentials with a web user's browser. It uses + encryption to send the password over the network which is safer than the + Basic access authentication that sends plaintext.</para> + + <para>Technically digest authentication is an application of MD5 + cryptographic hashing with usage of nonce values to discourage + cryptanalysis. It uses the HTTP protocol.</para> + </section> + + <section> + <title>Server configuration</title> + + <para>To configure you server to use DIGEST authentication we need to edit + serverside JAAS module implementation configuration file.</para> + + <section> + <title>Tomcat Server configuration</title> + + <para>You need to fulfill a couple of steps. Firstly change login + configuration:</para> + + <para>Edit config file located here: + exo-tomcat/webapps/rest.war/WEB-INF/web.xml</para> + + <para>Replace</para> + + <para><programlisting>&lt;login-config&gt; + &lt;auth-method&gt;BASIC&lt;/auth-method&gt; + &lt;realm-name&gt;eXo REST services&lt;/realm-name&gt; +&lt;/login-config&gt;</programlisting>for</para> + + <para><programlisting>&lt;login-config&gt; + &lt;auth-method&gt;DIGEST&lt;/auth-method&gt; + &lt;realm-name&gt;eXo REST services&lt;/realm-name&gt; +&lt;/login-config&gt;</programlisting>More information about tomcat + configuration can be found at <ulink + url="http://tomcat.apache.org/tomcat-6.0-doc/config/realm.html"... + Tomcat Configuration Reference</ulink>.</para> + + <para>Secondly you also need to specify new login module for + JAAS:</para> + + <para>Edit config file located here: exo-tomcat/conf/jaas.conf</para> + + <para>Replace</para> + + <para><programlisting>exo-domain { + org.exoplatform.services.security.j2ee.TomcatLoginModule required; +};</programlisting>for</para> + + <para><programlisting>exo-domain { + org.exoplatform.services.security.j2ee.DigestAuthenticationTomcatLoginModule required; +};</programlisting></para> + </section> + + <section> + <title>Jetty server configuration</title> + + <para>You need to fulfill a couple of steps. Firstly change login + configuration:</para> + + <para>Edit config file located here: + exo-jetty/webapps/rest.war/WEB-INF/web.xml</para> + + <para>Replace</para> + + <para><programlisting>&lt;login-config&gt; + &lt;auth-method&gt;BASIC&lt;/auth-method&gt; + &lt;realm-name&gt;eXo REST services&lt;/realm-name&gt; +&lt;/login-config&gt;</programlisting>for</para> + + <para><programlisting>&lt;login-config&gt; + &lt;auth-method&gt;DIGEST&lt;/auth-method&gt; + &lt;realm-name&gt;eXo REST services&lt;/realm-name&gt; +&lt;/login-config&gt;</programlisting>Secondly you also need to specify new + login module for JAAS:</para> + + <para>Edit config file located here: exo-jetty/jaas.conf</para> + + <para>Replace</para> + + <para><programlisting>exo-domain { + org.exoplatform.services.security.j2ee.JettyLoginModule required; +};</programlisting>for</para> + + <para><programlisting>exo-domain { + org.exoplatform.services.security.j2ee.DigestAuthenticationJettyLoginModule required; +};</programlisting></para> + </section> + + <section> + <title>JBoss server configuration</title> + + <para>Edit config file located here: + exo-jboss/server/default/deploy/exo.jcr.ear.ear/rest.war/WEB-INF/web.xml</para> + + <para>Replace</para> + + <para><programlisting>&lt;login-config&gt; + &lt;auth-method&gt;BASIC&lt;/auth-method&gt; + &lt;realm-name&gt;eXo REST services&lt;/realm-name&gt; +&lt;/login-config&gt;</programlisting>for</para> + + <para><programlisting>&lt;login-config&gt; + &lt;auth-method&gt;DIGEST&lt;/auth-method&gt; + &lt;realm-name&gt;eXo REST services&lt;/realm-name&gt; +&lt;/login-confi</programlisting></para> + + <para>You also need to edit login configuration file located here: + exo-jboss/server/default/conf/login-config.xml</para> + + <para><programlisting>&lt;application-policy name="exo-domain"&gt; + &lt;authentication&gt; + &lt;login-module code="org.exoplatform.services.security.j2ee.DigestAuthenticationJbossLoginModule" + flag="required"&gt; + &lt;module-option name="usersProperties"&gt;props/jmx-console-users.properties&lt;/module-option&gt; + &lt;module-option name="rolesProperties"&gt;props/jmx-console-roles.properties&lt;/module-option&gt; + &lt;module-option name="hashAlgorithm"&gt;MD5&lt;/module-option&gt; + &lt;module-option name="hashEncoding"&gt;rfc2617&lt;/module-option&gt; + &lt;module-option name="hashUserPassword"&gt;false&lt;/module-option&gt; + &lt;module-option name="hashStorePassword"&gt;true&lt;/module-option&gt; + &lt;module-option name="passwordIsA1Hash"&gt;true&lt;/module-option&gt; + &lt;module-option name="storeDigestCallback"&gt; + org.jboss.security.auth.spi.RFC2617Digest + &lt;/module-option&gt; + &lt;/login-module&gt; + &lt;/authentication&gt; +&lt;/application-policy&gt;</programlisting>You probably should define + users.properties and role.properties according to your own needs.</para> + + <para>More information about jboss server Digest authentication + configuration can be found at <ulink + url="http://docs.jboss.org/jbossas/guides/webguide/r2/en/html/ch05.h... + quide chapter</ulink>.</para> + </section> + </section> + + <section> + <title>OrganizationService implementation requirements</title> + + <para>To make your own + <literal>org.exoplatform.services.organization.OrganizationService</literal> + implementation able to use DIGEST authentication you need to make your + UserHandler implementation also implement + <literal>org.exoplatform.services.organization.DigestAuthenticator</literal> + interface which provide more flexible authenticate method. As it is called + from + <literal>org.exoplatform.services.organization.auth.OrganizationAuthenticatorImpl</literal> + it receive a + <literal>org.exoplatform.services.security.Credential</literal> instances, + you can get more information from + <literal>org.exoplatform.services.security.PasswordCredential.getPasswordContext()</literal>. + It can be used to calculate md5 digest of original password to compare it + with recieved from clientside.</para> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/ldap-configuration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/ldap-configuration.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/ldap-configuration.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,867 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.LDAPConfiguration"> + <?dbhtml filename="ch-ldap-configuration.html"?> + + <title>LDAP Configuration</title> + + <section> + <title>Overview</title> + + <para>You may decide that you want eXo users to be mapped to an existing + directory. eXo provides a flexible implementation of its + OrganizationService on top of LDAP. It can be used on any LDAP compliant + directory and even Active Directory. This page will guide you how to + configure eXo Platform to work with your directory.</para> + </section> + + <section> + <title>Quickstart</title> + + <para>If you just want to have a look at how eXo works with ldap. eXo + comes with a predefined ldap configuration. You just need to activate it + and eXo will create all it needs to work at startup.</para> + + <para>You need to have a working ldap server and a user with write + permissions.</para> + + <itemizedlist> + <listitem> + <para>Open <emphasis + role="bold">exo-tomcat/webapps/portal/WEB-INF/conf/configuration.xml</emphasis> + and replace:</para> + </listitem> + </itemizedlist> + + <programlisting language="xml">&lt;import&gt;war:/conf/organization/hibernate-configuration.xml&lt;/import&gt;</programlisting> + + <para>With</para> + + <programlisting language="xml">&lt;import&gt;war:/conf/organization/ldap-configuration.xml&lt;/import&gt;</programlisting> + + <itemizedlist> + <listitem> + <para>0pen <emphasis role="bold">ldap-configuration.xml</emphasis> and + update the <emphasis role="bold">providerURL</emphasis>, <emphasis + role="bold">rootdn</emphasis> and password settings according to your + environment</para> + </listitem> + </itemizedlist> + + <programlisting language="xml">&lt;field name="providerURL"&gt;&lt;string&gt;ldap://127.0.0.1:389&lt;/string&gt;&lt;/field&gt; +&lt;field name="rootdn"&gt;&lt;string&gt;CN=Manager,DC=MyCompany,DC=com&lt;/string&gt;&lt;/field&gt; +&lt;field name="password"&gt;&lt;string&gt;secret&lt;/string&gt;&lt;/field&gt;</programlisting> + + <itemizedlist> + <listitem> + <para>Delete <emphasis role="bold">exo-tomcat/temp/</emphasis>* to + have a clean database and then start tomcat.</para> + </listitem> + </itemizedlist> + + <para>eXo starts and autocreates its organization model in your directory + tree. Finally, the structure of the default LDAP schema looks like:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/organization-exo.jpg" /> + </imageobject> + </mediaobject> + + <para>That's it! Now eXo uses your LDAP directory as its org model + storage. Users, groups and memberships are now stored and retrieved from + there. We suggest that you complete some guideline functions with eXo user + management portlet and see what it changes in your directory tree.</para> + </section> + + <section> + <title>Configuration</title> + + <para>If you have an existing LDAP server, the eXo predefined settings + will likely not match your directory structure. eXo LDAP organization + service implementation was written with flexibility in mind and can + certainly be configured to meet your requirements.</para> + + <para>The configuration is done in <emphasis + role="bold">ldap-configuration.xml</emphasis> file, and this chapter will + explain the numerous parameters it contains.</para> + + <section> + <title>Connection Settings</title> + + <para>Firstly, start by connection settings which will tell eXo how to + connect to your directory server. These settings are very close to + <ulink url="http://java.sun.com/products/jndi">JNDI API</ulink> context + parameters. This configuration is activated by the init-param + ldap.config of service LDAPServiceImpl.</para> + + <programlisting language="xml">&lt;component&gt; + &lt;key&gt;org.exoplatform.services.ldap.LDAPService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.ldap.impl.LDAPServiceImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;object-param&gt; + &lt;name&gt;ldap.config&lt;/name&gt; + &lt;description&gt;Default ldap config&lt;/description&gt; + &lt;object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig"&gt; + &lt;field name="providerURL"&gt;&lt;string&gt;ldap://127.0.0.1:389,10.0.0.1:389&lt;/string&gt;&lt;/field&gt; + &lt;field name="rootdn"&gt;&lt;string&gt;CN=Manager,DC=exoplatform,DC=org&lt;/string&gt;&lt;/field&gt; + &lt;field name="password"&gt;&lt;string&gt;secret&lt;/string&gt;&lt;/field&gt; + &lt;!-- field name="authenticationType"&gt;&lt;string&gt;simple&lt;/string&gt;&lt;/field--&gt; + &lt;field name="version"&gt;&lt;string&gt;3&lt;/string&gt;&lt;/field&gt; + &lt;field name="referralMode"&gt;&lt;string&gt;follow&lt;/string&gt;&lt;/field&gt; + &lt;!-- field name="serverName"&gt;&lt;string&gt;active.directory&lt;/string&gt;&lt;/field--&gt; + &lt;field name="minConnection"&gt;&lt;int&gt;5&lt;/int&gt;&lt;/field&gt; + &lt;field name="maxConnection"&gt;&lt;int&gt;10&lt;/int&gt;&lt;/field&gt; + &lt;field name="timeout"&gt;&lt;int&gt;50000&lt;/int&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">providerURL</emphasis>: LDAP server URL + (see <ulink + url="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/Cont...>). + For multiple ldap servers, use comma separated list of host:port + (Ex. ldap://127.0.0.1:389,10.0.0.1:389).</para> + </listitem> + + <listitem> + <para><emphasis role="bold">rootdn</emphasis>: dn of user that will + be used by the service to authenticate on the server (see <ulink + url="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/Cont... + </listitem> + + <listitem> + <para><emphasis role="bold">password</emphasis>: password for user + rootdn (see <ulink + url="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/Cont... + </listitem> + + <listitem> + <para><emphasis role="bold">authenticationType</emphasis>: type of + authentication to be used (see <ulink + url="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/Cont...>). + Use one of none, simple, strong. Default is simple.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">version</emphasis>: LDAP protocol + version (see <ulink + url="http://java.sun.com/products/jndi/tutorial/ldap/misc/version.ht...>). + Set to 3 if your server supports LDAP V3.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">referalMode</emphasis>: one of follow, + ignore,throw (see <ulink + url="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/Cont... + </listitem> + + <listitem> + <para><emphasis role="bold">serverName</emphasis>: you will need to + set this to active.directory in order to work with Active Directory + servers. Any other value will be ignore and the service will act as + on a standard LDAP.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">maxConnection</emphasis>: the maximum + number of connections per connection identity that can be maintained + concurrently.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">minConnection</emphasis>: the number of + connections per connection identity to create when initially + creating a connection for the identity.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">timeout</emphasis>: the number of + milliseconds that an idle connection may remain in the pool without + being closed and removed from the pool.</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Organization Service Configuration</title> + + <para>Next, you need to configure the eXo <emphasis + role="bold">OrganizationService</emphasis> to tell him how the directory + is structured and how to interact with it. This is managed by a couple + of of init-params : <emphasis role="bold">ldap.userDN.key</emphasis> and + <emphasis role="bold">ldap.attribute.mapping</emphasis> in file + <emphasis role="bold">ldap-configuration.xml</emphasis> (by default + located at portal.war/WEB-INF/conf/organization)</para> + + <programlisting language="xml">&lt;component&gt; + &lt;key&gt;org.exoplatform.services.organization.OrganizationService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.organization.ldap.OrganizationServiceImpl&lt;/type&gt; + [...] + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;ldap.userDN.key&lt;/name&gt; + &lt;description&gt;The key used to compose user DN&lt;/description&gt; + &lt;value&gt;cn&lt;/value&gt; + &lt;/value-param&gt; + &lt;object-param&gt; + &lt;name&gt;ldap.attribute.mapping&lt;/name&gt; + &lt;description&gt;ldap attribute mapping&lt;/description&gt; + &lt;object type="org.exoplatform.services.organization.ldap.LDAPAttributeMapping"&gt; + [...] + &lt;/object-param&gt; + &lt;/init-params&gt; + [...] +&lt;/component&gt;</programlisting> + + <para><emphasis role="bold">ldap.attribute.mapping</emphasis> maps your + ldap to eXo. At first there are two main parameters to configure in + it:</para> + + <programlisting language="xml">&lt;field name="baseURL"&gt;&lt;string&gt;dc=exoplatform,dc=org&lt;/string&gt;&lt;/field&gt; +&lt;field name="ldapDescriptionAttr"&gt;&lt;string&gt;description&lt;/string&gt;&lt;/field&gt;</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">baseURL</emphasis>: root dn for eXo + organizational entities. This entry can't be created by eXo and must + preexist in directory.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">ldapDescriptionAttr</emphasis> (since + core 2.2+) : Name of a common attribute that will be used as + description for groups and membership types.</para> + </listitem> + </itemizedlist> + + <note> + <para>(since core 2.2+) : Name of a common attribute that will be used + as description for groups and membership types.</para> + </note> + + <para>Other parameters are discussed in the following sections.</para> + + <section> + <title>Users</title> + + <section> + <title>Main parameters</title> + + <para>Here are the main parameters to map eXo users to your + directory :</para> + + <programlisting language="xml">&lt;field name="userURL"&gt;&lt;string&gt;ou=users,ou=portal,dc=exoplatform,dc=org&lt;/string&gt;&lt;/field&gt; +&lt;field name="userObjectClassFilter"&gt;&lt;string&gt;objectClass=person&lt;/string&gt;&lt;/field&gt; +&lt;field name="userLDAPClasses"&gt;&lt;string&gt;top,person,organizationalPerson,inetOrgPerson&lt;/string&gt;&lt;/field&gt;</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">userURL</emphasis> : base dn for + users. Users are created in a flat structure under this base + with a dn of the form: <emphasis + role="bold">ldap.userDN.key=username,userURL</emphasis></para> + </listitem> + </itemizedlist> + + <para>Example :</para> + + <programlisting>uid=john,cn=People,o=MyCompany,c=com</programlisting> + + <para>However, if users exist deeply under userURL, eXo will be able + to retrieve them.</para> + + <para>Example :</para> + + <programlisting>uid=tom,ou=France,ou=EMEA,cn=People,o=MyCompany,c=com</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">userObjectClassFilter</emphasis>: + Filter used under userURL branch to distinguish eXo user entries + from others.</para> + </listitem> + </itemizedlist> + + <para>Example : john and tom will be recognized as valid eXo users + but EMEA and France entries will be ignored in the following subtree + :</para> + + <programlisting>uid=john,cn=People,o=MyCompany,c=com + objectClass: person + … +ou=EMEA,cn=People,o=MyCompany,c=com + objectClass: organizationalUnit + … + ou=France,ou=EMEA,cn=People,o=MyCompany,c=com + objectClass: organizationalUnit + … + uid=tom,ou=EMEA,cn=People,o=MyCompany,c=com + objectClass: person + …</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">userLDAPClasses</emphasis> : comma + separated list of classes used for user creation.</para> + </listitem> + </itemizedlist> + + <para>When creating a new user, an entry will be created with the + given objectClass attributes. The classes must at least define cn + and any attribute refernced in the user mapping.</para> + + <para>Example : Adding the user Marry Simons could produce :</para> + + <programlisting>uid=marry,cn=users,ou=portal,dc=exoplatform,dc=org + objectclass: top + objectClass: person + objectClass: organizationalPerson + objectClass: inetOrgPerson + …</programlisting> + </section> + + <section> + <title>User mapping</title> + + <para>The following parameters maps ldap attributes to eXo User java + objects attributes.</para> + + <programlisting language="xml">&lt;field name="userUsernameAttr"&gt;&lt;string&gt;uid&lt;/string&gt;&lt;/field&gt; +&lt;field name="userPassword"&gt;&lt;string&gt;userPassword&lt;/string&gt;&lt;/field&gt; +&lt;field name="userFirstNameAttr"&gt;&lt;string&gt;givenName&lt;/string&gt;&lt;/field&gt; +&lt;field name="userLastNameAttr"&gt;&lt;string&gt;sn&lt;/string&gt;&lt;/field&gt; +&lt;field name="userDisplayNameAttr"&gt;&lt;string&gt;displayName&lt;/string&gt;&lt;/field&gt; +&lt;field name="userMailAttr"&gt;&lt;string&gt;mail&lt;/string&gt;&lt;/field&gt;</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">userUsernameAttr</emphasis>: + username (login)</para> + </listitem> + + <listitem> + <para><emphasis role="bold">userPassword</emphasis>: password + (used when portal authentication is done by eXo login + module)</para> + </listitem> + + <listitem> + <para><emphasis role="bold">userFirstNameAttr</emphasis>: + firstname</para> + </listitem> + + <listitem> + <para><emphasis role="bold">userLastNameAttr</emphasis>: + lastname</para> + </listitem> + + <listitem> + <para><emphasis role="bold">userDisplayNameAttr</emphasis>: + displayed name</para> + </listitem> + + <listitem> + <para><emphasis role="bold">userMailAttr</emphasis>: email + address</para> + </listitem> + </itemizedlist> + + <para>Example : In the previous example, user Marry Simons could + produce :</para> + + <programlisting>uid=marry,cn=users,ou=portal,dc=exoplatform,dc=org + objectclass: top + objectClass: person + objectClass: organizationalPerson + objectClass: inetOrgPerson + …</programlisting> + </section> + </section> + + <section> + <title>Groups</title> + + <para>eXo groups can be mapped to organizational or applicative groups + defined in your directory.</para> + + <programlisting language="xml">&lt;field name="groupsURL"&gt;&lt;string&gt;ou=groups,ou=portal,dc=exoplatform,dc=org&lt;/string&gt;&lt;/field&gt; +&lt;field name="groupLDAPClasses"&gt;&lt;string&gt;top,organizationalUnit&lt;/string&gt;&lt;/field&gt; +&lt;field name="groupObjectClassFilter"&gt;&lt;string&gt;objectClass=organizationalUnit&lt;/string&gt;&lt;/field&gt;</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">groupsURL</emphasis> : base dn for eXo + groups</para> + </listitem> + </itemizedlist> + + <para>Groups can be structured hierarchically under groupsURL.</para> + + <para>Example: Groups communication, communication/marketing and + communication/press would map to :</para> + + <programlisting>ou=communication,ou=groups,ou=portal,dc=exoplatform,dc=org +… + ou=marketing,ou=communication,ou=groups,ou=portal,dc=exoplatform,dc=org + … + ou=press,ou=communication,ou=groups,ou=portal,dc=exoplatform,dc=org + …</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">groupLDAPClasses</emphasis>: comma + separated list of classes used for group creation.</para> + </listitem> + </itemizedlist> + + <para>When creating a new group, an entry will be created with the + given objectClass attributes. The classes must define at least the + required attributes: <emphasis role="bold">ou</emphasis>, <emphasis + role="bold">description</emphasis> and <emphasis + role="bold">l</emphasis>.</para> + + <note> + <para>l attribute corresponds to the City property in OU property + editor</para> + </note> + + <para>Example : Adding the group human-resources could produce:</para> + + <programlisting>ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org + objectclass: top + objectClass: organizationalunit + ou: human-resources + description: The human resources department + l: Human Resources + …</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">groupObjectClassFilter</emphasis>: + filter used under groupsURL branch to distinguish eXo groups from + other entries. You can also use a complex filter if you + need.</para> + </listitem> + </itemizedlist> + + <para>Example : groups WebDesign, WebDesign/Graphists and Sales could + be retrieved in :</para> + + <programlisting>l=Paris,dc=sites,dc=mycompany,dc=com + … + ou=WebDesign,l=Paris,dc=sites,dc=mycompany,dc=com + … + ou=Graphists,WebDesign,l=Paris,dc=sites,dc=mycompany,dc=com + … +l=London,dc=sites,dc=mycompany,dc=com + … + ou=Sales,l=London,dc=sites,dc=mycompany,dc=com + …</programlisting> + </section> + + <section> + <title>Membership Types</title> + + <para>Membership types are the possible roles that can be assigned to + users in groups.</para> + + <programlisting language="xml">&lt;field name="membershipTypeURL"&gt;&lt;string&gt;ou=memberships,ou=portal,dc=exoplatform,dc=org&lt;/string&gt;&lt;/field&gt; +&lt;field name="membershipTypeLDAPClasses"&gt;&lt;string&gt;top,organizationalRole&lt;/string&gt;&lt;/field&gt; +&lt;field name="membershipTypeNameAttr"&gt;&lt;string&gt;cn&lt;/string&gt;&lt;/field&gt;</programlisting> + + <para></para> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">membershipTypeURL</emphasis> : base dn + for membership types storage.</para> + </listitem> + </itemizedlist> + + <para>eXo stores membership types in a flat structure under + membershipTypeURL.</para> + + <para>Example : Roles manager, user, admin and editor could by defined + by the subtree :</para> + + <programlisting>ou=roles,ou=portal,dc=exoplatform,dc=org +… + cn=manager,ou=roles,ou=portal,dc=exoplatform,dc=org + … + cn=user,ou=roles,ou=portal,dc=exoplatform,dc=org + … + cn=admin,ou=roles,ou=portal,dc=exoplatform,dc=org + … + cn=editor,ou=roles,ou=portal,dc=exoplatform,dc=org + …</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">membershipTypeLDAPClasses</emphasis>: + comma separated list of classes for membership types + creation.</para> + </listitem> + </itemizedlist> + + <para>When creating a new membership type, an entry will be created + with the given objectClass attributes. The classes must define the + required attributes : <emphasis role="bold">description</emphasis>, + <emphasis role="bold">cn</emphasis></para> + + <para>Example : Adding membership type validator would produce + :</para> + + <programlisting>cn=validator,ou=roles,ou=portal,dc=exoplatform,dc=org + objectclass: top + objectClass: organizationalRole + …</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">membershipTypeNameAttr</emphasis> : + Attribute that will be used as the name of the role</para> + </listitem> + </itemizedlist> + + <para>Example : If membershipTypeNameAttr is 'cn', then role name is + 'manager' for the following membership type entry :</para> + + <programlisting>cn=manager,ou=roles,ou=portal,dc=exoplatform,dc=org &lt;/pre&gt;</programlisting> + </section> + + <section> + <title>Memberships</title> + + <para>Memberships are used to assign a role within a group. They are + entries that are placed under the group entry of their scope group. + Users in this role are defined as attributes of the membership + entry.</para> + + <para>Example: To designate tom as the manager of the group + human-resources:</para> + + <programlisting>ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org + … + cn=manager,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org + member: uid=tom,ou=users,ou=portal,dc=exoplatform,dc=org + …</programlisting> + + <para>The parameters to configure memberships are:</para> + + <programlisting language="xml">&lt;field name="membershipLDAPClasses"&gt;&lt;string&gt;top,groupOfNames&lt;/string&gt;&lt;/field&gt; +&lt;field name="membershipTypeMemberValue"&gt;&lt;string&gt;member&lt;/string&gt;&lt;/field&gt; +&lt;field name="membershipTypeRoleNameAttr"&gt;&lt;string&gt;cn&lt;/string&gt;&lt;/field&gt; +&lt;field name="membershipTypeObjectClassFilter"&gt;&lt;string&gt;objectClass=organizationalRole&lt;/string&gt;&lt;/field&gt;</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">membershipLDAPClasses</emphasis> : + comma separated list of classes used to create memberships.</para> + </listitem> + </itemizedlist> + + <para>When creating a new membership, an entry will be created with + the given objectClass attributes. The classes must at least define the + attribute designated by membershipTypeMemberValue.</para> + + <para>Example : Adding membership validator would produce :</para> + + <programlisting>cn=validator,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org + objectclass: top + objectClass: groupOfNames + …</programlisting> + + <para>&lt;pre&gt; + cn=validator,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org + objectclass: top objectClass: groupOfNames ... &lt;/pre&gt;</para> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">membershipTypeMemberValue</emphasis>: + Multivalued attribute used in memberships to reference users that + have the role in the group.</para> + </listitem> + </itemizedlist> + + <para>Values should be a user dn.</para> + + <para>Example: james and root have admin role within the group + human-resources, would give:</para> + + <programlisting>cn=admin,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org + member: cn=james,ou=users,ou=portal,dc=exoplatform,dc=org + member: cn=root,ou=users,ou=portal,dc=exoplatform,dc=org + …</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">membershipTypeRoleNameAttr</emphasis>: + Attribute of the membership entry whose value references the + membership type.</para> + </listitem> + </itemizedlist> + + <para>Example : In the following membership entry:</para> + + <para>&lt;pre&gt; + cn=manager,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org + &lt;/pre&gt;</para> + + <para>'cn' attribute is used to designate the 'manager' membership + type. Which could also be said : The name of the role is given by 'cn' + the attribute.</para> + + <itemizedlist> + <listitem> + <para><emphasis + role="bold">membershipTypeObjectClassFilter</emphasis> : Filter + used to distinguish membership entries under groups.</para> + </listitem> + </itemizedlist> + + <para>You can use rather complex filters.</para> + + <para>Example: Here is a filter we used for a customer that needed to + trigger a dynlist overlay on openldap.</para> + + <programlisting>(&amp;amp;(objectClass=ExoMembership)(membershipURL=*)) +</programlisting> + + <para>Note: Pay attention to the xml escaping of the '&amp;' (and) + operator</para> + </section> + + <section> + <title>User Profiles</title> + + <para>eXo User profiles also have entries in the ldap but the actual + storage is still done with the hibernate service. You will need the + following parameters:</para> + + <programlisting language="xml">&lt;field name="profileURL"&gt;&lt;string&gt;ou=profiles,ou=portal,dc=exoplatform,dc=org&lt;/string&gt;&lt;/field&gt; +&lt;field name="profileLDAPClasses"&gt;&lt;string&gt;top,organizationalPerson&lt;/string&gt;&lt;/field&gt;</programlisting> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">profileURL</emphasis>: base dn to + store user profiles</para> + </listitem> + + <listitem> + <para><emphasis role="bold">profileLDAPClasses</emphasis>: Classes + used to when creating user profiles</para> + </listitem> + </itemizedlist> + </section> + </section> + </section> + + <section> + <title>Advanced topics</title> + + <section> + <title>Automatic directory population</title> + + <para>At startup, eXo can populate the organization model based + on</para> + + <para>eXo organizational model has User,Group,Membership and Profile + entities. For each, we define a base dn that should be below baseURL. At + startup, if one of userURL, groupsURL, membershipTypeURL or profileURL + does not exist fully, eXo will attempt to create the missing subtree by + parsing the dn and creating entries on-the-fly. To determine the classes + of the created entries, the following rules are applied :</para> + + <itemizedlist> + <listitem> + <para>ou=... : objectClass=top,objectClass=organizationalUnit</para> + </listitem> + + <listitem> + <para>cn=... : objectClass=top,objectClass=organizationalRole</para> + </listitem> + + <listitem> + <para>c=... : objectClass=country</para> + </listitem> + + <listitem> + <para>o=... : objectClass=organization</para> + </listitem> + + <listitem> + <para>dc=.. : + objectClass=top,objectClass=dcObject,objectClass=organization</para> + </listitem> + </itemizedlist> + + <para>Example:</para> + + <para>If baseURL is <emphasis role="bold">o=MyCompany,c=com</emphasis> + and groupsURL is <emphasis + role="bold">dc=groups,cn=Extranet,c=France,ou=EMEA,o=MyCompany,c=com</emphasis> + then, the following subtree will be created :</para> + + <programlisting>ou=EMEA,o=MyCompany,c=com + objectClass: top + objectClass: organizationalUnit + … + c=France,ou=EMEA,o=MyCompany,c=com + objectClass: top + objectClass: country + … + cn=Extranet,c=France,ou=EMEA,o=MyCompany,c=com + objectClass: top + objectClass: organizationalRole + … + dc=groups,cn=Extranet,c=France,ou=EMEA,o=MyCompany,c=com + objectClass: top + objectClass: dcObject + objectClass: organization + …</programlisting> + </section> + + <section> + <title>Active Directory sample configuration</title> + + <para>Here is an alternative configuration for active directory that you + can find in <emphasis + role="bold">activedirectory-configuration.xml</emphasis></para> + + <note> + <para>There is a microsoft limitation: password can't be set in AD via + unsecured connection you have to use the ldaps protocol</para> + </note> + + <para>here is how to use LDAPS protocol with Active Directory :</para> + + <programlisting>1 setup AD to use SSL: + + * add Active Directory Certificate Services role + * install right certificate for DC machine + +2 enable Java VM to use certificate from AD: + + * import root CA used in AD, to keystore, something like + + keytool -importcert -file 2008.cer -keypass changeit -keystore /home/user/java/jdk1.6/jre/lib/security/cacerts + + * set java options + + JAVA_OPTS="${JAVA_OPTS} -Djavax.net.ssl.trustStorePassword=changeit -Djavax.net.ssl.trustStore=/home/user/java/jdk1.6/jre/lib/security/cacerts"</programlisting> + + <programlisting language="xml">[...] + &lt;component&gt; + &lt;key&gt;org.exoplatform.services.ldap.LDAPService&lt;/key&gt; +[..] + &lt;object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig"&gt; + &lt;!-- for multiple ldap servers, use comma seperated list of host:port (Ex. ldap://127.0.0.1:389,10.0.0.1:389) --&gt; + &lt;!-- whether or not to enable ssl, if ssl is used ensure that the javax.net.ssl.keyStore &amp; java.net.ssl.keyStorePassword properties are set --&gt; + &lt;!-- exo portal default installed javax.net.ssl.trustStore with file is java.home/lib/security/cacerts--&gt; + &lt;!-- ldap service will check protocol, if protocol is ldaps, ssl is enable (Ex. for enable ssl: ldaps://10.0.0.3:636 ;for disable ssl: ldap://10.0.0.3:389 ) --&gt; + &lt;!-- when enable ssl, ensure server name is *.directory and port (Ex. active.directory) --&gt; + &lt;field name="providerURL"&gt;&lt;string&gt;ldaps://10.0.0.3:636&lt;/string&gt;&lt;/field&gt; + &lt;field name="rootdn"&gt;&lt;string&gt;CN=Administrator,CN=Users, DC=exoplatform,DC=org&lt;/string&gt;&lt;/field&gt; + &lt;field name="password"&gt;&lt;string&gt;site&lt;/string&gt;&lt;/field&gt; + &lt;field name="version"&gt;&lt;string&gt;3&lt;/string&gt;&lt;/field&gt; + &lt;field name="referralMode"&gt;&lt;string&gt;ignore&lt;/string&gt;&lt;/field&gt; + &lt;field name="serverName"&gt;&lt;string&gt;active.directory&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; +[..] + &lt;component&gt; + &lt;key&gt;org.exoplatform.services.organization.OrganizationService&lt;/key&gt; + [...] + &lt;object type="org.exoplatform.services.organization.ldap.LDAPAttributeMapping"&gt; + [...] + &lt;field name="userAuthenticationAttr"&gt;&lt;string&gt;mail&lt;/string&gt;&lt;/field&gt; + &lt;field name="userUsernameAttr"&gt;&lt;string&gt;sAMAccountName&lt;/string&gt;&lt;/field&gt; + &lt;field name="userPassword"&gt;&lt;string&gt;unicodePwd&lt;/string&gt;&lt;/field&gt; + &lt;field name="userLastNameAttr"&gt;&lt;string&gt;sn&lt;/string&gt;&lt;/field&gt; + &lt;field name="userDisplayNameAttr"&gt;&lt;string&gt;displayName&lt;/string&gt;&lt;/field&gt; + &lt;field name="userMailAttr"&gt;&lt;string&gt;mail&lt;/string&gt;&lt;/field&gt; + [..] + &lt;field name="membershipTypeLDAPClasses"&gt;&lt;string&gt;top,group&lt;/string&gt;&lt;/field&gt; + &lt;field name="membershipTypeObjectClassFilter"&gt;&lt;string&gt;objectClass=group&lt;/string&gt;&lt;/field&gt; + [..] + &lt;field name="membershipLDAPClasses"&gt;&lt;string&gt;top,group&lt;/string&gt;&lt;/field&gt; + &lt;field name="membershipObjectClassFilter"&gt;&lt;string&gt;objectClass=group&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + [...] +&lt;/component&gt; </programlisting> + </section> + + <section> + <title>OpenLDAP dynlist overlays</title> + + <para>If you use OpenLDAP, you may want to use the <ulink + url="http://www.openldap.org/faq/data/cache/1169.html">overl...;. + Here is how you can use the <ulink + url="http://www.openldap.org/faq/data/cache/1209.html">dynlist + overlay</ulink> to have memberships dynamically populated.</para> + + <para>The main idea is to have your memberships populated dynamically by + an ldap query. Thus, you no longer have to maintain manually the roles + on users.</para> + + <para>To configure the dynlist, add the following to your <emphasis + role="bold">slapd.conf</emphasis> :</para> + + <programlisting>dynlist-attrset ExoMembership membershipURL member</programlisting> + + <para>This snipet means : On entries that have ExoMembership class, use + the URL defined in the value of attribute membershipURL as a query and + populate results under the multivalues attribute member.</para> + + <para>Now let's declare the corresponding schema (replace XXXXX to adapt + to your own IANA code):</para> + + <programlisting>attributeType ( 1.3.6.1.4.1.XXXXX.1.59 NAME 'membershipURL' SUP memberURL )</programlisting> + + <para>membershipURL inherits from memberURL.</para> + + <programlisting>objectClass ( 1.3.6.1.4.1.XXXXX.2.12 NAME 'ExoMembership' SUP top MUST ( cn ) MAY (membershipURL $ member $ description ) )</programlisting> + + <para>ExoMembership must define cn and can have attributes :</para> + + <itemizedlist> + <listitem> + <para>membershipURL: trigger for the dynlist</para> + </listitem> + + <listitem> + <para>member : attribute populated by the dynlist</para> + </listitem> + + <listitem> + <para>description : used by eXo for display</para> + </listitem> + </itemizedlist> + + <programlisting># the TestGroup group +dn: ou=testgroup,ou=groups,ou=portal,o=MyCompany,c=com +objectClass: top +objectClass: organizationalUnit +ou: testgroup +l: TestGroup +description: the Test Group</programlisting> + + <para>On this group, we can bind an eXo membership where the overlay + will occur:</para> + + <programlisting># the manager membership on group TestGroup +dn: cn=manager, ou=TestGroup,ou=groups,ou=portal,o=MyCompany,c=com +objectClass: top +objectClass: ExoMembership +membershipURL: ldap:///ou=users,ou=portal,o=MyCompany,c=com??sub?(uid=*) +cn: manager</programlisting> + + <para>This dynlist assigns the role <emphasis + role="bold">manager:/testgroup</emphasis> to any user.</para> + </section> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service-initalizer.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service-initalizer.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service-initalizer.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,182 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.OrganizationServiceInitializer"> + <?dbhtml filename="ch-organization-service-initalizer.html"?> + + <title>Organization Service Initializer</title> + + <para>Use the Organization Service Initializer to create users, groups and + membership types by default.</para> + + <programlisting language="xml">&lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.organization.OrganizationService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;init.service.listener&lt;/name&gt; + &lt;set-method&gt;addListenerPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.organization.OrganizationDatabaseInitializer&lt;/type&gt; + &lt;description&gt;this listener populate organization data for the first launch&lt;/description&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;checkDatabaseAlgorithm&lt;/name&gt; + &lt;description&gt;check database&lt;/description&gt; + &lt;value&gt;entry&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;printInformation&lt;/name&gt; + &lt;description&gt;Print information init database&lt;/description&gt; + &lt;value&gt;false&lt;/value&gt; + &lt;/value-param&gt; + &lt;object-param&gt; + &lt;name&gt;configuration&lt;/name&gt; + &lt;description&gt;description&lt;/description&gt; + &lt;object type="org.exoplatform.services.organization.OrganizationConfig"&gt; + &lt;field name="membershipType"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;object type="org.exoplatform.services.organization.OrganizationConfig$MembershipType"&gt; + &lt;field name="type"&gt; + &lt;string&gt;manager&lt;/string&gt; + &lt;/field&gt; + &lt;field name="description"&gt; + &lt;string&gt;manager membership type&lt;/string&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + + &lt;field name="group"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;object type="org.exoplatform.services.organization.OrganizationConfig$Group"&gt; + &lt;field name="name"&gt; + &lt;string&gt;platform&lt;/string&gt; + &lt;/field&gt; + &lt;field name="parentId"&gt; + &lt;string&gt;&lt;/string&gt; + &lt;/field&gt; + &lt;field name="description"&gt; + &lt;string&gt;the /platform group&lt;/string&gt; + &lt;/field&gt; + &lt;field name="label"&gt; + &lt;string&gt;Platform&lt;/string&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/value&gt; + &lt;value&gt; + &lt;object type="org.exoplatform.services.organization.OrganizationConfig$Group"&gt; + &lt;field name="name"&gt; + &lt;string&gt;administrators&lt;/string&gt; + &lt;/field&gt; + &lt;field name="parentId"&gt; + &lt;string&gt;/platform&lt;/string&gt; + &lt;/field&gt; + &lt;field name="description"&gt; + &lt;string&gt;the /platform/administrators group&lt;/string&gt; + &lt;/field&gt; + &lt;field name="label"&gt; + &lt;string&gt;Administrators&lt;/string&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + + &lt;field name="user"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;object type="org.exoplatform.services.organization.OrganizationConfig$User"&gt; + &lt;field name="userName"&gt; + &lt;string&gt;root&lt;/string&gt; + &lt;/field&gt; + &lt;field name="password"&gt; + &lt;string&gt;exo&lt;/string&gt; + &lt;/field&gt; + &lt;field name="firstName"&gt; + &lt;string&gt;Root&lt;/string&gt; + &lt;/field&gt; + &lt;field name="lastName"&gt; + &lt;string&gt;Root&lt;/string&gt; + &lt;/field&gt; + &lt;field name="email"&gt; + &lt;string&gt;root@localhost&lt;/string&gt; + &lt;/field&gt; + &lt;field name="groups"&gt; + &lt;string&gt; + manager:/platform/administrators + &lt;/string&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt;</programlisting> + + <para>Params for membership type:</para> + + <itemizedlist> + <listitem> + <para>type: The membership type's name.</para> + </listitem> + + <listitem> + <para>description: The membership type's description.</para> + </listitem> + </itemizedlist> + + <para>Params for group:</para> + + <itemizedlist> + <listitem> + <para>name: The group's name</para> + </listitem> + + <listitem> + <para>parentId: The id of the parent group. If the parent id is null, it + means that the group is at the first level. The parentId should have the + form: /ancestor/parent</para> + </listitem> + + <listitem> + <para>description: The group's description</para> + </listitem> + + <listitem> + <para>label: The group's label</para> + </listitem> + </itemizedlist> + + <para>Params for user:</para> + + <itemizedlist> + <listitem> + <para>userName: The user's name</para> + </listitem> + + <listitem> + <para>password: The user's password</para> + </listitem> + + <listitem> + <para>firstName: The user's first name</para> + </listitem> + + <listitem> + <para>lastName: The user's last name</para> + </listitem> + + <listitem> + <para>email: The user's email</para> + </listitem> + + <listitem> + <para>groups: The user's membership types and groups in which he + consist.</para> + </listitem> + </itemizedlist> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service-listener.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service-listener.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service-listener.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,182 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"hp://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.OrganizationListener"> + <?dbhtml filename="ch-organization-service-listener.html"?> + + <title>Organization Listener</title> + + <section> + <title>Overview</title> + + <para>The <link linkend="Core.OrganizationService">Organization + Service</link> provides a mechanism to receive notifications when :</para> + + <itemizedlist> + <listitem> + <para>A User is created, deleted or modified.</para> + </listitem> + + <listitem> + <para>A Group is created, deleted or modified.</para> + </listitem> + + <listitem> + <para>A Membership is created or removed.</para> + </listitem> + </itemizedlist> + + <para>This mechanism is very useful to cascade some actions when the + organization model is modified. For example, it is currently used to + :</para> + + <itemizedlist> + <listitem> + <para>Initialize the personal portal pages.</para> + </listitem> + + <listitem> + <para>Initialize the personal calendars, address books and mail + accounts in CS.</para> + </listitem> + + <listitem> + <para>Create drives and personal areas in ECM.</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Writing your own listeners</title> + + <para>To implement your own listener, you just need to write extend some + existing listener classes. These classes define hooks that are invoked + before or after operations are performed on organization model.</para> + + <section> + <title>UserEventListener</title> + + <para>To listen to user changes, you need to extend + &lt;&gt;org.exoplatform.services.organization.UserEventListener&lt;/&gt; + :</para> + + <programlisting language="java">public class MyUserListener extends UserEventListener { + + public void preSave(User user, boolean isNew) throws Exception { + System.out.println("Before " + (isNew?"creating":"updating") + " user " + user.getUserName()); + } + + public void postSave(User user, boolean isNew) throws Exception { + System.out.println("After user " + user.getUserName() + (isNew?" created":" updated")); + } + + public void preDelete(User user) throws Exception { + System.out.println("Before deleting user " + user.getUserName()); + } + + public void preDelete(User user) throws Exception { + System.out.println("After deleting user " + user.getUserName()); + } + +}</programlisting> + </section> + + <section> + <title>GroupEventListener</title> + + <para>To listen to group changes, you need to extend + &lt;&gt;org.exoplatform.services.organization.GroupEventListener&lt;/&gt; + :</para> + + <programlisting language="java">public class MyGroupListener extends GroupEventListener { + + public void preSave(Group group, boolean isNew) throws Exception { + System.out.println("Before " + (isNew?"creating":"updating") + " group " + group.getName()); + } + + public void postSave(Group group, boolean isNew) throws Exception { + System.out.println("After group " + group.getName() + (isNew?" created":" updated")); + } + + public void preDelete(Group group) throws Exception { + System.out.println("Before deleting group " + group.getName()); + } + + public void preDelete(Group group) throws Exception { + System.out.println("After deleting group " + group.getName()); + } +}</programlisting> + </section> + + <section> + <title>MembershipEventListener</title> + + <para>To listen to membership changes, you need to extend + &lt;&gt;org.exoplatform.services.organization.MembershipEventListener&lt;/&gt; + :</para> + + <programlisting language="java">public class MyMembershipListener extends MembershipEventListener { + + public void preSave(Membership membership, boolean isNew) throws Exception { + System.out.println("Before " + (isNew?"creating":"updating") + " membership."); + } + + public void postSave(Membership membership, boolean isNew) throws Exception { + System.out.println("After membership " + (isNew?" created":" updated")); + } + + public void preDelete(Membership membership) throws Exception { + System.out.println("Before deleting membership"); + } + + public void preDelete(Membership membership) throws Exception { + System.out.println("After deleting membership"); + } +}</programlisting> + </section> + </section> + + <section> + <title>Registering your listeners</title> + + <para>Registering the listeners is then achieved by using the ExoContainer + plugin mechanism. Learn more about it on the <link + linkend="Kernel.ServiceConfigurationforBeginners">Service Configuration + for Beginners</link> article.</para> + + <para>To effectively register organization service's listeners you simply + need to use the &lt;&gt;addListenerPlugin&lt;/&gt; seer injector.</para> + + <para>So, the easiest way to register your listeners is to pack them into + a .jar and create a configuration file into it under <emphasis + role="bold">mylisteners.jar!/conf/portal/configuration.xml</emphasis></para> + + <programlisting language="xml">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt; +&lt;configuration&gt; + &lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.organization.OrganizationService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;myuserplugin&lt;/name&gt; + &lt;set-method&gt;addListenerPlugin&lt;/set-method&gt; + &lt;type&gt;org.example.MyUserListener&lt;/type&gt; + &lt;description&gt;&lt;/description&gt; + &lt;/component-plugin&gt; + &lt;component-plugin&gt; + &lt;name&gt;mygroupplugin&lt;/name&gt; + &lt;set-method&gt;addListenerPlugin&lt;/set-method&gt; + &lt;type&gt;org.example.MyGroupListener&lt;/type&gt; + &lt;description&gt;&lt;/description&gt; + &lt;/component-plugin&gt; + &lt;component-plugin&gt; + &lt;name&gt;mymembershipplugin&lt;/name&gt; + &lt;set-method&gt;addListenerPlugin&lt;/set-method&gt; + &lt;type&gt;org.example.MyMembershipListener&lt;/type&gt; + &lt;description&gt;&lt;/description&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt; +&lt;configuration&gt;</programlisting> + + <para>Now, simply deploy the jar under $TOMCAT_HOME/lib and your listeners + are ready!</para> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/organization-service.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,150 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.OrganizationService"> + <?dbhtml filename="ch-organization-service.html"?> + + <title>Organization Service</title> + + <section id="Overview"> + <title>Overview</title> + + <para>OrganizationService is the service that allows to access the + Organization model. This model is composed of :</para> + + <itemizedlist> + <listitem> + <para>Users</para> + </listitem> + + <listitem> + <para>Groups</para> + </listitem> + + <listitem> + <para>Memberships</para> + </listitem> + </itemizedlist> + + <para>It is the basis of eXo personalization and authorizations in eXo and + is used to all over the platform. The model is abstract and does not rely + on any specific storage. Multiple implementations exist in eXo :</para> + + <itemizedlist> + <listitem> + <para>Hibernate : for storage into a RDBMS</para> + </listitem> + + <listitem> + <para>Jndi : for storage into a directory such as an LDAP or MS Active + Directory</para> + </listitem> + + <listitem> + <para>Jcr : for storage inside a Java Content Repository</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Organizational Model</title> + + <section> + <title>User</title> + + <itemizedlist> + <listitem> + <para>Username used as the identified</para> + </listitem> + + <listitem> + <para>Profile (identity and preferences)</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Group</title> + + <para>Gather a set of users</para> + + <itemizedlist> + <listitem> + <para>Applicative or business</para> + </listitem> + + <listitem> + <para>Tree structure</para> + </listitem> + + <listitem> + <para>No inheritance</para> + </listitem> + + <listitem> + <para>Expressed as /group/subgroup/subsubgroup</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Membership</title> + + <itemizedlist> + <listitem> + <para>Qualifies the group belonging</para> + </listitem> + + <listitem> + <para>"Member of group as XXX"</para> + </listitem> + + <listitem> + <para>Expressed as : manager:/organization/hr, *:/partners</para> + </listitem> + </itemizedlist> + </section> + </section> + + <section> + <title>Related articles and how-tos</title> + + <itemizedlist> + <listitem> + <para><ulink + url="http://wiki.exoplatform.org/xwiki/bin/view/JCR/Organization+Ser... + Organization Service</ulink></para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para><ulink + url="http://wiki.exoplatform.org/xwiki/bin/view/Core/Update+Conversa... + ConversationState when user's Membership changed</ulink></para> + </listitem> + + <listitem> + <para><ulink url="Organization Service Initializer">Organization + Service Initializer</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://wiki.exoplatform.org/xwiki/bin/view/Portal/Accessing+Use... + to Access User Profile in your code</ulink></para> + </listitem> + + <listitem> + <para><ulink url="CoreOrganizationListener">How to create your own + Organization Listener</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="How to manipulate Users and Memberships Programmatically">How to + manipulate Users and Memberships Programmatically</ulink></para> + </listitem> + </itemizedlist> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/security-service.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/security-service.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/security-service.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,307 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.SecurityService"> + <?dbhtml filename="ch-security-service.html"?> + + <title>Security Service</title> + + <section> + <title>1 Overview</title> + + <para>The purpose is to make a simple, unified way for the authentication + and the storing/propagation of user sessions through all the eXo + components and J2EE containers. JAAS is supposed to be the primary login + mechanism but the Security Service framework should not prevent other + (custom or standard) mechanisms from being used. You can learn more about + JAAS in the <ulink + url="http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/tutoria... + Tutorial</ulink></para> + </section> + + <section> + <title>1 Framework</title> + + <para>The central point of this framework is the <emphasis + role="bold">ConversationState</emphasis> object which stores all + information about the state of the current user (very similar to the + Session concept). The same ConversationState also stores acquired + attributes of an <emphasis role="bold">Identity</emphasis> which is a set + of principals to identify a user.</para> + + <para>The ConversationState has definite lifetime. This object should be + created when the user's identity becomes known by eXo (login procedure) + and destroyed when the user leaves an eXo based application (logout + procedure). Using JAAS it should happen in LoginModule's login() and + logout() methods respectively.</para> + + <section> + <title>1.1 ConversationState and ConversationRegistry</title> + + <para>The ConversationState can be stored</para> + + <itemizedlist> + <listitem> + <para>In a static <emphasis role="bold">local thread + variable</emphasis>, or</para> + </listitem> + + <listitem> + <para>As a <emphasis role="bold">key-value pair</emphasis> in the + <emphasis role="bold">ConversationRegistry</emphasis> + component.</para> + </listitem> + </itemizedlist> + + <para>One or the other, or both methods can be used to set/retrieve the + state at runtime. The most important thing is that they should be + complementary, i.e. make sure that the conversation state is set before + you try to use it.</para> + + <para><emphasis role="bold">Local Thread Variable:</emphasis> Storing + the ConversationState in a static local thread variable makes it + possible to represent it as a <emphasis role="bold">context</emphasis> + (current user's state).</para> + + <programlisting language="java">ConversationState.setCurrent(conversationState); +.... +ConversationState.getCurrent();</programlisting> + + <para><emphasis role="bold">Key-Value way</emphasis></para> + + <para>If you store the ConversationState inside the <emphasis + role="bold">ConversationRegistry</emphasis> component as a set of + key-value pairs, the session key is an arbitrary String (user name, + ticket id, httpSessionId etc).</para> + + <programlisting language="java">conversationRegistry.register("key", conversationState); +... +conversationRegistry.getState("key");</programlisting> + + <para><emphasis role="bold">ConversationRegistry</emphasis> The + ConversationRegistry is a mandatory component deployed into eXo + Container as following:</para> + + <programlisting language="xml">&lt;component&gt; + &lt;type&gt;org.exoplatform.services.security.ConversationRegistry&lt;/type&gt; +&lt;/component&gt;</programlisting> + </section> + + <section> + <title>1.1 Authenticator</title> + + <para>An Authenticator is responsible for Identity creating, it contains + two methods:</para> + + <itemizedlist> + <listitem> + <para>validateUser() accepts an array of credentials and returns the + userId (which can be something different from the username).</para> + </listitem> + + <listitem> + <para>createIdentity() accepts the userId and returns a newly + created Identity object.</para> + </listitem> + </itemizedlist> + + <programlisting language="java">public interface Authenticator { + /** + * Authenticate user and return userId which can be different to username. + * @param credentials - list of users credentials (such as name/password, X509 certificate etc) + * @return userId + * @throws LoginException + * @throws Exception + */ + String validateUser(Credential[] credentials) throws LoginException, Exception; + + /** + * @param credentials - userId. + * @return Identity + * @throws Exception + */ + Identity createIdentity(String userId) throws Exception; +}</programlisting> + + <para>It is up to the application developer (and deployer) whether to + use the Authenticator component(s) and how many implementations of this + components should be deployed in eXo container. The developer is free to + create an Identity object using a different way, but the Authenticator + component is the highly recommended way from architectural + considerations.</para> + + <para>Typical functionality of the validateUser(Credential\[] + credentials) method is the comparison of incoming credentials + (username/password, digest etc) with those credentials that are stored + in an implementation specific database. Then, validateUser(Credential\[] + credentials) returns back the userId or throws a LoginException in a + case of wrong credentials.</para> + + <para>Default Authenticator implementation is + org.exoplatform.services.organization.auth.OrganizationAuthenticatorImpl + which compares incoming username/password credentials with the ones + stored in OrganizationService. Configuration example:</para> + + <programlisting language="xml">&lt;component&gt; + &lt;key&gt;org.exoplatform.services.security.Authenticator&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.organization.auth.OrganizationAuthenticatorImpl&lt;/type&gt; +&lt;/component&gt;</programlisting> + </section> + </section> + + <section> + <title>Usage</title> + + <section> + <title>JAAS login module</title> + + <para>The framework described is not coupled with any authentication + mechanism but the most logical and implemented by default is the JAAS + Login module. The typical sequence looks as follows (see + org.exoplatform.services.security.jaas.DefaultLoginModule):</para> + + <itemizedlist> + <listitem> + <para>LoginModule.login() creates a list of credentials using + standard JAAS Callbacks features, obtains an Authenticator instance, + and creates an Identity object calling + Authenticator.authenticate(..) method</para> + </listitem> + </itemizedlist> + + <programlisting language="java">Authenticator authenticator = (Authenticator) container() + .getComponentInstanceOfType(Authenticator.class); +// RolesExtractor can be null +RolesExtractor rolesExtractor = (RolesExtractor) container(). +getComponentInstanceOfType(RolesExtractor.class); + + +Credential[] credentials = new Credential[] {new UsernameCredential(username), new PasswordCredential(password) }; +String userId = authenticator.validateUser(credentials); +identity = authenticator.createIdentity(userId);</programlisting> + + <itemizedlist> + <listitem> + <para>LoginModule.commit() obtains the IdentityRegistry object, and + register the identity using userId as a key.</para> + </listitem> + </itemizedlist> + + <para>When initializing the login module, you can set the option + parameter "singleLogin". With this option you can disallow the same + Identity to login for a second time.</para> + + <para>By default singleLogin is disabled, so the same identity can be + registered more than one time. Parameter can be passed in this form + singleLogin=yes or singleLogin=true.</para> + + <programlisting language="java">IdentityRegistry identityRegistry = (IdentityRegistry) getContainer().getComponentInstanceOfType(IdentityRegistry.class); + +if (singleLogin &amp;&amp; identityRegistry.getIdentity(identity.getUserId()) != null) + throw new LoginException("User " + identity.getUserId() + " already logined."); + +identity.setSubject(subject); +identityRegistry.register(identity);</programlisting> + + <para>In the case of using several LoginModules, JAAS allows to place + the login() and commit() methods in different REQUIRED modules.</para> + + <para>After that, the web application must use SetCurrentIdentityFilter. + This filter obtains the ConversationRegistry object and tries to get the + ConversationState by sessionId (HttpSession). If there is no + ConversationState, then SetCurrentIdentityFilter will create a new one, + register it and set it as current one using + ConversationState.setCurrent(state).</para> + + <itemizedlist> + <listitem> + <para>LoginModule.logout() can be called by + JAASConversationStateListener, it extends + ConversationStateListener.</para> + </listitem> + </itemizedlist> + + <para>This listener must be configured in web.xml. The method + sessionDestroyed(HttpSessionEvent) is called by the ServletContainer. + This method removes the ConversationState from the ConversationRegistry + ConversationRegistry.unregister(sesionId) and calls the method + LoginModule.logout().</para> + + <programlisting language="java">ConversationRegistry conversationRegistry = (ConversationRegistry) getContainer().getComponentInstanceOfType(ConversationRegistry.class); + +ConversationState conversationState = conversationRegistry.unregister(sesionId); + +if (conversationState != null) { + log.info("Remove conversation state " + sesionId); + if (conversationState.getAttribute(ConversationState.SUBJECT) != null) { + Subject subject = (Subject) conversationState.getAttribute(ConversationState.SUBJECT); + LoginContext ctx = new LoginContext("exo-domain", subject); + ctx.logout(); +} else { + log.warn("Subject was not found in ConversationState attributes."); +}</programlisting> + + <para></para> + </section> + + <section> + <title>1.1 Predefinded JAAS login modules</title> + + <para>There are several JAAS Login modules included in eXo Platform + sources:</para> + + <para><emphasis + role="bold">org.exoplatform.services.security.jaas.DefaultLoginModule</emphasis> + which provides both authentication (using eXo Authenticator based + mechanism) and authorization, filling Conversation Registry as it + described in previous section. There are also several per-Application + Server extensions of this login module which can be found in + org.exoplatform.services.security.jaas package, which can be used in + appropriate AS. In particular, we have dedicated Login modules for + Tomcat, JBoss, Jonas and WebSphere.</para> + + <para>Besides that, for the case when third party authentication + mechanism required, we have <emphasis + role="bold">org.exoplatform.services.security.jaas.IdentitySetLoginModule</emphasis>, + which catches a login identity from third party "authenticating" login + module and preforms eXo specific authorization job. In this case third + party login module has to put login (user) name to the shared state map + under <emphasis role="bold">"javax.security.auth.login.name"</emphasis> + key and third party LM has to be configured before + IdentitySetLoginModule like:</para> + + <programlisting>exo { + com.third.party.LoginModuleImpl required; + org.exoplatform.services.security.jaas.IdentitySetLoginModule required; +};</programlisting> + </section> + + <section> + <title>1.1 J2EE container authentication</title> + + <para>As you know, when a user in JAAS is authenticated, a Subject is + created as a result. This Subject represents the authenticated user. It + is important to know and follow the rules regarding Subject filling + which are specific for each J2EE server, where eXo Platform is + deployed.</para> + + <para>To make it workable for the particular J2EE server, it is + necessary to add specific Principals/Credentials to the Subject to be + propagated into the specific J2EE container implementation. We extended + the DefaultLoginModule by overloading its commit() method with a + dedicated logic, presently available for Tomcat, JBOSS and JONAS + application servers.</para> + + <para>Furthermore, you can use the optional RolesExtractor which is + responsible for mapping primary Subject's principals (userId and a set + of groups) to J2EE Roles:</para> + + <programlisting language="java">public interface RolesExtractor { + Set &lt;String&gt; extractRoles(String userId, Set&lt;MembershipEntry&gt; memberships); +}</programlisting> + + <para>This component may be used by Authenticator to create the Identity + with a particular set of <emphasis role="bold">Roles</emphasis>.</para> + </section> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/spring-security-integration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/spring-security-integration.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/spring-security-integration.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,672 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.SpringSecurityIntegration"> + <?dbhtml filename="ch-spring-security-integration.html"?> + + <title>Spring Security Integration</title> + + <section> + <title>Introduction</title> + + <para>How to Integrate the spring security framework in the eXo + portal?</para> + + <para>This tutorial will guide you through a few steps and show you how + easy it is to integrate spring security (or the Spring framework in + general) in eXo portal. We will create a login portlet example as a + support all along the document reading. The login portlet example has been + developed and deployed using the eXo WCM product running on the + application server JBoss 4.2.3. But it can easily be adapted to another + eXo product (such as ECM) and to other servers such as tomcat. Moreover, + the example, claiming to be a real world example, is implemented using JSF + 1.2, the JBoss portlet bridge and Spring and can serve as a example + project from where you can start your own portlet development targeting + the eXo platform.</para> + </section> + + <section> + <title>Installation</title> + + <para>This tutorial assumes that you have a working eXo WCM installation + running under JBoss 4.2.x.</para> + + <para>Download the spring framework: <ulink + url="http://s3.amazonaws.com/dist.springframework.org/release/SPR/sp... + + <para>Download spring-security: <ulink + url="http://sourceforge.net/project/showfiles.php?group_id=73357&... + + <para>Unzip the 02portal.war file in the jboss + server/default/deploy/exoplatform.sar directory and copy the following + jars in WEB-INF/lib:</para> + + <itemizedlist> + <listitem> + <para>spring.jar</para> + </listitem> + + <listitem> + <para>spring-security-core.jar</para> + </listitem> + + <listitem> + <para>aspectjrt-1.5.4.jar</para> + </listitem> + + <listitem> + <para>exo-spring.jar (contains the filters and event handlers + described in this tutorial - see the attachment section of this + page)</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Configuration</title> + + <para>To enable spring security in exo we need to go through a few + configuration steps:</para> + + <section> + <title>JAAS disabling</title> + + <para>First, we need to disable the JAAS security which is the default + authentication mechanism in exo. Edit 02portal.war web.xml file and + comment out the JAAS configuration related lines:</para> + + <programlisting language="xml">... + &lt;session-config&gt; + &lt;session-timeout&gt;15&lt;/session-timeout&gt; + &lt;/session-config&gt; + + &lt;!-- + &lt;security-constraint&gt; + &lt;web-resource-collection&gt; + &lt;web-resource-name&gt;user authentication&lt;/web-resource-name&gt; + &lt;url-pattern&gt;/private/*&lt;/url-pattern&gt; + &lt;http-method&gt;POST&lt;/http-method&gt; + &lt;http-method&gt;GET&lt;/http-method&gt; + &lt;/web-resource-collection&gt; + &lt;auth-constraint&gt; + &lt;role-name&gt;users&lt;/role-name&gt; + &lt;/auth-constraint&gt; + &lt;user-data-constraint&gt; + &lt;transport-guarantee&gt;NONE&lt;/transport-guarantee&gt; + &lt;/user-data-constraint&gt; + &lt;/security-constraint&gt; + + &lt;login-config&gt; + &lt;auth-method&gt;FORM&lt;/auth-method&gt; + &lt;realm-name&gt;exo-domain&lt;/realm-name&gt; + &lt;form-login-config&gt; + &lt;form-login-page&gt;/login/jsp/login.jsp&lt;/form-login-page&gt; + &lt;form-error-page&gt;/login/jsp/login.jsp&lt;/form-error-page&gt; + &lt;/form-login-config&gt; + &lt;/login-config&gt; + --&gt; + + &lt;security-role&gt; + &lt;description&gt;a simple user role&lt;/description&gt; + &lt;role-name&gt;users&lt;/role-name&gt; + &lt;/security-role&gt; +...</programlisting> + </section> + + <section> + <title>Enabling spring security</title> + + <para>To enable spring and set the spring security filter, add the + following lines:</para> + + <programlisting language="xml">... + &lt;context-param&gt; + &lt;param-name&gt;contextConfigLocation&lt;/param-name&gt; + &lt;param-value&gt;/WEB-INF/security-context.xml&lt;/param-value&gt; + &lt;/context-param&gt; + + &lt;listener&gt; + &lt;listener-class&gt;org.springframework.web.context.ContextLoaderListener&lt;/listener-class&gt; + &lt;/listener&gt; + + &lt;filter&gt; + &lt;filter-name&gt;springSecurityFilterChain&lt;/filter-name&gt; + &lt;filter-class&gt;org.springframework.web.filter.DelegatingFilterProxy&lt;/filter-class&gt; + &lt;/filter&gt; +...</programlisting> + + <para>Activate the spring security filter at the right position, i.e. + just after the filter responsible of exo container + initialization.</para> + + <programlisting language="xml">... + &lt;filter-mapping&gt; + &lt;filter-name&gt;PortalContainerInitializedFilter&lt;/filter-name&gt; + &lt;url-pattern&gt;/*&lt;/url-pattern&gt; + &lt;/filter-mapping&gt; + + &lt;filter-mapping&gt; + &lt;filter-name&gt;springSecurityFilterChain&lt;/filter-name&gt; + &lt;url-pattern&gt;/*&lt;/url-pattern&gt; + &lt;/filter-mapping&gt; + + &lt;filter-mapping&gt; + &lt;filter-name&gt;SetCurrentIdentityFilter&lt;/filter-name&gt; + &lt;url-pattern&gt;/*&lt;/url-pattern&gt; + &lt;/filter-mapping&gt; +...</programlisting> + </section> + + <section> + <title>security-context.xml</title> + + <para>We need to configure the spring security filter chain for our + purposes. Create a file named security-context.xml in 02portal.war + WEB-INF directory containing the following lines:</para> + + <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;beans:beans xmlns="http://www.springframework.org/schema/security" + xmlns:beans="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd + http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security-2.0.1.xsd&... + + &lt;http auto-config="true"&gt; + &lt;intercept-url pattern="/private/**" access="ROLE_USER" /&gt; + &lt;form-login login-page='/public/classic/Login' default-target-url='/private/classic/home' /&gt; + &lt;/http&gt; + + &lt;authentication-provider&gt; + &lt;user-service&gt; + &lt;user name="rod" password="koala" authorities="ROLE_SUPERVISOR, ROLE_USER, ROLE_TELLER" /&gt; + &lt;user name="root" password="exo" authorities="ROLE_USER" /&gt; + &lt;/user-service&gt; + &lt;/authentication-provider&gt; + +&lt;/beans:beans&gt;</programlisting> + + <para>The file contains two elements. The http node which is responsible + of configuring the filter chain. The auto-config mode set to true allows + us to do just a minimal configuration, everything else being smartly + initialized by default. We just set an intercept URL pointing to + '/private/**' with the ROLE_USER authority which corresponds to secured + resources in exo. In case of successful auhentication, the user will be + redirected to the specified default target URL.</para> + + <para>The second element defines a simple authentication provider based + on the spring security InMemoryDaoImpl implementation of the + UserDetailsService. Note that we define the exo root user in the + configuration which will allow us to log in with admin privileges in the + exo portal.</para> + </section> + </section> + + <section> + <title>Login portlet example</title> + + <para>Now that we have successfully installed and configured spring + security in exo, we need a login portlet example to capture user + credentials and serve as an entry point in the authentication process. The + login portlet itself is based on JSF 1.2, Jboss portlet bridge and the + spring framework, but you can obviously use whatever web framework you + want to achieve the same.</para> + + <section> + <title>Building the portlet</title> + + <para>So we need a login form to capture user credentials inputs. The + portlet login form consists of the following lines of xml:</para> + + <programlisting>&lt;f:view xmlns:f="http://java.sun.com/jsf/core" + xmlns:h="http://java.sun.com/jsf/html" + xmlns:ice="http://www.icesoft.com/icefaces/component" + xmlns:liferay-faces="http://liferay.com/tld/faces" + xmlns:ui="http://java.sun.com/jsf/facelets" + xmlns:c="http://java.sun.com/jstl/core" + xmlns:fn="http://java.sun.com/jsp/jstl/functions" + xmlns:t="http://myfaces.apache.org/tomahawk"&gt; + + &lt;style type="text/css" media="screen"&gt; + @import "/loginportlet/css/starter.css"; + @import "/loginportlet/css/uni-form.css"; + &lt;/style&gt; + + &lt;script src="/loginportlet/js/jquery.js" type="text/javascript"&gt;&lt;/script&gt; + &lt;script src="/loginportlet/js/uni-form.jquery.js" type="text/javascript"&gt;&lt;/script&gt; + + &lt;h:form styleClass="uniForm" &gt; + &lt;fieldset class="inlineLabels"&gt; + &lt;legend&gt;Sign in&lt;/legend&gt; + + &lt;div class="ctrlHolder"&gt; + &lt;h:outputLabel for="login" style="width: 70px"&gt;&lt;em&gt;*&lt;/em&gt;Login:&lt;/h:outputLabel&gt; + &lt;h:inputText id="login" value="#{loginBean.login}" required="true" styleClass="textInput" /&gt; + &lt;h:message for="login" styleClass="portlet-msg-error" /&gt; + &lt;/div&gt; + &lt;div class="ctrlHolder"&gt; + &lt;h:outputLabel for="password" style="width: 70px"&gt;&lt;em&gt;*&lt;/em&gt;Password:&lt;/h:outputLabel&gt; + &lt;h:inputSecret id="password" value="#{loginBean.passwd}" required="true" styleClass="textInput" /&gt; + &lt;h:message for="password" styleClass="portlet-msg-error" /&gt; + &lt;/div&gt; + &lt;/fieldset&gt; + + &lt;div class="buttonHolder" style="margin-top: 20px; margin-right: 20px"&gt; + &lt;h:commandButton styleClass="primaryAction" value="Submit" action="#{loginBean.login}" /&gt; + &lt;/div&gt; + &lt;/h:form&gt; +&lt;/f:view&gt;</programlisting> + + <para>The interesting part resides in the backing bean which implements + the login action triggered when the user clicks the login form submit + button.</para> + + <programlisting language="java">package org.exoplatform.loginportlet; + +import org.springframework.context.annotation.Scope; +import org.springframework.stereotype.Controller; + +@Controller +@Scope("request") +public class LoginBean { + + String login; + + String passwd; + + public String login() throws Exception { + String redirect = "/portal/j_spring_security_check?j_username=" + login + "&amp;j_password=" + passwd; + PortalUtils.sendRedirect(redirect); + return null; + } + + ... +}</programlisting> + + <para>The login action simply sends a HTTP redirect to the spring + security login URL passing the user login and password as parameters. + This URL informs the filter to try to authenticate the supplied user + credentials. This is the Spring security authentication process entry + point.</para> + </section> + + <section> + <title>Setting up the login portal page</title> + + <para>Now that we have a login portlet available we need to set it up + into a portal page.</para> + + <itemizedlist> + <listitem> + <para>Log in as root in exo portal.</para> + </listitem> + + <listitem> + <para>Go to application registry and import the loginportlet</para> + </listitem> + + <listitem> + <para>Add a new hidden page named 'Login' under the portal classic's + navigation (read more on page creation <ulink + url="here&gt;WCM.Tutorial">here&gt;WCM.Tutorial</ulink>). Make sure + that the visible flag is unchecked to hide the page. Also declare + the page as public so that everyone can access it without being + authenticated for obvious reasons.</para> + </listitem> + + <listitem> + <para>Finally, drag &amp; drop the login portlet in the page with + the desired layout.</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Customization of portal login and logout urls</title> + + <para>In the portal header, there is a login or logout action displayed + depending whether you are already logged in or not. We need to customize + those actions so that when the user clicks on it she or he will be + redirected either to our login page or to the spring security logout + url. Edit the article, go to the default.js tab and apply the following + changes to the code:</para> + + <programlisting language="javascript">function validateUser() { + + var user = eXo.env.portal.userName; + var rootObj = document.getElementById("classic-access"); + var loginContentObj = eXo.core.DOMUtil.findFirstDescendantByClass(rootObj, "div", "UIWCMLoginPortlet"); + var welcomeObj = eXo.core.DOMUtil.findFirstDescendantByClass(rootObj, "span", "Welcome"); + var userObj = eXo.core.DOMUtil.findFirstDescendantByClass(rootObj, "span", "LoggedUser"); + var languageObj = eXo.core.DOMUtil.findFirstDescendantByClass(rootObj, "a", "LanguageIcon"); + var logXXXObj = eXo.core.DOMUtil.findPreviousElementByTagName(languageObj, "a"); + + if (user != "null") { + welcomeObj.innerHTML = "Welcome: "; + userObj.innerHTML = user; + logXXXObj.innerHTML = "Logout"; + if (eXo.core.DOMUtil.hasClass(logXXXObj, "LoginIcon")) { + eXo.core.DOMUtil.removeClass(logXXXObj, "LoginIcon"); + eXo.core.DOMUtil.addClass(logXXXObj, "LogoutIcon"); + } + logXXXObj.onclick = function() { document.location.href = '/portal/j_spring_security_logout' } + } else { + if (eXo.core.DOMUtil.hasClass(logXXXObj, "LogoutIcon")) { + eXo.core.DOMUtil.removeClass(logXXXObj, "LogoutIcon"); + eXo.core.DOMUtil.addClass(logXXXObj, "LoginIcon"); + } + logXXXObj.innerHTML = "Login"; + logXXXObj.onclick = function() { document.location.href = '/portal/public/classic/Login' }; + } + + languageObj.onclick = function () { if(document.getElementById('UIMaskWorkspace')) ajaxGet(eXo.env.server.createPortalURL('UIPortal', 'ChangeLanguage', true)); } +} + +eXo.core.Browser.addOnLoadCallback("validateUser", validateUser);</programlisting> + + <para>As you can see, the two onclick event handler function bodies have + been changed to a simple redirect to the login page or the logout + URL.</para> + </section> + + <section> + <title>A look at the login page</title> + + <para>Once you are done with all this, just click on the login action + and you should be redirect to the login page looking something like + that:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/login-page.jpg" /> + </imageobject> + </mediaobject> + </section> + </section> + + <section> + <title>Integration strategies</title> + + <para>Until now we haven't discussed about any integration strategies + concerning a potential existing security realm outside of the eXo + platform. To address this problem we have the choice between at least two + different strategies:</para> + + <para>1.1.1 <emphasis role="bold">Direct integration</emphasis> We can + directly integrate eXo with the external realm. Everything related to + organisation and user management in exo is cleanly separated in its own + abstraction accessible through the OrganisationService. The authentication + process itself is encapsulated in the Authenticator abstraction which sits + on top of the organization service. eXo provides several implementations + of both. So whether your realm is based on LDAP or JDBC and because the + default implementations are generic enough, you will be able to use them + and fits them to your needs with a matter of a little configuration. You + can even develop a custom implementation to meet your more specific + needs.</para> + + <section> + <title>Replication</title> + + <para>Or we can go through a replication process between the external + realm and the eXo platform realm. This is the strategy that we are going + to use to build our login portlet example. Furthermore, the replication + will occur dynamically on any user authentication attempt.</para> + </section> + </section> + + <section> + <title>Integration with eXo portal</title> + + <para>Being successfully authenticated against an external realm is not + sufficient by itself. We also need to propagate the newly created security + context to the portal own security mechanism. In eXo portal terminology, + it means we have to create an Identity object for the user and register it + into the Identity Registry.</para> + + <para>Spring framework provides a simple notification model where a bean + can listen to application events published by other beans. Fortunately, + spring security uses this mechanism and publishes an + InteractiveAuthenticationSuccessEvent in case of successful + authentication. That will allow us to hook up custom code to that + event.</para> + + <para>Furthermore, we need to replicate the user details from the external + realm to the eXo portal one according to the integration strategy defined + above.</para> + + <para>We create a SpringSecurityEventHandler bean that implements the + ApplicationListener interface and listens to the + InteractiveAuthenticationSuccessEvent event.</para> + + <programlisting language="java">package org.exoplatform.spring.security.web; + +... + +public class SpringSecurityEventHandler implements ApplicationListener { + + private String portalContainerName = "portal"; + + public void onApplicationEvent(ApplicationEvent event) { + if (event instanceof InteractiveAuthenticationSuccessEvent) { + try { + InteractiveAuthenticationSuccessEvent successEvent = (InteractiveAuthenticationSuccessEvent) event; + ExoContainer container = getContainer(); + + String login = successEvent.getAuthentication().getName(); + String passwd = successEvent.getAuthentication().getCredentials().toString(); + + IdentityRegistry identityRegistry = (IdentityRegistry) container.getComponentInstanceOfType(IdentityRegistry.class); + Authenticator authenticator = (Authenticator) container.getComponentInstanceOfType(Authenticator.class); + OrganizationService orgService = (OrganizationService) container.getComponentInstanceOfType(OrganizationService.class); + + User user = orgService.getUserHandler().findUserByName(login); + if (user == null) { + user = orgService.getUserHandler().createUserInstance(login); + user.setFirstName(login); + user.setLastName(login); + orgService.getUserHandler().createUser(user, false); + orgService.getUserHandler().saveUser(user, false); + //TODO: put some more integration code here + } + + Identity identity = authenticator.createIdentity(login); + + Subject subject = new Subject(); + subject.getPrivateCredentials().add(passwd); + subject.getPublicCredentials().add(new UsernameCredential(login)); + + identity.setSubject(subject); + identityRegistry.register(identity); + + } catch (Exception e) { + e.getMessage(); + } + } + } + + protected ExoContainer getContainer() { + // TODO set correct current container + ExoContainer container = ExoContainerContext.getCurrentContainer(); + if (container instanceof RootContainer) { + container = RootContainer.getInstance().getPortalContainer(portalContainerName); + } + return container; + } + +... + +}</programlisting> + + <para>Basically the bean retrieves user login and password from the + InteractiveAuthenticationSuccessEvent object and tries to get the user + from the organization service. In case he cannot find it in the + repository, he simply creates it on the fly. In this example the user is + created with just a few details, but you can put some custom integration + code with the external realm here, and create the user with all the + details (email, birth date, roles, etc.) it seems appropriate to you. + After that, the bean creates an Identity object with the help of the + authenticator service, populates it with a subject containing the user + credentials and registers it. That's all we have to do to make the portal + aware of the user logging in.</para> + + <para>Registering our bean is done the usual way in security-context.xml + file:</para> + + <programlisting language="xml">... +&lt;beans:bean id="myEventHandler" class="org.exoplatform.spring.security.web.SpringSecurityEventHandler" /&gt; +...</programlisting> + </section> + + <section> + <title>Security context propagation to portlets</title> + + <para>Part of the problem is the question of security context propagation + between on one side the portal webapp and at the other side the portlets + webapps. This means that the security context has to be available in the + portlet side allowing the application logic to deal the with current user + principal and granted authorities. By default, Spring security uses a + thread local variable to partially achieve this. But a problem may arise + due to the fact that the portal invokes the portlet through a webapp cross + context call. This means that it can lead to a class cast exceptions (two + different classloaders involved), or that the security context is simply + not propagated at all. To accommodate this, we will need to set up two + request filters, one at the portal webapp side and the other at the + portlet webapp side and use the http request to propagate the context in + between.</para> + + <section> + <title>Portal side filter</title> + + <para>We will use the spring security extensible filter chain to plug in + our filter.</para> + + <programlisting language="java">package org.exoplatform.spring.security.web; + +... + +public class PortalSideSecurityContextFilter extends SpringSecurityFilter { + + @Override + protected void doFilterHttp(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws IOException, ServletException { + //fill request with security context + SecurityContext context = SecurityContextHolder.getContext(); + request.setAttribute(HttpSessionContextIntegrationFilter.SPRING_SECURITY_CONTEXT_KEY, context); + + //fill request with security last exception + Object e = request.getSession().getAttribute(AbstractProcessingFilter.SPRING_SECURITY_LAST_EXCEPTION_KEY); + request.setAttribute(AbstractProcessingFilter.SPRING_SECURITY_LAST_EXCEPTION_KEY, e); + + chain.doFilter(request, response); + } + + public int getOrder() { + // TODO Auto-generated method stub + return 0; + } +}</programlisting> + + <para>The PortalSideSecurityContextFilter simply fills the request with + the security context and security last exception using the + HttpSessionContextIntegrationFilter.SPRING_SECURITY_CONTEXT_KEY and + AbstractProcessingFilter.SPRING_SECURITY_LAST_EXCEPTION_KEY attribute + names. The portlet can have a look to the + AbstractProcessingFilter.SPRING_SECURITY_LAST_EXCEPTION_KEY attribute to + check if a security exception has occured.</para> + + <para>The following lines in the security-context file register our + custom filter in the chain at the last position.</para> + + <programlisting language="xml">... + &lt;beans:bean id="myCustomFilter" class="org.exoplatform.spring.security.web.PortalSideSecurityContextFilter"&gt; + &lt;custom-filter after="LAST" /&gt; + &lt;/beans:bean&gt; +...</programlisting> + </section> + + <section> + <title>Portlet side filter</title> + + <para>In the portlet webapp we create a regular filter named + PortletSideSecurityContextFilter.</para> + + <programlisting language="java">package org.exoplatform.spring.security.web; + +... + +public class PortletSideSecurityContextFilter implements Filter { + + public void destroy() { + + } + + public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain) throws IOException, ServletException { + Object object = request.getAttribute(HttpSessionContextIntegrationFilter.SPRING_SECURITY_CONTEXT_KEY); + SecurityContext context = (SecurityContext) serializeDeserialize(object); + if (context != null) { + SecurityContextHolder.setContext(context); + } else { + SecurityContextHolder.clearContext(); + } + + filterChain.doFilter(request, response); + } + + public void init(FilterConfig arg0) throws ServletException { + + } + + private Object serializeDeserialize(Object obj) { + Object result = null; + try { + ByteArrayOutputStream bout = new ByteArrayOutputStream(); + ObjectOutputStream out = new ObjectOutputStream(bout); + + out.writeObject(obj); + + ByteArrayInputStream bin = new ByteArrayInputStream(bout.toByteArray()); + ObjectInputStream in = new ObjectInputStream(bin); + + result = in.readObject(); + } catch (Exception e) { + //TODO: handle exception + } + return result; + } + +}</programlisting> + + <para>The PortletSideSecurityContextFilter retrieves the security + context from the request and proceeds to a serialization + de-serialization of it to avoid a potential class cast exception that + may occur when propagating an object across webapps. Then the context is + simply set or cleared whether the context is null or not.</para> + + <para>To register your filter simply add the following lines to your + portlet webapp web.xml file.</para> + + <programlisting language="xml">... + &lt;filter&gt; + &lt;filter-name&gt;portletSideSecurityContextFilter&lt;/filter-name&gt; + &lt;filter-class&gt;org.exoplatform.spring.security.web.PortletSideSecurityContextFilter&lt;/filter-class&gt; + &lt;/filter&gt; + + &lt;filter-mapping&gt; + &lt;filter-name&gt;portletSideSecurityContextFilter&lt;/filter-name&gt; + &lt;url-pattern&gt;/*&lt;/url-pattern&gt; + &lt;dispatcher&gt;REQUEST&lt;/dispatcher&gt; + &lt;dispatcher&gt;INCLUDE&lt;/dispatcher&gt; + &lt;dispatcher&gt;FORWARD&lt;/dispatcher&gt; + &lt;/filter-mapping&gt; +...</programlisting> + </section> + </section> + + <section> + <title>Conclusion</title> + + <para>We are done! Now we know how to integrate the spring security + framework in the eXo portal. Thanks to the the great integration + capabilities of both eXo portal and Spring framework. You can have a look + to the attachment section on this page and get the source code of this + tutorial.</para> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/tika-document-reader-service.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/tika-document-reader-service.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core/tika-document-reader-service.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,396 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Core.TikaDocumentReaderService"> + <?dbhtml filename="ch-core-document-reader-service.html"?> + + <title>Tika Document Reader Service</title> + + <section> + <title>Intro</title> + + <para>DocumentReaderService provides API to retrieve DocumentReader by + mimetype.</para> + + <para>DocumentReader lets the user fetch content of document as String or, + in case of TikaDocumentReader, as Reader.</para> + </section> + + <section> + <title>Architecture</title> + + <para>Basicaly, DocumentReaderService is a container for all registered + DocumentReaders. So, you can register DocumentReader (method + addDocumentReader(ComponentPlugin reader)) and fetch DocumentReader by + mimeType (method getDocumentReader(String mimeType)).</para> + + <para>TikaDocumentReaderServiceImpl extends DocumentReaderService with + simple goal - read Tika configuration and lazy register each Tika Parser + as TikaDocumentReader.</para> + + <para><note> + <para>By default, all Tikas Parsers are not registered in readers + &lt;mimetype, DocumentReader&gt; map. When user tries to fetch a + DocumentReader by unknown mimetype. Than TikaDocumentReaderService + checks tika configuration, and register a new mimetype-DocumentReader + pair.</para> + </note></para> + </section> + + <section> + <title>Configuration</title> + + <para>How TikaDocumentReaderService Impl configuration looks + like:</para> + <programlisting language="xml">&lt;component&gt; + &lt;key&gt;org.exoplatform.services.document.DocumentReaderService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.document.impl.tika.TikaDocumentReaderServiceImpl&lt;/type&gt; + + &lt;!-- Old-style document readers --&gt; + &lt;component-plugins&gt; + &lt;component-plugin&gt; + &lt;name&gt;pdf.document.reader&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.PDFDocumentReader&lt;/type&gt; + &lt;description&gt;to read the pdf inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;document.readerMSWord&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.MSWordDocumentReader&lt;/type&gt; + &lt;description&gt;to read the ms word inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;document.readerMSXWord&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.MSXWordDocumentReader&lt;/type&gt; + &lt;description&gt;to read the ms word inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;document.readerMSExcel&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.MSExcelDocumentReader&lt;/type&gt; + &lt;description&gt;to read the ms excel inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;document.readerMSXExcel&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.MSXExcelDocumentReader&lt;/type&gt; + &lt;description&gt;to read the ms excel inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;document.readerMSOutlook&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.MSOutlookDocumentReader&lt;/type&gt; + &lt;description&gt;to read the ms outlook inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;PPTdocument.reader&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.PPTDocumentReader&lt;/type&gt; + &lt;description&gt;to read the ms ppt inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;MSXPPTdocument.reader&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.MSXPPTDocumentReader&lt;/type&gt; + &lt;description&gt;to read the ms pptx inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;document.readerHTML&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.HTMLDocumentReader&lt;/type&gt; + &lt;description&gt;to read the html inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;document.readerXML&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.XMLDocumentReader&lt;/type&gt; + &lt;description&gt;to read the xml inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;TPdocument.reader&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.TextPlainDocumentReader&lt;/type&gt; + &lt;description&gt;to read the plain text inputstream&lt;/description&gt; + &lt;init-params&gt; + &lt;!-- + values-param&gt; &lt;name&gt;defaultEncoding&lt;/name&gt; &lt;description&gt;description&lt;/description&gt; &lt;value&gt;UTF-8&lt;/value&gt; + &lt;/values-param + --&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;document.readerOO&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.document.impl.OpenOfficeDocumentReader&lt;/type&gt; + &lt;description&gt;to read the OO inputstream&lt;/description&gt; + &lt;/component-plugin&gt; + + &lt;/component-plugins&gt; + + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;tika-configuration&lt;/name&gt; + &lt;value&gt;jar:/conf/portal/tika-config.xml&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; + + &lt;/component&gt; +&lt;/configuration&gt;</programlisting> + + <para>tika-config.xml example:</para> + <programlisting language="xml">&lt;properties&gt; + + &lt;mimeTypeRepository magic="false"/&gt; + &lt;parsers&gt; + + &lt;parser name="parse-dcxml" class="org.apache.tika.parser.xml.DcXMLParser"&gt; + &lt;mime&gt;application/xml&lt;/mime&gt; + &lt;mime&gt;image/svg+xml&lt;/mime&gt; + &lt;mime&gt;text/xml&lt;/mime&gt; + &lt;mime&gt;application/x-google-gadget&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-office" class="org.apache.tika.parser.microsoft.OfficeParser"&gt; + &lt;mime&gt;application/excel&lt;/mime&gt; + &lt;mime&gt;application/xls&lt;/mime&gt; + &lt;mime&gt;application/msworddoc&lt;/mime&gt; + &lt;mime&gt;application/msworddot&lt;/mime&gt; + &lt;mime&gt;application/powerpoint&lt;/mime&gt; + &lt;mime&gt;application/ppt&lt;/mime&gt; + + &lt;mime&gt;application/x-tika-msoffice&lt;/mime&gt; + &lt;mime&gt;application/msword&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-excel&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-excel.sheet.binary.macroenabled.12&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-powerpoint&lt;/mime&gt; + &lt;mime&gt;application/vnd.visio&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-outlook&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-ooxml" class="org.apache.tika.parser.microsoft.ooxml.OOXMLParser"&gt; + &lt;mime&gt;application/x-tika-ooxml&lt;/mime&gt; + &lt;mime&gt;application/vnd.openxmlformats-package.core-properties+xml&lt;/mime&gt; + &lt;mime&gt;application/vnd.openxmlformats-officedocument.spreadsheetml.sheet&lt;/mime&gt; + &lt;mime&gt;application/vnd.openxmlformats-officedocument.spreadsheetml.template&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-excel.sheet.macroenabled.12&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-excel.template.macroenabled.12&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-excel.addin.macroenabled.12&lt;/mime&gt; + &lt;mime&gt;application/vnd.openxmlformats-officedocument.presentationml.presentation&lt;/mime&gt; + &lt;mime&gt;application/vnd.openxmlformats-officedocument.presentationml.template&lt;/mime&gt; + &lt;mime&gt;application/vnd.openxmlformats-officedocument.presentationml.slideshow&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-powerpoint.presentation.macroenabled.12&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-powerpoint.slideshow.macroenabled.12&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-powerpoint.addin.macroenabled.12&lt;/mime&gt; + &lt;mime&gt;application/vnd.openxmlformats-officedocument.wordprocessingml.document&lt;/mime&gt; + &lt;mime&gt;application/vnd.openxmlformats-officedocument.wordprocessingml.template&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-word.document.macroenabled.12&lt;/mime&gt; + &lt;mime&gt;application/vnd.ms-word.template.macroenabled.12&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-html" class="org.apache.tika.parser.html.HtmlParser"&gt; + &lt;mime&gt;text/html&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser mame="parse-rtf" class="org.apache.tika.parser.rtf.RTFParser"&gt; + &lt;mime&gt;application/rtf&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-pdf" class="org.apache.tika.parser.pdf.PDFParser"&gt; + &lt;mime&gt;application/pdf&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-txt" class="org.apache.tika.parser.txt.TXTParser"&gt; + &lt;mime&gt;text/plain&lt;/mime&gt; + &lt;mime&gt;script/groovy&lt;/mime&gt; + &lt;mime&gt;application/x-groovy&lt;/mime&gt; + &lt;mime&gt;application/x-javascript&lt;/mime&gt; + &lt;mime&gt;application/javascript&lt;/mime&gt; + &lt;mime&gt;text/javascript&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-openoffice" class="org.apache.tika.parser.opendocument.OpenOfficeParser"&gt; + + &lt;mime&gt;application/vnd.oasis.opendocument.database&lt;/mime&gt; + + &lt;mime&gt;application/vnd.sun.xml.writer&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.text&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.graphics&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.presentation&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.spreadsheet&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.chart&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.image&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.formula&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.text-master&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.text-web&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.text-template&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.graphics-template&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.presentation-template&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.spreadsheet-template&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.chart-template&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.image-template&lt;/mime&gt; + &lt;mime&gt;application/vnd.oasis.opendocument.formula-template&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.text&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.graphics&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.presentation&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.spreadsheet&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.chart&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.image&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.formula&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.text-master&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.text-web&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.text-template&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.graphics-template&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.presentation-template&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.spreadsheet-template&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.chart-template&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.image-template&lt;/mime&gt; + &lt;mime&gt;application/x-vnd.oasis.opendocument.formula-template&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-image" class="org.apache.tika.parser.image.ImageParser"&gt; + &lt;mime&gt;image/bmp&lt;/mime&gt; + &lt;mime&gt;image/gif&lt;/mime&gt; + &lt;mime&gt;image/jpeg&lt;/mime&gt; + &lt;mime&gt;image/png&lt;/mime&gt; + &lt;mime&gt;image/tiff&lt;/mime&gt; + &lt;mime&gt;image/vnd.wap.wbmp&lt;/mime&gt; + &lt;mime&gt;image/x-icon&lt;/mime&gt; + &lt;mime&gt;image/x-psd&lt;/mime&gt; + &lt;mime&gt;image/x-xcf&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-class" class="org.apache.tika.parser.asm.ClassParser"&gt; + &lt;mime&gt;application/x-tika-java-class&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-mp3" class="org.apache.tika.parser.mp3.Mp3Parser"&gt; + &lt;mime&gt;audio/mpeg&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-midi" class="org.apache.tika.parser.audio.MidiParser"&gt; + &lt;mime&gt;application/x-midi&lt;/mime&gt; + &lt;mime&gt;audio/midi&lt;/mime&gt; + &lt;/parser&gt; + + &lt;parser name="parse-audio" class="org.apache.tika.parser.audio.AudioParser"&gt; + &lt;mime&gt;audio/basic&lt;/mime&gt; + &lt;mime&gt;audio/x-wav&lt;/mime&gt; + &lt;mime&gt;audio/x-aiff&lt;/mime&gt; + &lt;/parser&gt; + + &lt;/parsers&gt; + +&lt;/properties&gt;</programlisting> + </section> + + <section> + <title>Old-style DocumentReaders and Tika Parsers</title> + + <para>As you see configuration above, there is both old-style + DocumentReaders and new Tika parsers registered.</para> + + <para><emphasis>But MSWordDocumentReader and + org.apache.tika.parser.microsoft.OfficeParser both refer to same + "application/msword"</emphasis> mimetype, exclaims attentive reader. And + he is right. But only one DocumentReader will be fetched.</para> + + <para>Old-style DocumentReader registered in configuration become + registered into DocumentReaderService. So, mimetypes that is supported by + those DocumentReaders will have a registered pair, and user will always + fetch this DocumentReaders with getDocumentReader(..) method. Tika + configuration will be checked for Parsers only if there is no already + registered DocumentReader.</para> + + <section> + <title>How to make and register own DocumentReader</title> + + <para>You can make you own DocumentReader in two ways.</para> + + <para><emphasis role="bold">Old-Style Document + Reader</emphasis>:</para> + <itemizedlist> + <listitem> + <para>extend BaseDocumentReader</para> + </listitem> + </itemizedlist> + <programlisting language="java">public class MyDocumentReader extends BaseDocumentReader +{ + public String[] getMimeTypes() + { + return new String[]{"mymimetype"}; + } + ... +}</programlisting> + + <itemizedlist> + <listitem> + <para>register it as component-plugin</para> + </listitem> + </itemizedlist> + <programlisting language="xml">&lt;component-plugin&gt; + &lt;name&gt;my.DocumentReader&lt;/name&gt; + &lt;set-method&gt;addDocumentReader&lt;/set-method&gt; + &lt;type&gt;com.mycompany.document.MyDocumentReader&lt;/type&gt; + &lt;description&gt;to read my own file format&lt;/description&gt; +&lt;/component-plugin&gt;</programlisting> + + + + <para><emphasis role="bold">Tika Parser</emphasis>:</para> + <itemizedlist> + <listitem> + <para>implement Parser</para> + </listitem> + </itemizedlist> + <programlisting language="java">public class MyParser implements Parser +{ + ... +}</programlisting> + + <itemizedlist> + <listitem> + <para>register it in tika-config.xml</para> + </listitem> + </itemizedlist> +<programlisting language="xml"> &lt;parser name="parse-mydocument" class="com.mycompany.document.MyParser"&gt; + &lt;mime&gt;mymimetype&lt;/mime&gt; + &lt;/parser&gt; +</programlisting> + + + </section> + </section> + + <section> + <title>TikaDocumentReader features and notes</title> + + <para>TikaDocumentReader features and notes:<itemizedlist> + <listitem> + <para>TikaDocumentReader may return document contant as Reader + object. Old-Style DocumentReader does not;</para> + </listitem> + + <listitem> + <para>TikaDocumentReader do not detects document mimetipe. You will + get exact parser as configured in tika-config;</para> + </listitem> + + <listitem> + <para>All readers methods closes InputStream at final.</para> + </listitem> + </itemizedlist></para> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/core.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,46 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<part> + <?dbhtml filename="part-core.html"?> + + <title>eXoCore</title> + + <xi:include href="core/core.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/db-creator-service.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/security-service.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/spring-security-integration.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/organization-service.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/organization-service-initalizer.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/organization-service-listener.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/conversationstate-when-membership-changed.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/db-schema-creator-service.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/db-configuration-hibernate.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/ldap-configuration.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/tika-document-reader-service.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="core/digest-auth.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> +</part> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/faq/jcr-faq.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/faq/jcr-faq.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/faq/jcr-faq.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -33,18 +33,17 @@ <varlistentry> <term>Is it better to use Session.getNodeByUUID or Session.getItem?</term> <listitem> - <para> - Session.getNodeByUUID() about 2.5 times faster of Session.getItem(String) and only 25% faster of Node.getNode(String). See the daily tests results for such comparisons, e.g. - </para> - <para> - <ulink url="http://tests.exoplatform.org/JCR/1.12.2-GA/rev.2442/daily-perfo... - </para> + <para><literal>Session.getNodeByUUID()</literal> is about 2.5 times faster than <literal>Session.getItem(String)</literal> and 25% faster than <literal>Node.getNode(String)</literal>. + See the daily tests results for such comparisons, e.g.</para> + <para><ulink + url="http://tests.exoplatform.org/JCR/1.12.2-GA/rev.2442/daily-perfo... + </listitem> </varlistentry> <varlistentry> - <term>Does it make sense to have all the node referenceable to use getNodeByUUID all the time?</term> + <term>Does it make sense to have all the node referenceable to use <literal>getNodeByUUID</literal> all the time?</term> <listitem> <para> Until it's applicable for a business logic it can be. But take in account the paths are human readable and lets you think in hierarchy. If it's important a location based approach is preferable. @@ -56,9 +55,8 @@ <varlistentry> <term>What should I use to check if an Item exists before getting the Value?</term> <listitem> - <para> - Use Session.itemExists(String absPath), Node.hasNode(String relPath) or Property.hasProperty(String name). It's also is possible to check Node.hasNodes() and Node.hasProprties(). - </para> + <para>Use <literal>Session.itemExists(String absPath)</literal>, <literal>Node.hasNode(StringrelPath)</literal> or <literal>Property.hasProperty(String name)</literal>. It is also is possible + to check <literal>Node.hasNodes()</literal> and <literal>Node.hasProprties()</literal>.</para> </listitem> @@ -67,8 +65,11 @@ <term>How to use Observation properly?</term> <listitem> <para> - JCR Observation's a way to listen on persistence changes of a Repository. It provides several options to configure the listener for an interesting only changes. To use properly, it's important to understand concept of events filtering for a registered EventListener (8.3.3 Observation Manager). An often confusing part, it's the <emphasis role="bold">absPath</emphasis>, it's an associated parent of a location you want to observe events on. I.e. it's a parent of child node(s) or this parent property(ies); if <emphasis role="bold">isDeep</emphasis> is true then you'll get events of all the subtree of child nodes also. The same actual for <emphasis role="bold">uuid</emphasis> and <emphasis role="bold">nodeTypeName</emphasis> parameters of ObservationManager.addEventListener() method. + JCR Observation's a way to listen on persistence changes of a Repository. It provides several options to configure the listener for an interesting only changes. To use properly, it's important to understand concept of events filtering for a registered EventListener. </para> + <para> + An often confusing part is the <emphasis role="bold">absPath</emphasis>, it's an associated parent of a location you want to observe events on. I.e. it's a parent of child node(s) or this parent property(ies); if <emphasis role="bold">isDeep</emphasis> is true then you'll get events of all the subtree of child nodes also. The same actual for <emphasis role="bold">uuid</emphasis> and <emphasis role="bold">nodeTypeName</emphasis> parameters of ObservationManager.addEventListener() method. + </para> </listitem> @@ -87,7 +88,7 @@ <term>What is default query ordering?</term> <listitem> <para> - By default (if query do not contains any ordering statements) result nodes is sorted by document order. + By default (if queries do not contain any ordering statements) result nodes are sorted by document order. </para> </listitem> @@ -97,18 +98,18 @@ <term>Is ordering by jcr:path or Item name supported?</term> <listitem> <para> - No, it does not supported. There is two ways to ordering results, when path may be used as criteria: + No, it is not supported. There are two ways to order results, in which <emphasis>path</emphasis> may be used as criteria: </para> <itemizedlist> <listitem> <para> - Order by property with value type NAME or PATH (jcr supports it). + Order by property with value type NAME or PATH (supported). </para> </listitem> <listitem> <para> - Order by jcr:path - sort by exact path of node (jcr do not supports it). + Order by jcr:path - sort by exact path of node (not supported. </para> </listitem> @@ -118,10 +119,10 @@ Order by jcr:path </para> <para> - If no order specification is supplied in the query statement, implementations may support document order on the result nodes (see 6.6.4.2 Document Order). And it is sorted by order number. + If no order specification is supplied in the query statement, implementations may support document order on the result nodes. And it is sorted by order number. </para> <para> - By default, (if query do not contains any ordering statements) result nodes is sorted by document order. + By default, (if a query does not contain any ordering statements) result nodes is sorted by document order. </para> <programlisting>SELECT * FROM nt:unstructured WHERE jcr:path LIKE 'testRoot/%'</programlisting> @@ -248,7 +249,211 @@ </para> </listitem> + + </varlistentry> + <varlistentry> + <term>How to configure jcr for cluster?</term> + <listitem> + <para>So we have configured JCR in standalone mode and want to + reconfigure it for clustered environment. First of all, let's check + whether all requirements are satisfied:</para> + <itemizedlist> + <listitem> + <para>Dedicated RDBMS anyone like MySQL, Postges, Oracle and, etc + but just not HSSQL;</para> + </listitem> + + <listitem> + <para>Shared storage. The simplest thing is to use shared FS like + NFS or SMB mounted in operation system, but they are rather slow. + The best thing is to use SAN (Storage Area Network);</para> + </listitem> + + <listitem> + <para>Fast network between JCR nodes.</para> + </listitem> + </itemizedlist> + <para>So now, need to configure Container a bit. Check + exo-configuration.xml to be sure that you are using JBossTS + Transaction Service and JBossCache Transaction Manager, as shown + below.</para> +<programlisting language="xml">&lt;component&gt; + &lt;key&gt;org.jboss.cache.transaction.TransactionManagerLookup&lt;/key&gt; + &lt;type&gt;org.jboss.cache.GenericTransactionManagerLookup&lt;/type&gt; +&lt;/component&gt; + +&lt;component&gt; + &lt;key&gt;org.exoplatform.services.transaction.TransactionService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.transaction.jbosscache.JBossTransactionsService&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;timeout&lt;/name&gt; + &lt;value&gt;300&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</programlisting> + <para>Next stage is actually the JCR configuration. We need JBossCache + configuration templates for : data-cache, indexer-cache and + lock-manager-cache. Later they will be used to configure JCR's core + components. There are pre-bundled templates in EAR or JAR in + conf/standalone/cluster. They can be used as is or re-written if + needed. And now, re-configure a bit each workspace. Actually, a few + parameters need changing, e.g. &lt;cache&gt;, &lt;query-handler&gt; + and &lt;lock-manager&gt;.</para> + <itemizedlist> + <listitem> + <para>&lt;cache&gt; configuration should look like this:</para> +<programlisting language="xml">&lt;cache enabled="true" + class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"&gt; + &lt;properties&gt; + &lt;property name="jbosscache-configuration" value="test-jbosscache-data.xml" /&gt; + &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; + &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; + &lt;property name="jbosscache-cluster-name" value="JCR-cluster-db1-ws" /&gt; + &lt;/properties&gt; +&lt;/cache&gt;</programlisting> + </listitem> + <listitem> + <para>"jbosscache-configuration" is the path to configuration + template;</para> + </listitem> + + <listitem> + <para>"jgroups-configuration" is path to JGroups configuration + that is multiplexer stack is used (default). This file is also + pre-bundled with templates and is recommended for use;</para> + </listitem> + + <listitem> + <para>"jgroups-multiplexer-stack" just simply "true". Strongly + recommended;</para> + </listitem> + + <listitem> + <para>"jbosscache-cluster-name" is the name of cluster group. + It should be different for each workspace and each workspace + component. I.e.: + &lt;repository_name&gt;-&lt;ws_name&gt;-&lt;component(cache\|lock\|index)&gt;</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para>&lt;query-handler&gt; configuration</para> + + <itemizedlist> + <listitem> + <para>You must replace or add in &lt;query-handler&gt; block + the "changesfilter-class" parameter equals with:</para> + + <programlisting language="xml">&lt;property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter"/&gt;</programlisting> + </listitem> + + <listitem> + <para>add JBossCache-oriented configuration:</para> + + <programlisting language="xml">&lt;property name="jbosscache-configuration" value="test-jbosscache-indexer.xml" /&gt; +&lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; +&lt;property name="jgroups-multiplexer-stack" value="true" /&gt; +&lt;property name="jbosscache-cluster-name" value="JCR-cluster-indexer-db1-ws" /&gt; +&lt;property name="max-volatile-time" value="60" /&gt;</programlisting> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + + <para>Those properties have the same meaning and restrictions as in + the previous block. The last property "max-volatile-time" is not + mandatory but recommended. This notifies that the latest changes in + index will be visible for each cluster node not later than in + 60s.</para> + + <itemizedlist> + <listitem> + <para>&lt;lock-manager&gt; configuration</para> + + <para>Maybe this is the hardest element to configure, because we + have to define access to DB where locks will be stored. Replace + exsiting lock-manager configuration with shown below.</para> + + <programlisting language="xml"> +&lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; + &lt;properties&gt; + &lt;property name="time-out" value="15m" /&gt; + &lt;property name="jbosscache-configuration" value="test-jbosscache-lock.xml" /&gt; + &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; + &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; + &lt;property name="jbosscache-cluster-name" value="JCR-cluster-locks-db1-ws" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_db1_ws" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.create" value="true" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.drop" value="false" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_db1_ws_pk" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.node.column" value="node" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" /&gt; + &lt;/properties&gt; +&lt;/lock-manager&gt; + +</programlisting> + + <para>First few properties are the same as in the previous + components, but here you can see some strange + "jbosscache-cl-cache.jdbc.*" properties. They define access + parameters for database where lock are persisted.</para> + + <itemizedlist> + <listitem> + <para>"jbosscache-cl-cache.jdbc.table.create" - whether to + create it or not. Usually "true";</para> + </listitem> + + <listitem> + <para>"jbosscache-cl-cache.jdbc.table.drop" - whether to drop + on a start or not. Use "false";</para> + </listitem> + + <listitem> + <para>"jbosscache-cl-cache.jdbc.table.primarykey" - the name + of column with pk;</para> + </listitem> + + <listitem> + <para>"jbosscache-cl-cache.jdbc.fqn.column" - the name of one + more column. If you are not sure how to use, follow the + example above (if much interested, please refer to JBossCache + JDBCCacheLoader documentation)</para> + </listitem> + + <listitem> + <para>"jbosscache-cl-cache.jdbc.node.column" - the name of one + more column. If you are not sure how to use, follow the + example above (if much interested, please refer to JBossCache + JDBCCacheLoader documentation)</para> + </listitem> + + <listitem> + <para>"jbosscache-cl-cache.jdbc.parent.column" - name of one + more column. If you are not sure how to use, follow the + example above if you are not sure (if much interested, please + refer to JBossCache JDBCCacheLoader documentation)</para> + </listitem> + + <listitem> + <para>"jbosscache-cl-cache.jdbc.datasource" - name of + configured in Container datasource, where you want to store + locks. The best idea is to use the same as for + workspace.</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + + <para>That's all. JCR is ready for running in a cluster.</para> + </listitem> </varlistentry> <varlistentry> <term>Is JCR suitable for remote sites\* synchronization?</term> @@ -308,7 +513,7 @@ </itemizedlist> <para> - If there is no any results, that means there is no suggestion, so word is correct or spellcheckers dictionary do not contain any words like the checked word. + If there are no results, that means there is no suggestion, so word is correct or spellcheckers dictionary do not contain any words like the checked word. </para> </listitem> @@ -465,7 +670,9 @@ </variablelist> - </section> --> <section id="sect-Reference_Guide_eXo_JCR_1.14-JCR_FAQ-WebDAV"> + </section> --> + +<section id="sect-Reference_Guide_eXo_JCR_1.14-JCR_FAQ-WebDAV"> <title>WebDAV</title> <variablelist> <title></title> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/backup-client.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/backup-client.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/backup-client.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -1472,9 +1472,6 @@ &lt;init-params&gt; &lt;properties-param&gt; &lt;name&gt;backup-properties&lt;/name&gt; - &lt;property name="default-incremental-job-period" value="3600" /&gt; &lt;!-- set default incremental periond = 60 minutes --&gt; - &lt;property name="full-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob" /&gt; - &lt;property name="incremental-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob" /&gt; &lt;property name="backup-dir" value="../temp/backup" /&gt; &lt;/properties-param&gt; &lt;/init-params&gt; @@ -1514,8 +1511,6 @@ For JBoss Enterprise Portal Platform you should use context "<emphasis>/portal/rest</emphasis>". JBoss Enterprise Portal Platform uses form authentication, so first you need to login (url to form authentication is <uri>http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/<replaceable>portal</replaceable>/login</uri>) and then perform requests. </para> <para> - </para> - <para> The backup client supports form authentication. For example, the following would call the <emphasis>info</emphasis> command with form authentication to JBoss Enterprise Portal Platform : </para> <para> @@ -1547,13 +1542,13 @@ stop &lt;backup_id&gt; status &lt;backup_id&gt; restores &lt;repo[/ws]&gt; - restore [remove-exists] [&lt;repo[/ws]&gt;] {&lt;backup_id&gt;|&lt;backup_set_path&gt;} [&lt;pathToConfigFile&gt;] + restore [remove-exists] {{&lt;backup_id&gt;|&lt;backup_set_path&gt;} | {&lt;repo[/ws]&gt; {&lt;backup_id&gt;|&lt;backup_set_path&gt;} [&lt;pathToConfigFile&gt;]}} list [completed] info drop [force-close-session] &lt;repo[/ws]&gt; help - start - start backup of repositpry or workspace + start - start backup of repository or workspace stop - stop backup status - information about the current or completed backup by 'backup_id' restores - information about the last restore on specific repository or workspace @@ -1570,9 +1565,23 @@ &lt;backup_set_dir&gt; - path to folder with backup set on remote server &lt;incr&gt; - incemental job period &lt;pathToConfigFile&gt; - path (local) to repository or workspace configuration - remove-exists - removed fully (db, value storage, index) existed repository/workspace - force-close-session - close opened sessions on repositpry or workspace.</screen> + remove-exists - remove fully (db, value storage, index) exists repository/workspace + force-close-session - close opened sessions on repository or workspace. + All valid combination of parameters for command restore: + 1. restore remove-exists &lt;repo/ws&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 2. restore remove-exists &lt;repo&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 3. restore remove-exists &lt;repo/ws&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 4. restore remove-exists &lt;repo&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 5. restore remove-exists &lt;backup_id&gt; + 6. restore remove-exists &lt;backup_set_path&gt; + 7. restore &lt;repo/ws&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 8. restore &lt;repo&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 9. restore &lt;repo/ws&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 10. restore &lt;repo&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 11. restore &lt;backup_id&gt; + 12. restore &lt;backup_set_path&gt; </screen> + </section> <section id="sect-Reference_Guide_eXo_JCR_1.14-HTTPBackupAgent_and_Backup_Client-Building_and_Running_Application"> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/backup-clonsole-dist.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/backup-clonsole-dist.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/backup-clonsole-dist.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -40,7 +40,7 @@ stop &lt;backup_id&gt; status &lt;backup_id&gt; restores &lt;repo[/ws]&gt; - restore [remove-exists] [&lt;repo[/ws]&gt;] {&lt;backup_id&gt;|&lt;backup_set_path&gt;} [&lt;pathToConfigFile&gt;] + restore [remove-exists] {{&lt;backup_id&gt;|&lt;backup_set_path&gt;} | {&lt;repo[/ws]&gt; {&lt;backup_id&gt;|&lt;backup_set_path&gt;} [&lt;pathToConfigFile&gt;]}} list [completed] info drop [force-close-session] &lt;repo[/ws]&gt; @@ -63,8 +63,23 @@ &lt;incr&gt; : incremental job period &lt;pathToConfigFile&gt; : path (local) to repository or workspace configuration remove-exists : remove fully (db, value storage, index) exists repository/workspace -force-close-session : close opened sessions on repository or workspace</programlisting> +force-close-session : close opened sessions on repository or workspace + +All valid combination of parameters for command restore: + 1. restore remove-exists &lt;repo/ws&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 2. restore remove-exists &lt;repo&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 3. restore remove-exists &lt;repo/ws&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 4. restore remove-exists &lt;repo&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 5. restore remove-exists &lt;backup_id&gt; + 6. restore remove-exists &lt;backup_set_path&gt; + 7. restore &lt;repo/ws&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 8. restore &lt;repo&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 9. restore &lt;repo/ws&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 10. restore &lt;repo&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 11. restore &lt;backup_id&gt; + 12. restore &lt;backup_set_path&gt; +</programlisting> </section> <section id="sect-Reference_Guide_eXo_JCR_1.14-Backup_Console_Binary_Distribution-exobackup.sh_and_exobackup.cmd"> @@ -86,7 +101,7 @@ stop &lt;backup_id&gt; status &lt;backup_id&gt; restores &lt;repo[/ws]&gt; - restore [remove-exists] [&lt;repo[/ws]&gt;] {&lt;backup_id&gt;|&lt;backup_set_path&gt;} [&lt;pathToConfigFile&gt;] + restore [remove-exists] {{&lt;backup_id&gt;|&lt;backup_set_path&gt;} | {&lt;repo[/ws]&gt; {&lt;backup_id&gt;|&lt;backup_set_path&gt;} [&lt;pathToConfigFile&gt;]}} list [completed] info drop [force-close-session] &lt;repo[/ws]&gt; @@ -108,8 +123,22 @@ &lt;incr&gt; : incremental job period &lt;pathToConfigFile&gt; : path (local) to repository or workspace configuration remove-exists : remove fully (db, value storage, index) exists repository/workspace -force-close-session : close opened sessions on repository or workspace</programlisting> +force-close-session : close opened sessions on repository or workspace + +All valid combination of parameters for command restore: + 1. restore remove-exists &lt;repo/ws&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 2. restore remove-exists &lt;repo&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 3. restore remove-exists &lt;repo/ws&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 4. restore remove-exists &lt;repo&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 5. restore remove-exists &lt;backup_id&gt; + 6. restore remove-exists &lt;backup_set_path&gt; + 7. restore &lt;repo/ws&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 8. restore &lt;repo&gt; &lt;backup_id&gt; &lt;pathToConfigFile&gt; + 9. restore &lt;repo/ws&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 10. restore &lt;repo&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; + 11. restore &lt;backup_id&gt; + 12. restore &lt;backup_set_path&gt; </programlisting> </section> <section id="sect-Reference_Guide_eXo_JCR_1.14-Backup_Console_Binary_Distribution-Backup_Console_Binary_Distribution_Usage"> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/exojcr-backup-service.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/exojcr-backup-service.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/backup/exojcr-backup-service.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -16,9 +16,6 @@ The main purpose of this feature is to restore data in case of system faults and repository crashes. Also, the backup results may be used as a content history. </para> <para> - The eXo JCR backup service was developed from the JCR 1.8 implementation. It is an independent service available as an eXo JCR Extensions project. - </para> - <para> The concept is based on the export of a workspace unit in the <emphasis>Full</emphasis>, or <emphasis>Full + Incremental</emphasis> model. A repository workspace can be backup and restored using a combination of these modes. </para> <para> @@ -79,6 +76,10 @@ <para> Restoring an incremental backup consists in applying the collected set of ChangesLogs to a workspace in the correct order. </para> + <note> + <title></title> + <para>Incremental backup is an experimental feature and not supported. Please use it with caution.</para> + </note> </section> @@ -182,7 +183,7 @@ As an optional extension, the Backup service is not enabled by default. <emphasis role="bold">You need to enable it via configuration</emphasis>. </para> <para> - The following is an example configuration compatible with JCR 1.9.3 and later: + The following is an example configuration: </para> <programlistingco> @@ -198,39 +199,73 @@ &lt;init-params&gt; &lt;properties-param&gt; &lt;name&gt;backup-properties&lt;/name&gt; - &lt;property name="default-incremental-job-period" value="3600" /&gt; &lt;!-- set default incremental period = 60 minutes --&gt; - &lt;property name="full-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob" /&gt; - &lt;property name="incremental-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob" /&gt; &lt;property name="backup-dir" value="target/backup" /&gt; &lt;/properties-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> <calloutlist> - <!--#--> + <title>Mandatory parameter</title> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-eXo_JCR_Backup_Service-Configuration-backup-dir"> + <para> + <parameter>backup-dir</parameter> is the path to a working directory where the service will store internal files and chain logs. + </para> + </callout> + </calloutlist> + <calloutlist> + <title>Optional parameters</title> <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-eXo_JCR_Backup_Service-Configuration-incremental-backup-type"> <para> - <parameter>incremental-backup-type</parameter> (since 1.9.3) is the FQN of incremental job class. It must implement <literal>org.exoplatform.services.jcr.ext.backup.BackupJob</literal>. + <parameter>incremental-backup-type</parameter> The FQN of incremental job class. Must implement <literal>org.exoplatform.services.jcr.ext.backup.BackupJob</literal>. By default, <literal>org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob</literal> is used. </para> </callout> <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-eXo_JCR_Backup_Service-Configuration-full-backup-type"> <para> - <parameter>full-backup-type</parameter> (since 1.9.3) is the FQN of the full backup job class; it must implement <literal>org.exoplatform.services.jcr.ext.backup.BackupJob</literal>. + <parameter>full-backup-type</parameter> is the FQN of the full backup job class. It must implement <literal>org.exoplatform.services.jcr.ext.backup.BackupJob</literal>. By default, <literal>org.exoplatform.services.jcr.ext.backup.impl.rdbms.FullBackupJob</literal> is used. Please, notice that file-system based implementation <literal>org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob</literal> is deprecated and not recommended for use.. </para> </callout> <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-eXo_JCR_Backup_Service-Configuration-default-incremental-job-period"> <para> - <parameter>default-incremental-job-period</parameter> (since 1.9.3) is the period between incremental flushes (in seconds). + <parameter>default-incremental-job-period</parameter> is the period between incremental flushes (in seconds). Default is <literal>3600</literal> seconds. </para> </callout> - <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-eXo_JCR_Backup_Service-Configuration-backup-dir"> - <para> - <parameter>backup-dir</parameter> is the path to a working directory where the service will store internal files and chain logs. - </para> - </callout> </calloutlist> </programlistingco> </section> - + <section> + <title>RDBMS backup</title> + + <para>RDBMS backup It is the lastest, currently supportedm used by default + and recommended implementation of full backup job for BackupManager + service. It is useful in case when database is used to store data.</para> + + <para>Brings such advantages:</para> + + <para><itemizedlist> + <listitem> + <para>fast: backup takes only several minutes to perform full backup + of repository with 1 million rows in tables;</para> + </listitem> + + <listitem> + <para>atomic restore: restore process into existing + workspace/repository with same configuration is atomic, it means you + don’t loose the data when restore failed, the original data + remains;</para> + </listitem> + + <listitem> + <para>cluster aware: it is possible to make backup/restore in + cluster environment into existing workspace/repository with same + configuration;</para> + </listitem> + + <listitem> + <para>consistence backup: all threads make waiting until backup is + finished and then continue to work, so, there are no data + modification during backup process;</para> + </listitem> + </itemizedlist></para> + </section> <section id="sect-Reference_Guide_eXo_JCR_1.14-eXo_JCR_Backup_Service-Usage"> <title>Usage</title> <section id="sect-Reference_Guide_eXo_JCR_1.14-Usage-Performing_a_Backup"> @@ -919,69 +954,6 @@ </para> </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-eXo_JCR_Backup_Service-RDBMS_backup"> - <title>RDBMS backup</title> - <para> - RDBMS backup is another implementation of a full backup job for <literal>BackupManager</literal> service. - </para> + </section> - <variablelist> - <title>Advantages of RDBMS backup</title> - <varlistentry> - <term>Speed</term> - <listitem> - <para> - It only takes minutes to perform full backup of repository with 1 million rows in tables; - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Atomic restore</term> - <listitem> - <para> - The restore process into existing workspace/repository with same configuration is atomic. This means you do not lose the data if the restore fails; the original data is retained; - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Cluster aware</term> - <listitem> - <para> - It is possible to backup into or restore from a cluster environment into existing workspace/repository with same configuration; - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Consistent backup</term> - <listitem> - <para> - All threads wait until the backup is finished and before resuming, ensuring there are no data modification during backup process; - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Configuration: - </para> - -<programlisting language="XML">&lt;component&gt; - &lt;key&gt;org.exoplatform.services.jcr.ext.backup.BackupManager&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;properties-param&gt; - &lt;name&gt;backup-properties&lt;/name&gt; - &lt;property name="default-incremental-job-period" value="3600" /&gt; &lt;!-- set default incremental period = 60 minutes --&gt; - &lt;property name="full-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.rdbms.FullBackupJob" /&gt; - &lt;property name="incremental-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob" /&gt; - &lt;property name="backup-dir" value="target/backup" /&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; -&lt;/component&gt; -</programlisting> - </section> - -</section> - - Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/cluster-config.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/cluster-config.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/cluster-config.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,50 +4,46 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Cluster_Config"> - <!-- This document was created with Syntext Serna Free. --> <title>Cluster Config</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Cluster_Config-Launching_Cluster"> - <title>Launching Cluster</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Deploying_eXo_JCR_to_JBoss_As"> - <title>Deploying eXo JCR to JBoss As</title> - <para> - To deploy eXo JCR to JBoss, do the following steps: - </para> - <orderedlist> - <listitem> - <para> - Download the latest version of eXo JCR .ear file distribution. - </para> - - </listitem> - <listitem> - <para> - Copy &lt;jcr.ear&gt; into &lt;%jboss_home%/server/default/deploy&gt; - </para> - - </listitem> - <listitem> - <para> - Put exo-configuration.xml to the root &lt;%jboss_home%/exo-configuration.xml&gt; - </para> - - </listitem> - <listitem> - <para> - Configure JAAS by inserting XML fragment shown below into &lt;%jboss_home%/server/default/conf/login-config.xml&gt; - </para> - + <!-- This document was created with Syntext Serna Free. --> + <title>Cluster Configuration</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Cluster_Config-Launching_Cluster"> + <title>Launching Cluster</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Deploying_eXo_JCR_to_JBoss_As"> + <title>Deploying eXo JCR to JBoss Application Server</title> + <para> + To deploy eXo JCR to the JBoss AS, do the following: + </para> + <procedure> + <title></title> + <step> + <para> + Download the latest version of eXo JCR <filename>.ear</filename> file distribution. + </para> + </step> + <step> + <para> + Copy the file into <filename>&lt;%jboss_home%/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy&gt;</filename> directory. + </para> + </step> + <step> + <para> + Drop <filename>exo-configuration.xml</filename> into your root <replaceable>&lt;JBOSS_HOME&gt;</replaceable> directory. + </para> + </step> + <step> + <para> + Configure JAAS by inserting the XML fragment shown below into <filename>&lt;JBOSS_HOME&gt;/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/login-config.xml</filename> + </para> <programlisting language="XML" role="XML">&lt;application-policy name="exo-domain"&gt; &lt;authentication&gt; &lt;login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required"&gt;&lt;/login-module&gt; &lt;/authentication&gt; &lt;/application-policy&gt;</programlisting> - - </listitem> - <listitem> - <para> - Ensure that you use JBossTS and JBossCache <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-JBossTransactionsService" />. Your exo-configuration.xml must contain such parts: - </para> - + </step> + <step> + <para> + To ensure that <emphasis>JBossTS</emphasis> and <emphasis>JBossCache</emphasis> are used, your <filename>configuration.xml</filename> file must contain: + </para> <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;org.jboss.cache.transaction.TransactionManagerLookup&lt;/key&gt; &lt;type&gt;org.jboss.cache.GenericTransactionManagerLookup&lt;/type&gt;^ @@ -63,48 +59,47 @@ &lt;/value-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> - - </listitem> - <listitem> - <para> - Start server: - </para> - <itemizedlist> - <listitem> - <para> - bin/run.sh for Unix - </para> - - </listitem> - <listitem> - <para> - bin/run.bat for Windows - </para> - - </listitem> - - </itemizedlist> - - </listitem> - <listitem> - <para> - Try accessing <uri>http://localhostu:8080/browser</uri> with root/exo as login/password if you have done everything right, you'll get access to repository browser. - </para> - - </listitem> - - </orderedlist> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Configuring_JCR_to_use_external_configuration"> - <title>Configuring JCR to use external configuration</title> - <itemizedlist> - <listitem> - <para> - To manually configure repository, create a new configuration file (e.g., exo-jcr-configuration.xml). For details, see <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-JCR_configuration" />. Your configuration must look like: - </para> - + </step> + <step> + <para> + Start server: + </para> + <para> + In Linux systems: + </para> +<programlisting><command>sh bin/run.sh</command> +</programlisting> + <para> + In Windows systems: + </para> +<programlisting><command>bin/run.bat</command> +</programlisting> + </step> + <step> + <para> + Navigate to <ulink type="http" url="http://localhostu:8080/browser"></ulink> ans use the credentials <emphasis role="bold">root</emphasis>/<emphasis role="bold">exo</emphasis> (login/password). + </para> + </step> + </procedure> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Configuring_JCR_to_use_external_configuration"> + <title>Configuring JCR to use external configuration</title> + <itemizedlist> + <listitem> + <para> + To manually configure a repository, create a new configuration file (<filename>exo-jcr-configuration.xml</filename> for example). For details, see <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-JCR_configuration" />. + </para> + <para> + The configuration file must be formatted as follows: + </para> +<programlistingco> + <areaspec> + <area coords="20" id="area-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Configuring_JCR_to_use_external_configuration-value_storages" /> + <area coords="27" id="area-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Configuring_JCR_to_use_external_configuration-conf_cache" /> + <area coords="31" id="area-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Configuring_JCR_to_use_external_configuration-conf_indexer" /> + <area coords="34" id="area-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Configuring_JCR_to_use_external_configuration-conf_lock_manager" /> + </areaspec> <programlisting language="XML" role="XML">&lt;repository-service default-repository="repository1"&gt; &lt;repositories&gt; &lt;repository name="repository1" system-workspace="ws1" default-workspace="ws1"&gt; @@ -123,7 +118,7 @@ &lt;property name="swap-directory" value="../temp/swap/production" /&gt; &lt;/properties&gt; &lt;value-storages&gt; - see "<xref linkend="list-Reference_Guide_eXo_JCR_1.14-list-Reference_Guide-conf_value_storage" />" part. + &lt;/value-storages&gt; &lt;/container&gt; &lt;initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"&gt; @@ -132,13 +127,13 @@ &lt;/properties&gt; &lt;/initializer&gt; &lt;cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"&gt; - see "<xref linkend="list-Reference_Guide_eXo_JCR_1.14-list-Reference_Guide-conf_cache" />" part. + &lt;/cache&gt; &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; - see "<xref linkend="list-Reference_Guide_eXo_JCR_1.14-list-Reference_Guide-conf_indexer" />" part. + &lt;/query-handler&gt; &lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; - see "<xref linkend="list-Reference_Guide_eXo_JCR_1.14-list-Reference_Guide-conf_lock_manager" />" part. + &lt;/lock-manager&gt; &lt;/workspace&gt; &lt;workspace name="ws2"&gt; @@ -151,13 +146,36 @@ &lt;/repository&gt; &lt;/repositories&gt; &lt;/repository-service&gt;</programlisting> - - </listitem> - <listitem> - <para> - Then, update RepositoryServiceConfiguration configuration in exo-configuration.xml to use this file: - </para> - + <calloutlist> + <!--#--> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Configuring_JCR_to_use_external_configuration-value_storages"> + <para> + Refer to <xref linkend="exam-Reference_Guide_eXo_JCR_1.14-Requirements-Configuration_requirements-conf_value_storage" />. + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Configuring_JCR_to_use_external_configuration-conf_cache"> + <para> + Refer to <xref linkend="exam-Reference_Guide_eXo_JCR_1.14-Requirements-Configuration_requirements-conf_cache" />. + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Configuring_JCR_to_use_external_configuration-conf_indexer"> + <para> + Refer to <xref linkend="exam-Reference_Guide_eXo_JCR_1.14-Requirements-Configuration_requirements-conf_indexer" />. + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Launching_Cluster-Configuring_JCR_to_use_external_configuration-conf_lock_manager"> + <para> + Refer to <xref linkend="exam-Reference_Guide_eXo_JCR_1.14-Requirements-Configuration_requirements-conf_lock_manager" />. + </para> + </callout> + </calloutlist> +</programlistingco> + </listitem> + <listitem> + <para> + Then, update <parameter>RepositoryServiceConfiguration</parameter> configuration in the <filename>exo-configuration.xml</filename> to reference your file: + </para> + <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; @@ -170,57 +188,54 @@ &lt;/init-params&gt; &lt;/component&gt;</programlisting> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - + </section> + - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Cluster_Config-Requirements"> - <title>Requirements</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Requirements-Environment_requirements"> - <title>Environment requirements</title> - <itemizedlist> - <listitem> - <para> - Every node of cluster MUST have the same mounted Network File System with the read and write permissions on it. - </para> - <para> - "/mnt/tornado" - path to the mounted Network File System (all cluster nodes must use the same NFS). - </para> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Cluster_Config-Requirements"> + <title>Requirements</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Requirements-Environment_requirements"> + <title>Environment requirements</title> + <itemizedlist> + <listitem> + <para> + Every node of the cluster <emphasis role="bold">must</emphasis> have the same mounted Network File System (<abbrev>NFS</abbrev>) with the read and write permissions on it. + </para> + </listitem> + <listitem> + <para> + Every node of cluster <emphasis role="bold">must</emphasis> use the same database. + </para> + </listitem> + <listitem> + <para> + The same Clusters on different nodes <emphasis role="bold">must</emphasis> have the same names. + </para> + <example id="exam-Reference_Guide_eXo_JCR_1.14-Requirements-Environment_requirements-Example"> + <title>Example</title> + <para> + If the <emphasis>Indexer</emphasis> cluster in the <emphasis>production</emphasis> workspace on the first node is named <literal>production_indexer_cluster</literal>, then <emphasis>indexer</emphasis> clusters in the <emphasis>production</emphasis> workspace on all other nodes <emphasis role="bold">must</emphasis> also be named <literal>production_indexer_cluster</literal>. + </para> + </example> - </listitem> - <listitem> - <para> - Every node of cluster MUST use the same database. - </para> + </listitem> - </listitem> - <listitem> - <para> - The same Clusters on different nodes MUST have the same names (e.g., if Indexer cluster in workspace production on the first node has the name "production_indexer_cluster", then indexer clusters in workspace production on all other nodes MUST have the same name "production_indexer_cluster" ). - </para> + </itemizedlist> - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Requirements-Configuration_requirements"> - <title>Configuration requirements</title> - <para> - Configuration of every workspace in repository must contains of such parts: - </para> - <itemizedlist> - <listitem id="list-Reference_Guide_eXo_JCR_1.14-list-Reference_Guide-conf_value_storage"> - <para> - Value Storage configuration: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Requirements-Configuration_requirements"> + <title>Configuration requirements</title> + <para> + The configuration of every workspace in the repository must contain the following elements: + </para> + <example id="exam-Reference_Guide_eXo_JCR_1.14-Requirements-Configuration_requirements-conf_value_storage"> + <title>Value Storage configuration</title> <programlisting language="XML" role="XML">&lt;value-storages&gt; &lt;value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; &lt;properties&gt; @@ -231,13 +246,10 @@ &lt;/filters&gt; &lt;/value-storage&gt; &lt;/value-storages&gt;</programlisting> - - </listitem> - <listitem id="list-Reference_Guide_eXo_JCR_1.14-list-Reference_Guide-conf_cache"> - <para> - Cache configuration: - </para> - + </example> + + <example id="exam-Reference_Guide_eXo_JCR_1.14-Requirements-Configuration_requirements-conf_cache"> + <title>Cache configuration</title> <programlisting language="XML" role="XML">&lt;cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"&gt; &lt;properties&gt; &lt;property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-data.xml" /&gt; &lt;!-- path to JBoss Cache configuration for data storage --&gt; @@ -246,13 +258,10 @@ &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; &lt;/properties&gt; &lt;/cache&gt;</programlisting> - - </listitem> - <listitem id="list-Reference_Guide_eXo_JCR_1.14-list-Reference_Guide-conf_indexer"> - <para> - Indexer configuration: - </para> - + </example> + + <example id="exam-Reference_Guide_eXo_JCR_1.14-Requirements-Configuration_requirements-conf_indexer"> + <title>Indexer configuration</title> <programlisting language="XML" role="XML">&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; &lt;properties&gt; &lt;property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /&gt; @@ -263,13 +272,10 @@ &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; &lt;/properties&gt; &lt;/query-handler&gt;</programlisting> - - </listitem> - <listitem id="list-Reference_Guide_eXo_JCR_1.14-list-Reference_Guide-conf_lock_manager"> - <para> - Lock Manager configuration: - </para> - + </example> + + <example id="exam-Reference_Guide_eXo_JCR_1.14-Requirements-Configuration_requirements-conf_lock_manager"> + <title>Lock Manager configuration</title> <programlisting language="XML" role="XML">&lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"&gt; &lt;properties&gt; &lt;property name="time-out" value="15m" /&gt; @@ -288,17 +294,14 @@ &lt;property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr"/&gt; &lt;/properties&gt; &lt;/lock-manager&gt;</programlisting> + </example> - </listitem> + </section> + - </itemizedlist> + </section> + - </section> - - - </section> - - </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-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/exo-jcr-configuration.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -1,268 +1,866 @@ <?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_eXo_JCR_1.14-JCR_configuration"> - <title>JCR configuration</title> - <para> - The JCR configuration is defined in an XML file which is constructed as per the DTD below: - </para> - -<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 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> -&lt;repository-service default-repository="repository"&gt; - &lt;repositories&gt; - &lt;repository name="repository" system-workspace="system" default-workspace="portal-system"&gt; - &lt;security-domain&gt;gatein-domain&lt;/security-domain&gt; - &lt;access-control&gt;optional&lt;/access-control&gt; - &lt;authentication-policy&gt;org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator&lt;/authentication-policy&gt; + <title>JCR configuration</title> - &lt;!-- System --&gt; - &lt;workspaces&gt; - [... Workspaces definitions ...] - &lt;/workspaces&gt; - &lt;/repository&gt; - &lt;/repositories&gt; -&lt;/repository-service&gt; -</programlisting> - <para> - In JBoss Enterprise Portal Platform you will see several configured workspaces required for the portal. - </para> - <orderedlist numeration="arabic"> - <listitem> - <para> - <literal>system</literal> - </para> + - </listitem> - <listitem> - <para> - <literal>portal-system</literal>: To store portal metadata such as page compositions. - </para> + <para> + The JCR configuration is defined in an XML file which is constructed as per the DTD below: + </para> - </listitem> - <listitem> - <para> - <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. - </para> + <section> + <title>Portal configuration</title> - </listitem> - <listitem> - <para> - <literal>wsrp-system</literal>: To store Portlet Container related data (such as portlet preferences). - </para> + - </listitem> + <para> + JCR services are registered in the Portal container. + </para> - </orderedlist> - <para> - Configure the workspaces by locating the workspace you need to modify in <filename><filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename></filename>. - </para> - <para> - The repository configuration supports human-readable values. They are not case-sensitive. - </para> - <para> - Complete the appropriate element fields using the following value formats: - </para> - <variablelist> - <varlistentry> - <term>Number formats:</term> - <listitem> - <para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">K</emphasis> or <emphasis role="bold">KB</emphasis> for kilobytes. - </para> + - </listitem> - <listitem> - <para> - <emphasis role="bold">M</emphasis> or <emphasis role="bold">MB</emphasis> for megabytes. - </para> + <para> + Below is an example configuration from the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration.xml</filename> file. + </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">G</emphasis> or <emphasis role="bold">GB</emphasis> for gigabytes. - </para> + - </listitem> - <listitem> - <para> - <emphasis role="bold">T</emphasis> or <emphasis role="bold">TB</emphasis> for terabytes. - </para> + <programlistingco> +<areaspec> + <area coords="10" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-conf-path" /><area coords="15" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-working-conf" /> + </areaspec> +<programlisting language="XML" role="XML">&lt;component&gt; + &lt;key&gt;org.exoplatform.services.jcr.RepositoryService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.jcr.impl.RepositoryServiceImpl&lt;/type&gt; +&lt;/component&gt; +&lt;component&gt; + &lt;key&gt;org.exoplatform.services.jcr.config.RepositoryServiceConfiguration&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;conf-path&lt;/name&gt; + &lt;description&gt;JCR repositories configuration file&lt;/description&gt; + &lt;value&gt;jar:/conf/standalone/exo-jcr-config.xml&lt;/value&gt; + &lt;/value-param&gt; + &lt;properties-param&gt; + &lt;name&gt;working-conf&lt;/name&gt; + &lt;description&gt;working-conf&lt;/description&gt; + &lt;property name="source-name" value="jdbcjcr" /&gt; + &lt;property name="dialect" value="hsqldb" /&gt; + &lt;property name="persister-class-name" value="org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister" /&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-conf-path"> + <para> + A path to a RepositoryService JCR Configuration. + </para> + </callout> + + + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-working-conf"> + <para> + JCR configuration persister configuration. If no <parameter>working-conf</parameter> is found, the persister will be disabled. + </para> + </callout> + </calloutlist> + </programlistingco> + + + + <section> + <title>JCR Configuration</title> + + + + <para> + The JCR Service can use multiple <emphasis>Repositories</emphasis> and each repository can have multiple <emphasis>Workspaces</emphasis>. + </para> + + + + <para> + Configure the workspaces by locating the workspace you need to modify in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + </para> + + + + <para> + The repository configuration supports human-readable values. They are not case-sensitive. + </para> + + + + <para> + Complete the appropriate element fields using the following value formats: + </para> + + + + <variablelist> + <varlistentry> + <term>Number formats:</term> + + <listitem> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">K</emphasis> or <emphasis role="bold">KB</emphasis> for kilobytes. + </para> </listitem> - <listitem> - <para> - Examples: 200K or 200KB; 4M or 4MB; 1.4G or 1.4GB; 10T or 10TB. - </para> + + + <listitem> + <para> + <emphasis role="bold">M</emphasis> or <emphasis role="bold">MB</emphasis> for megabytes. + </para> </listitem> - </itemizedlist> + - </para> + <listitem> + <para> + <emphasis role="bold">G</emphasis> or <emphasis role="bold">GB</emphasis> for gigabytes. + </para> + </listitem> - </listitem> + - </varlistentry> - <varlistentry> - <term>Time formats:</term> - <listitem> - <para> - <itemizedlist> <listitem> - <para> - <emphasis role="bold">ms</emphasis> for milliseconds. - </para> - + <para> + <emphasis role="bold">T</emphasis> or <emphasis role="bold">TB</emphasis> for terabytes. + </para> </listitem> - <listitem> - <para> - <emphasis role="bold">s</emphasis> for seconds. - </para> + + + <listitem> + <para> + Examples: 200K or 200KB; 4M or 4MB; 1.4G or 1.4GB; 10T or 10TB. + </para> </listitem> - <listitem> - <para> - <emphasis role="bold">m</emphasis> for minutes. - </para> + </itemizedlist> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Time formats:</term> + + <listitem> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">ms</emphasis> for milliseconds. + </para> + </listitem> + + + <listitem> + <para> + <emphasis role="bold">s</emphasis> for seconds. + </para> </listitem> - <listitem> - <para> - <emphasis role="bold">h</emphasis> for hours. - </para> + + + <listitem> + <para> + <emphasis role="bold">m</emphasis> for minutes. + </para> </listitem> - <listitem> - <para> - <emphasis role="bold">d</emphasis> for days. - </para> + + + <listitem> + <para> + <emphasis role="bold">h</emphasis> for hours. + </para> </listitem> - <listitem> - <para> - <emphasis role="bold">w</emphasis> for weeks. - </para> + + + <listitem> + <para> + <emphasis role="bold">d</emphasis> for days. + </para> </listitem> - <listitem> - <para> - The default time format is seconds if no other format is specified. - </para> + + + <listitem> + <para> + <emphasis role="bold">w</emphasis> for weeks. + </para> </listitem> - <listitem> - <para> - Examples: 500ms or 500 milliseconds; 20, 20s or 20 seconds; 30m or 30 minutes; 12h or 12 hours; 5d or 5 days; 4w or 4 weeks. - </para> + + + <listitem> + <para> + The default time format is seconds if no other format is specified. + </para> </listitem> - </itemizedlist> + - </para> + <listitem> + <para> + Examples: 500ms or 500 milliseconds; 20, 20s or 20 seconds; 30m or 30 minutes; 12h or 12 hours; 5d or 5 days; 4w or 4 weeks. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> - </listitem> + - </varlistentry> + <section id="JCR.eXoJCRconfiguration.RepositoryConfiguration"> + <title>Repository service configuration (JCR repositories configuration)</title> - </variablelist> - <section id="sect-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace"> - <title>Example of the portal-system workspace</title> <programlistingco> - <areaspec> - <!-- 1 --> <area coords="2 60" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-workspace-name" /> - <!-- 2 --> <area coords="3 90" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-container" /> - <!-- 3 --> <area coords="23 90" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_initializer" /> - <!-- 4 --> <area coords="29 60" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_cache" /> - <!-- 5 --> <area coords="37 100" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_query-handler" /> - <!-- 6 --> <area coords="50 60" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_lock-manager-timeout" /> +<areaspec> + <!--1--> + <area coords="1 60" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-default-repository" /> + <!--2--> + <area coords="2 60" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-repositories" /> + <!--3--> + <area coords="3 125" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-name" /> + <!--4--> + <area coords="3 125" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-default-workspace" /> + <!--5--> + <area coords="3 125" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-system-workspace" /> + <!--6--> + <area coords="4 60" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-security-domain" /> + <!--7--> + <area coords="5 60" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-access-control" /> + <!--8--> + <area coords="6 165" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-authentication-policy" /> + <!--9--> + <area coords="9 60" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-workspaces" /> + <!--10--> + <area coords="13 60" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-workspace-name" /> + <!--11--> + <area coords="14 165" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-container" /> + <!--12--> + <area coords="34 165" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_initializer" /> + <!--13--> + <area coords="40 165" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_cache" /> + <!--14--> + <area coords="48 165" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_query-handler" /> + <!--15--> + <area coords="61 60" id="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_lock-manager-timeout" /> + </areaspec> +<programlisting language="XML" role="XML"><xi:include href="../../../../../extras/Advanced_Development_JCR_Configuration/orig.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <calloutlist> +<!--1--> - </areaspec> +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-default-repository"> + <para> + <emphasis>default-repository</emphasis>: The name of a default repository (one returned by <parameter> RepositoryService.getRepository() </parameter> ). + </para> +</callout> + +<!--2--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-repositories"> + <para> + <emphasis>repositories</emphasis>: The list of repositories. + </para> +</callout> + +<!--3--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-name"> + <para> + <emphasis>name</emphasis>: The name of a repository. + </para> +</callout> + +<!--4--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-default-workspace"> + <para> + <emphasis>default-workspace</emphasis>: The name of a workspace obtained using Session's login() or login(Credentials) methods (ones without an explicit workspace name). + </para> +</callout> + +<!--5--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-system-workspace"> + <para> + <emphasis>system-workspace</emphasis>: The name of workspace where <emphasis>/jcr:system</emphasis> node is placed. + </para> +</callout> + +<!--6--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-security-domain"> + <para> + <emphasis>security-domain</emphasis>: The name of a security domain for JAAS authentication. + </para> +</callout> + +<!--7--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-access-control"> + <para> + <emphasis>access-control</emphasis>: The name of an access control policy. There can be 3 types: optional - ACL is created on-demand(default), disable - no access control, mandatory - an ACL is created for each added node(not supported yet). + </para> +</callout> + +<!--8--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-authentication-policy"> + <para> + <emphasis>authentication-policy</emphasis>: The name of an authentication policy class. + </para> +</callout> + +<!--9--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-workspaces"> + <para> + <emphasis>workspaces</emphasis>: The list of workspaces. + </para> +</callout> + +<!--10--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-workspace-name"> + <para> + The name of the workspace. + </para> +</callout> + +<!--11--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-container"> + <para> + Workspace data container (physical storage) configuration. + </para> +</callout> + +<!--12--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_initializer"> + <para> + Workspace initializer configuration. + </para> +</callout> + +<!--13--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_cache"> + <para> + Workspace storage cache configuration. + </para> +</callout> + +<!--14--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_query-handler"> + <para> + Query handler configuration. + </para> +</callout> + +<!--15--> + +<callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_lock-manager-timeout"> + <para> + The amount of time before the unused global lock is removed. + </para> +</callout> + </calloutlist> +</programlistingco> + + <note> + <title><parameter> session-max-age </parameter></title> -<programlisting language="XML" role="XML"><xi:include href="../../../../../extras/Advanced_Development_JCR_Configuration/orig.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-workspace-name"> - <para> - The name of the workspace. - </para> + <para> + <emphasis>session-max-age</emphasis>: This parameter is not shown in the examjple file above as it is not a required setting. It sets the time after which an idle session will be removed (called logout). If it is not set up, an idle session will never be removed. + </para> + </note> - </callout> - <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-container"> - <para> - Workspace data container (physical storage) configuration. - </para> + - </callout> - <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_initializer"> - <para> - Workspace initializer configuration. - </para> + <para id="JCR.eXoJCRconfiguration.LockRemoverMaxThreads"> + <emphasis role="bold">lock-remover-max-threads</emphasis>: Number of threads that can serve LockRemover tasks. Default value is 1. Repository may have many workspaces, each workspace have own LockManager. JCR supports Locks with defined lifetime. Such a lock must be removed is it become expired. That is what LockRemovers does. But LockRemovers is not an independent timer-threads, its a task that executed each 30 seconds. Such a task is served by ThreadPoolExecutor which may use different number of threads. + </para> + </section> - </callout> - <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_cache"> - <para> - Workspace storage cache configuration. - </para> + - </callout> - <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_query-handler"> - <para> - Query handler configuration. - </para> + <section> + <title>Workspace configuration:</title> - </callout> - <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace-service_lock-manager-timeout"> - <para> - The amount of time before the unused global lock is removed. - </para> + - </callout> + <para> + <emphasis>name</emphasis>: The name of a workspace + </para> - </calloutlist> + - </programlistingco> - + <para> + <emphasis>auto-init-root-nodetype</emphasis>: DEPRECATED in JCR 1.9 (use initializer). The node type for root node initialization. + </para> - </section> - - <!-- - <section id="sect-Reference_Guide-JCR_configuration-Related_documents"> - <title>Related Sections</title> - <itemizedlist> + + + <para> + <emphasis>container</emphasis>: Workspace data container (physical storage) configuration. + </para> + + + + <para> + <emphasis>initializer</emphasis>: Workspace initializer configuration. + </para> + + + + <para> + <emphasis>cache</emphasis>: Workspace storage cache configuration. + </para> + + + + <para> + <emphasis>query-handler</emphasis>: Query handler configuration. + </para> + + + + <para> + <emphasis>auto-init-permissions</emphasis>: DEPRECATED in JCR 1.9 (use initializer). Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities (user, group, etc, see Organization service documentation for details) and the type of permission. For example, any read; <emphasis>:/admin read;</emphasis>:/admin add_node; <emphasis>:/admin set_property;</emphasis>:/admin remove means that users from group <emphasis>admin</emphasis> have all permissions and other users have only a 'read' permission. + </para> + </section> + + + + <section> + <title>Workspace data container configuration:</title> + + + + <para> + <emphasis>class:</emphasis> A workspace data container class name. + </para> + + + + <para> + <emphasis>properties</emphasis>: The list of properties (name-value pairs) for the concrete Workspace data container. + </para> + + + + <table> + <title>Parameter Descriptions</title> + + <tgroup cols="2"> + <thead> + <row> + <entry> + Parameter + </entry> + + + + <entry> + Description + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + trigger_events_for_descendents_on_rename + </entry> + + + + <entry> + indicates if need to trigger events for descendents on rename or not. It allows to increase performance on rename operation but in same time Observation'll not notified, has default value true + </entry> + </row> + + <row> + <entry> + lazy-node-iterator-page-size + </entry> + + + + <entry> + the page size for lazy iterator. Indicates how many nodes can be retrieved from storage per request. The default value is 100 + </entry> + </row> + + <row> + <entry> + acl-bloomfilter-false-positive-probability + </entry> + + + + <entry> + ACL Bloom-filter desired false positive probability. Range [0..1]. Default value 0.1d. (See the note below) + </entry> + </row> + + <row> + <entry> + acl-bloomfilter-elements-number + </entry> + + + + <entry> + Expected number of ACL-elements in the Bloom-filter. Default value 1000000. (See the note below) + </entry> + </row> + </tbody> + </tgroup> + </table> + + + + <note> + <para> + Bloom filters are not supported by all the cache implementations so far only the implementation for infinispan supports it. + </para> + </note> + + + + <para> + <emphasis>value-storages</emphasis>: The list of value storage plugins. + </para> + </section> + + + + <section id="JCR.ConfigurationPersister.ValueStoragePlugin"> + <title>Value Storage plugin configuration (for data container):</title> + + + + <note> + <para> + The value-storage element is optional. If you don't include it, the values will be stored as BLOBs inside the database. + </para> + </note> + + + + <para> + <emphasis>value-storage</emphasis>: Optional value Storage plugin definition. + </para> + + + + <para> + <emphasis>class</emphasis>: A value storage plugin class name (attribute). + </para> + + + + <para> + <emphasis>properties</emphasis>: The list of properties (name-value pairs) for a concrete Value Storage plugin. + </para> + + + + <para> + <emphasis>filters</emphasis>: The list of filters defining conditions when this plugin is applicable. + </para> + </section> + + + + <section> + <title>Initializer configuration (optional):</title> + + + + <para> + <emphasis>class</emphasis>: Initializer implementation class. + </para> + + + + <para> + <emphasis>properties</emphasis>: The list of properties (name-value pairs). Properties are supported. + </para> + + + + <para> + <emphasis>root-nodetype</emphasis>: The node type for root node initialization. + </para> + + + + <para> + <emphasis>root-permissions</emphasis>: Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities (user, group etc, see Organization service documentation for details) and the type of permission. For example any read; <emphasis + role="bold">:/admin read;</emphasis>:/admin add_node; <emphasis + role="bold">:/admin set_property;</emphasis>:/admin remove means that users from group <emphasis>admin</emphasis> have all permissions and other users have only a 'read' permission. + </para> + + + + <para> + Configurable initializer adds a capability to override workspace initial startup procedure (used for Clustering). Also it replaces workspace element parameters auto-init-root-nodetype and auto-init-permissions with root-nodetype and root-permissions. + </para> + </section> + + + + <section> + <title>Cache configuration:</title> + + + + <para> + <emphasis>enabled</emphasis>: If workspace cache is enabled or not. + </para> + + + + <para> + <emphasis>class</emphasis>: Cache implementation class, optional from 1.9. Default value is. org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl. + </para> + + + + <para> + Cache can be configured to use concrete implementation of WorkspaceStorageCache interface. JCR core has two implementation to use: + </para> + + + + <itemizedlist> <listitem> - <para> - <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration"/> - </para> + <para> + LinkedWorkspaceStorageCacheImpl - default, with configurable read behavior and statistic. + </para> </listitem> + + + <listitem> - <para> - <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-JDBC_Data_Container_Config"/> - </para> + <para> + WorkspaceStorageCacheImpl - pre 1.9, still can be used. + </para> </listitem> + </itemizedlist> + + + + <para> + <emphasis>properties</emphasis>: The list of properties (name-value pairs) for Workspace cache. + </para> + + + + <para> + <emphasis>max-size</emphasis>: Cache maximum size (maxSize prior to v.1.9). + </para> + + + + <para> + <emphasis>live-time</emphasis>: Cached item live time (liveTime prior to v.1.9). + </para> + + + + <para> + From 1.9 LinkedWorkspaceStorageCacheImpl supports additional optional parameters. + </para> + + + + <para> + <emphasis>statistic-period</emphasis>: Period (time format) of cache statistic thread execution, 5 minutes by default. + </para> + + + + <para> + <emphasis>statistic-log</emphasis>: If true cache statistic will be printed to default logger (log.info), false by default or not. + </para> + + + + <para> + <emphasis>statistic-clean</emphasis>: If true cache statistic will be cleaned after was gathered, false by default or not. + </para> + + + + <para> + <emphasis>cleaner-period</emphasis>: Period of the eldest items remover execution, 20 minutes by default. + </para> + + + + <para> + <emphasis>blocking-users-count</emphasis>: Number of concurrent users allowed to read cache storage, 0 - unlimited by default. + </para> + </section> + + + + <section> + <title>Query Handler configuration:</title> + + + + <para> + <emphasis>class</emphasis>: A Query Handler class name. + </para> + + + + <para> + <emphasis>properties</emphasis>: The list of properties (name-value pairs) for a Query Handler (indexDir). + </para> + + + + <para> + Properties and advanced features described in Search Configuration. + </para> + </section> + + + + <section> + <title>Lock Manager configuration:</title> + + + + <para> + <emphasis>time-out</emphasis>: Time after which the unused global lock will be removed. + </para> + + + + <para> + <emphasis>persister</emphasis>: A class for storing lock information for future use. For example, remove lock after jcr restart. + </para> + + + + <para> + <emphasis>path</emphasis>: A lock folder. Each workspace has its own one. + </para> + + + + <note> + <para> + Also see <link linkend="JCR.eXoJCRconfiguration.LockRemoverMaxThreads"><emphasis role="bold">lock-remover-max-threads</emphasis></link> repository configuration parameter. + </para> + </note> + +<programlisting language="XML" role="XML">&lt;!ELEMENT repository-service (repositories)&gt; +&lt;!ATTLIST repository-service default-repository NMTOKEN #REQUIRED&gt; +&lt;!ELEMENT repositories (repository)&gt; +&lt;!ELEMENT repository (security-domain,access-control,session-max-age,authentication-policy,workspaces)&gt; +&lt;!ATTLIST repository + default-workspace NMTOKEN #REQUIRED + name NMTOKEN #REQUIRED + system-workspace NMTOKEN #REQUIRED +&gt; +&lt;!ELEMENT security-domain (#PCDATA)&gt; +&lt;!ELEMENT access-control (#PCDATA)&gt; +&lt;!ELEMENT session-max-age (#PCDATA)&gt; +&lt;!ELEMENT authentication-policy (#PCDATA)&gt; +&lt;!ELEMENT workspaces (workspace+)&gt; +&lt;!ELEMENT workspace (container,initializer,cache,query-handler)&gt; +&lt;!ATTLIST workspace name NMTOKEN #REQUIRED&gt; +&lt;!ELEMENT container (properties,value-storages)&gt; +&lt;!ATTLIST container class NMTOKEN #REQUIRED&gt; +&lt;!ELEMENT value-storages (value-storage+)&gt; +&lt;!ELEMENT value-storage (properties,filters)&gt; +&lt;!ATTLIST value-storage class NMTOKEN #REQUIRED&gt; +&lt;!ELEMENT filters (filter+)&gt; +&lt;!ELEMENT filter EMPTY&gt; +&lt;!ATTLIST filter property-type NMTOKEN #REQUIRED&gt; +&lt;!ELEMENT initializer (properties)&gt; +&lt;!ATTLIST initializer class NMTOKEN #REQUIRED&gt; +&lt;!ELEMENT cache (properties)&gt; +&lt;!ATTLIST cache + enabled NMTOKEN #REQUIRED + class NMTOKEN #REQUIRED +&gt; +&lt;!ELEMENT query-handler (properties)&gt; +&lt;!ATTLIST query-handler class NMTOKEN #REQUIRED&gt; +&lt;!ELEMENT access-manager (properties)&gt; +&lt;!ATTLIST access-manager class NMTOKEN #REQUIRED&gt; +&lt;!ELEMENT lock-manager (time-out,persister)&gt; +&lt;!ELEMENT time-out (#PCDATA)&gt; +&lt;!ELEMENT persister (properties)&gt; +&lt;!ELEMENT properties (property+)&gt; +&lt;!ELEMENT property EMPTY&gt;</programlisting> + </section> + + + + <section> + <title>Help application to prohibit the use of closed sessions</title> + + + + <para> + Products that use eXo JCR, sometimes missuse it since they continue to use a session that has been closed through a method call on a node, a property or even the session itself. To prevent bad practices we propose three modes which are the folllowing: + </para> + + + + <orderedlist> <listitem> - <para> - <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-External_Value_Storages"/> - </para> + <para> + If the system property <emphasis>exo.jcr.prohibit.closed.session.usage</emphasis> has been set to <emphasis>true</emphasis>, then a RepositoryException will be thrown any time an application will try to access to a closed session. In the stack trace, you will be able to know the call stack that closes the session. + </para> </listitem> - </itemizedlist> - </section> - --> + + <listitem> + <para> + If the system property <emphasis>exo.jcr.prohibit.closed.session.usage</emphasis> has not been set and the system property <emphasis>exo.product.developing</emphasis> has been set to <emphasis>true</emphasis>, then a warning will be logged in the log file with the full stack trace in order to help identifying the root cause of the issue. In the stack trace, you will be able to know the call stack that closes the session. + </para> + </listitem> + + <listitem> + <para> + If none of the previous system properties have been set, then we will ignore that the issue and let the application use the closed session as it was possible before without doing anything in order to allow applications to migrate step by step. + </para> + </listitem> + </orderedlist> + </section> + </section> </section> - 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-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/external-value-storages.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -10,9 +10,9 @@ <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> + <!--<para> Value storage configuration is a part of the repository configuration. Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-JCR_configuration-Example_of_the_portal_system_workspace" /> for more details. - </para> + </para>--> <para> Tree-based storage is recommended in most cases. </para> 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-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/jdbc-data-container-config.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -7,6 +7,21 @@ <title>JDBC Data Container Config</title> <section id="sect-Reference_Guide_eXo_JCR_1.14-JDBC_Data_Container_Config-Introduction"> <title><remark>Introduction</remark></title> + <para>eXo JCR persistent data container can work in two configuration + modes: + </para> + <itemizedlist> + <listitem> + <para><phrase>Multi-database</phrase>: One database for each + workspace (used in standalone eXo JCR service mode)</para> + </listitem> + + <listitem> + <para><phrase>Single-database</phrase>: All workspaces persisted in + one database (used in embedded eXo JCR service mode, e.g. in eXo + portal)</para> + </listitem> + </itemizedlist> <para> The data container uses the JDBC driver to communicate with the actual database software, i.e. any JDBC-enabled data storage can be used with eXo JCR implementation. </para> @@ -126,8 +141,23 @@ <para> 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> + <note> + <para>One more mandatory JCR requirement for underlying databases is a + case sensitive collation. Microsoft SQL Server both 2005 and 2008 + customers must configure their server with collation corresponding to + personal needs and requirements, but obligatorily case sensitive. For + more information please refer to Microsoft SQL Server documentation + page "Selecting a SQL Server Collation" <ulink + url="http://msdn.microsoft.com/en-us/library/ms144250.aspx">... + </para> + </note> + <note> + <para> + Be aware that JCR does not support MyISAM storage engine for the MySQL + relational database management system. + </para> + </note> <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> @@ -328,6 +358,10 @@ <para> 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> + <para>There are preconfigured configuration files for HSQLDB. Look for + these files in /conf/portal and /conf/standalone folders of the jar-file + <package>exo.jcr.component.core-XXX.XXX.jar</package> or + source-distribution of eXo JCR implementation.</para> <example id="exam-Reference_Guide_eXo_JCR_1.14-Introduction-Example_Parameter"> <title>Example Parameter</title> @@ -583,7 +617,7 @@ <section id="sect-Reference_Guide_eXo_JCR_1.14-JDBC_Data_Container_Config-Simple_and_Complex_queries"> <title>Simple and Complex queries</title> <para> - eXo JCR provides two ways for interact with the database; + eXo JCR provides two ways to interact with the database; </para> <variablelist> <title></title> 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-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/configuration/rest-services-on-groovy.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -5,6 +5,13 @@ ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-REST_Services_on_Groovy"> <title>REST Services on Groovy</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 <link linkend="WS.RestFramework">RESTful + framework</link> and uses ResourceContainer concept.</para> <para> Groovy scripts should extend <literal>ResourceContainer</literal> and should be stored in the JCR as an <literal>exo:groovyResourceContainer</literal> node type. </para> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/jbosscache-configuration-templates.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/jbosscache-configuration-templates.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/jbosscache-configuration-templates.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,77 +4,94 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration"> - <title>JBoss Cache configuration</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration-JBoss_cache_configuration_for_indexer_lock_manager_and_data_container"> - <title>JBoss cache configuration for indexer, lock manager and data container</title> - <para> - Each mentioned components uses instances of JBoss Cache product for caching in clustered environment. So every element has it's own transport and has to be configured in a proper way. As usual, workspaces have similar configuration but with different cluster-names and may-be some other parameters. The simplest way to configure them is to define their own configuration files for each component in each workspace: - </para> - + <title>JBoss Cache configuration</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration-JBoss_cache_configuration_for_indexer_lock_manager_and_data_container"> + <title>Indexer, lock manager and data container configuration</title> + <para> + Each mentioned component uses instances of the JBoss Cache product for caching in clustered environment. So every element has its own transport and has to be configured correctly. As usual, workspaces have similar configuration differing only in cluster-names (and, possibly, some other parameters). The simplest way to configure them is to define their own configuration files for each component in each workspace: + </para> + <programlisting language="XML" role="XML">&lt;property name="jbosscache-configuration" value="conf/<remark>standalone</remark> - /test-jbosscache-lock-db1-ws1.xml" /&gt;</programlisting> - <para> - But if there are few workspaces, configuring them in such a way can be painful and hard-manageable. eXo JCR offers a template-based configuration for JBoss Cache instances. You can have one template for Lock Manager, one for Indexer and one for data container and use them in all the workspaces, defining the map of substitution parameters in a main configuration file. Just simply define ${jbosscache-&lt;parameter name&gt;} inside xml-template and list correct value in JCR configuration file just below "jbosscache-configuration", as shown: - </para> - <para> - Template: - </para> - + /test-jbosscache-lock-db1-ws1.xml" /&gt;</programlisting> + <para> + But if there are few workspaces, configuring them in such a way can be painful and hard-manageable. eXo JCR offers a template-based configuration for JBoss Cache instances. You can have one template for Lock Manager, one for Indexer and one for data container and use them in all the workspaces, defining the map of substitution parameters in a main configuration file. Just simply define ${jbosscache-&lt;parameter name&gt;} inside xml-template and list correct value in JCR configuration file just below "jbosscache-configuration", as shown: + </para> + <para> + Template: + </para> + <programlisting language="XML" role="XML">... &lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; ...</programlisting> - <para> - and JCR configuration file: - </para> - + <para> + and JCR configuration file: + </para> + <programlisting language="XML" role="XML">... &lt;property name="jbosscache-configuration" value="jar:/conf/portal/jbosscache-lock.xml" /&gt; &lt;property name="jbosscache-cluster-name" value="JCR-cluster-locks-db1-ws" /&gt; ...</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration-JGroups_configuration"> - <title>JGroups configuration</title> - <para> - JGroups is used by JBoss Cache for network communications and transport in a clustered environment. If property "jgroups-configuration" is defined in component configuration, it will be injected into the JBoss Cache instance on startup. - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration-JGroups_configuration"> + <title>JGroups configuration</title> + <para> + JGroups is used by JBoss Cache for network communications and transport in a clustered environment. If the property is defined in component configuration, it will be injected into the JBoss Cache instance on start up. + </para> + <programlisting language="XML" role="XML">&lt;property name="jgroups-configuration" value="your/path/to/modified-udp.xml" /&gt;</programlisting> - <para> - As mentioned above, each component (lock manager, data container and query handler) for each workspace requires its own clustered environment. In other words, they have their own clusters with unique names. By default, each cluster should perform multi-casts on a separate port. This configuration leads to much unnecessary overhead on cluster. That's why JGroups offers multiplexer feature, providing ability to use one single channel for set of clusters. This feature reduces network overheads and increase performance and stability of application. To enable multiplexer stack, you should define appropriate configuration file (upd-mux.xml is pre-shipped one with eXo JCR) and set "jgroups-multiplexer-stack" into "true". - </para> - + <para> + As outlined above, each component (lock manager, data container and query handler) for each workspace requires its own clustered environment. In other words, they have their own clusters with unique names. + </para> + <para> + Each cluster should, by default, perform multi-casts on a separate port. This configuration leads to much unnecessary overhead on cluster. This is why JGroups offers a multiplexer feature, providing ability to use one single channel for set of clusters. + </para> + <para> + The multiplexer reduces network overheads and increase performance and stability of application. To enable multiplexer stack, you should define appropriate configuration file (<filename>upd-mux.xml</filename> is pre-shipped one with eXo JCR) and set "jgroups-multiplexer-stack" into "true". + </para> + <programlisting language="XML" role="XML">&lt;property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /&gt; &lt;property name="jgroups-multiplexer-stack" value="true" /&gt;</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration-Allow_to_share_JBoss_Cache_instances"> - <title>Allow to share JBoss Cache instances</title> - <para> - A JBoss Cache instance is quite resource consuming and by default we will have 3 JBoss Cache instances (one instance for the indexer, one for the lock manager and one for the data container) for each workspace, so if you intend to have a lot of workspaces it could make sense to decide to share one JBoss Cache instance with several cache instances of the same type (i.e. indexer, lock manager or data container). This feature is disabled by default and can be enabled at component configuration level (i.e. indexer configuration, lock manager configuration and/or data container configuration) by setting the property "jbosscache-shareable" to true as below: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration-Allow_to_share_JBoss_Cache_instances"> + <title>Sharing JBoss Cache instances</title> + <para> + As a single JBoss Cache instance can be demanding on resources, and the default setup will have an instance each for the indexer, the lock manager and the data container on each workspace, an environment that uses multiple workspace may benefit from sharing a JBoss Cache instance between several instances of the same type (the lock manager instance, for example). + </para> + <para> + This feature is disabled by default and can be enabled at the component configuration level by setting the <parameter>jbosscache-shareable</parameter> property to <literal>true</literal>: + </para> <programlisting language="XML" role="XML">&lt;property name="jbosscache-shareable" value="true" /&gt;</programlisting> - <para> - Once enabled this feature will allow the JBoss Cache instance used by the component to be re-used by another components of the same type (i.e. indexer, lock manager or data container) with the exact same JBoss Cache configuration (except the eviction configuration that cans be different), which means that all the parameters of type ${jbosscache-&lt;parameter name&gt;} must be identical between the components of same type of different workspaces. In other words, if we use the same values for the parameters of type ${jbosscache-&lt;parameter name&gt;} in each workspace, we will have only 3 JBoss Cache instances (one instance for the indexer, one for the lock manager and one for the data container) used whatever the total amount of workspaces defined. - </para> + <para> + Once enabled, this feature will allow the JBoss Cache instance used by a component to be re-used by another components of the same type with the same JBoss Cache configuration (with the exception of the eviction configuration, which can differ). + </para> + <para> + This means that all the parameters of type <parameter>jbosscache-<replaceable>&lt;PARAM_NAME&gt;</replaceable></parameter> must be identical between the components of same type of different workspaces. + </para> + <para> + Therefore, if you can use the same values for the parameters in each workspace, you only need three JBoss Cache instances (one instance each for the indexer, lock manager and data container) running at once. This can relieve resource stress significantly. + </para> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration-Shipped_JBoss_Cache_configuration_templates"> - <title>Shipped JBoss Cache configuration templates</title> - <para> - eXo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR's components. They are situated in application package in /conf/portal/ folder. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Data_container_template"> - <title>Data container template</title> - <para> - Data container template is "jbosscache-data.xml": - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration-Shipped_JBoss_Cache_configuration_templates"> + <title>Shipped JBoss Cache configuration templates</title> + <para> + The eXo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR's components. They are located in an application package in the <filename>/conf/portal/</filename> directory. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Data_container_template"> + <title>Data container template</title> + <para> + The data container template is <filename>jbosscache-data.xml</filename>: + </para> +<programlistingco> + <areaspec> + <area coords="7" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Data_container_template-jbosscache-cluster-name" /> + </areaspec> <programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; &lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; @@ -97,43 +114,38 @@ &lt;/default&gt; &lt;/eviction&gt; &lt;/jbosscache&gt;</programlisting> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Data_container_template-Template_variables"> - <title>Template variables</title> - <tgroup cols="1"> - <thead> - <row> - <entry align="center"> - Variable - </entry> + <calloutlist> + <title>Template variables</title> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Data_container_template-jbosscache-cluster-name"> + <para> + <replaceable>jbosscache-cluster-name</replaceable>. + </para> + </callout> + </calloutlist> +</programlistingco> - </row> - - </thead> - <tbody> - <row> - <entry> - jbosscache-cluster-name - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <para> - - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template"> - <title>Lock manager template</title> - <para> - It's template name is "jbosscache-lock.xml" - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template"> + <title>Lock manager template</title> + <para> + The lock manager template is <filename>jbosscache-lock.xml</filename>: + </para> + +<programlistingco> + <areaspec> + <area coords="6" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cluster-name" /> + <area coords="18" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.table.name" /> + <area coords="19" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.table.create" /> + <area coords="20" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.table.drop" /> + <area coords="21" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.table.primarykey" /> + <area coords="22" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.fqn.column" /> + <area coords="23" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.fqn.type" /> + <area coords="24" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.node.column" /> + <area coords="25" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.node.type" /> + <area coords="26" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.parent.column" /> + <area coords="27" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.datasource" /> + </areaspec> <programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; &lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; @@ -165,100 +177,76 @@ &lt;/loader&gt; &lt;/loaders&gt; &lt;/jbosscache&gt;</programlisting> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Lock_manager_template-Template_variables"> - <title>Template variables</title> - <tgroup cols="1"> - <thead> - <row> - <entry align="center"> - Variable - </entry> - - </row> - - </thead> - <tbody> - <row> - <entry> - jbosscache-cluster-name - </entry> - - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.table.name - </entry> - - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.table.create - </entry> - - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.table.drop - </entry> - - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.table.primarykey - </entry> - - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.fqn.column - </entry> - - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.fqn.type - </entry> - - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.node.column - </entry> - - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.node.type - </entry> - - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.parent.column - </entry> - - </row> - <row> - <entry> - jbosscache-cl-cache.jdbc.datasource - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Query_handler_indexer_template"> - <title>Query handler (indexer) template</title> - <para> - Have a look at "jbosscache-indexer.xml" - </para> - + <calloutlist> + <title>Template variables</title> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cluster-name"> + <para> + <replaceable>jbosscache-cluster-name</replaceable> + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.table.name"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.table.name</replaceable> + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.table.create"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.table.create</replaceable> + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.table.drop"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.table.drop</replaceable> + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.table.primarykey"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.table.primarykey</replaceable> + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.fqn.column"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.fqn.column</replaceable> + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.fqn.type"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.fqn.type</replaceable> + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.node.column"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.node.column</replaceable> + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.node.type"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.node.type</replaceable> + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.parent.column"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.parent.column</replaceable> + </para> + </callout> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template-jbosscache-cl-cache.jdbc.datasource"> + <para> + <replaceable>jbosscache-cl-cache.jdbc.datasource</replaceable> + </para> + </callout> + </calloutlist> +</programlistingco> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Query_handler_indexer_template"> + <title>Query handler (indexer) template</title> + <para> + The query handler template is called <filename>jbosscache-indexer.xml</filename>: + </para> +<programlistingco> + <areaspec> + <area coords="5" id="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Query_handler_indexer_template-jbosscache-cluster-name" /> + </areaspec> <programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; &lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" @@ -276,38 +264,20 @@ &lt;/default&gt; &lt;/eviction&gt; &lt;/jbosscache&gt;</programlisting> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Query_handler_indexer_template-Template_variables"> - <title>Template variables</title> - <tgroup cols="1"> - <thead> - <row> - <entry align="center"> - Variable - </entry> + <calloutlist> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Shipped_JBoss_Cache_configuration_templates-Query_handler_indexer_template-jbosscache-cluster-name"> + <para> + <replaceable>jbosscache-cluster-name</replaceable> + </para> + </callout> + </calloutlist> +</programlistingco> + </section> + - </row> + </section> + - </thead> - <tbody> - <row> - <entry> - jbosscache-cluster-name - </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/jta.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/jta.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/jta.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,10 +4,17 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-JTA"> - <!-- This document was created with Syntext Serna Free. --> <title>JTA</title> - <para> - eXo JCR supports the Java Transaction API out of the box. If a <emphasis>TransactionService</emphasis> has been defined (refer to the section about the TransactionService for more details) at session save, it checks if a global transaction is active and if so, it automatically enrols the JCR session in the global transaction. If you intend to use a managed data source, you will have to configure the service <emphasis>DataSourceProvider</emphasis> (for more details please refer to the corresponding section). - </para> + <!-- This document was created with Syntext Serna Free. --> + <title>Java Transaction API</title> + <para> + eXo JCR supports the Java Transaction API (<abbrev>JTA</abbrev>) by default. + </para> + <para> + If a <literal>TransactionService</literal> has been defined at session save, it checks if a global transaction is active and if so, it automatically enrols the JCR session in the global transaction. + </para> + <para> + If you intend to use a managed data source, you will have to configure the service <literal>DataSourceProvider</literal> (for more details please refer to the corresponding section). + </para> </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/query-handler-config.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/query-handler-config.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/query-handler-config.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,50 +4,50 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-QueryHandler_configuration"> - <title>QueryHandler configuration</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-QueryHandler_configuration-Indexing_in_clustered_environment"> - <title>Indexing in clustered environment</title> - <para> - JCR offers indexing strategies for clustered environments using the advantages of running in a single JVM or doing the best to use all resources available in cluster. JCR uses Lucene library as underlying search and indexing engine, but it has several limitations that greatly reduce possibilities and limits the usage of cluster advantages. That's why eXo JCR offers two strategies that are suitable for it's own usecases. They are clustered with shared index and clustered with local indexes. Each one has it's pros and cons. - </para> - <para> - Clustered implementation with local indexes combines in-memory buffer index directory with delayed file-system flushing. This index is called "Volatile" and it is invoked in searches also. Within some conditions volatile index is flushed to the persistent storage (file system) as new index directory. This allows to achieve great results for write operations. - </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/eXoJCR/diagram-local-index.png" width="444" /> - </imageobject> + <title>QueryHandler configuration</title> + <!-- <section id="sect-Reference_Guide_eXo_JCR_1.14-QueryHandler_configuration-Indexing_in_clustered_environment"> + <title>Indexing in clustered environment</title> + <para> + JCR offers indexing strategies for clustered environments using the advantages of running in a single JVM or doing the best to use all resources available in cluster. JCR uses Lucene library as underlying search and indexing engine, but it has several limitations that greatly reduce possibilities and limits the usage of cluster advantages. That's why eXo JCR offers two strategies that are suitable for it's own usecases. They are clustered with shared index and clustered with local indexes. Each one has it's pros and cons. + </para> + <para> + Clustered implementation with local indexes combines in-memory buffer index directory with delayed file-system flushing. This index is called "Volatile" and it is invoked in searches also. Within some conditions volatile index is flushed to the persistent storage (file system) as new index directory. This allows to achieve great results for write operations. + </para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/eXoJCR/diagram-local-index.png" width="444" /> + </imageobject> - </mediaobject> - <para> - As this implementation designed for clustered environment it has additional mechanisms for data delivery within cluster. Actual text extraction jobs done on the same node that does content operations (i.e. write operation). Prepared "documents" (Lucene term that means block of data ready for indexing) are replicated withing cluster nodes and processed by local indexes. So each cluster instance has the same index content. When new node joins the cluster it has no initial index, so it must be created. There are some supported ways of doing this operation. The simplest is to simply copy the index manually but this is not intended for use. If no initial index found JCR uses automated sceneries. They are controlled via configuration (see "index-recovery-mode" parameter) offering full re-indexing from database or copying from another cluster node. - </para> - <para> - For some reasons having a multiple index copies on each instance can be costly. So shared index can be used instead (see diagram below). - </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/eXoJCR/diagram-shared-index.png" width="444" /> - </imageobject> + </mediaobject> + <para> + As this implementation designed for clustered environment it has additional mechanisms for data delivery within cluster. Actual text extraction jobs done on the same node that does content operations (i.e. write operation). Prepared "documents" (Lucene term that means block of data ready for indexing) are replicated withing cluster nodes and processed by local indexes. So each cluster instance has the same index content. When new node joins the cluster it has no initial index, so it must be created. There are some supported ways of doing this operation. The simplest is to simply copy the index manually but this is not intended for use. If no initial index found JCR uses automated sceneries. They are controlled via configuration (see "index-recovery-mode" parameter) offering full re-indexing from database or copying from another cluster node. + </para> + <para> + For some reasons having a multiple index copies on each instance can be costly. So shared index can be used instead (see diagram below). + </para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/eXoJCR/diagram-shared-index.png" width="444" /> + </imageobject> - </mediaobject> - <para> - This indexing strategy combines advantages of in-memory index along with shared persistent index offering "near" real time search capabilities. This means that newly added content is accessible via search practically immediately. This strategy allows nodes to index data in their own volatile (in-memory) indexes, but persistent indexes are managed by single "coordinator" node only. Each cluster instance has a read access for shared index to perform queries combining search results found in own in-memory index also. Take in account that shared folder must be configured in your system environment (i.e. mounted NFS folder). But this strategy in some extremely rare cases can have a bit different volatile indexes within cluster instances for a while. In a few seconds they will be up2date. - </para> - <para> - See more about <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration" />. - </para> + </mediaobject> + <para> + This indexing strategy combines advantages of in-memory index along with shared persistent index offering "near" real time search capabilities. This means that newly added content is accessible via search practically immediately. This strategy allows nodes to index data in their own volatile (in-memory) indexes, but persistent indexes are managed by single "coordinator" node only. Each cluster instance has a read access for shared index to perform queries combining search results found in own in-memory index also. Take in account that shared folder must be configured in your system environment (i.e. mounted NFS folder). But this strategy in some extremely rare cases can have a bit different volatile indexes within cluster instances for a while. In a few seconds they will be up2date. + </para> + <para> + See more about <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration" />. + </para> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-QueryHandler_configuration-Configuration"> - <title>Configuration</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuration-Query_handler_configuration_overview"> - <title>Query-handler configuration overview</title> - <para> - Configuration example: - </para> - + </section> --> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-QueryHandler_configuration-Configuration"> + <title>Configuration</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuration-Query_handler_configuration_overview"> + <title>Query-handler configuration overview</title> + <para> + Configuration example: + </para> + <programlisting language="XML" role="XML">&lt;workspace name="ws"&gt; &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; &lt;properties&gt; @@ -66,127 +66,127 @@ &lt;/query-handler&gt; &lt;/workspace&gt; </programlisting> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Query_handler_configuration_overview-Config_properties_description"> - <title>Config properties description</title> - <tgroup cols="2"> - <thead> - <row> - <entry> - Property name - </entry> - <entry> - Description - </entry> + <table id="tabl-Reference_Guide_eXo_JCR_1.14-Query_handler_configuration_overview-Config_properties_description"> + <title>Configuration properties</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + Property name + </entry> + <entry> + Description + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - index-dir - </entry> - <entry> - path to index - </entry> + </thead> + <tbody> + <row> + <entry> + index-dir + </entry> + <entry> + path to index + </entry> - </row> - <row> - <entry> - changesfilter-class - </entry> - <entry> - template of JBoss-cache configuration for all query-handlers in repository - </entry> + </row> + <row> + <entry> + changesfilter-class + </entry> + <entry> + template of JBoss-cache configuration for all query-handlers in repository + </entry> - </row> - <row> - <entry> - jbosscache-configuration - </entry> - <entry> - template of JBoss-cache configuration for all query-handlers in repository - </entry> + </row> + <row> + <entry> + jbosscache-configuration + </entry> + <entry> + template of JBoss-cache configuration for all query-handlers in repository + </entry> - </row> - <row> - <entry> - jgroups-configuration - </entry> - <entry> - jgroups-configuration is template configuration for all components (search, cache, locks) [Add link to document describing template configurations] - </entry> + </row> + <row> + <entry> + jgroups-configuration + </entry> + <entry> + jgroups-configuration is template configuration for all components (search, cache, locks) [Add link to document describing template configurations] + </entry> - </row> - <row> - <entry> - jgroups-multiplexer-stack - </entry> - <entry> - [TODO about jgroups-multiplexer-stack - add link to JBoss doc] - </entry> + </row> + <row> + <entry> + jgroups-multiplexer-stack + </entry> + <entry> + [TODO about jgroups-multiplexer-stack - add link to JBoss doc] + </entry> - </row> - <row> - <entry> - jbosscache-cluster-name - </entry> - <entry> - cluster name (must be unique) - </entry> + </row> + <row> + <entry> + jbosscache-cluster-name + </entry> + <entry> + cluster name (must be unique) + </entry> - </row> - <row> - <entry> - max-volatile-time - </entry> - <entry> - max time to live for Volatile Index - </entry> + </row> + <row> + <entry> + max-volatile-time + </entry> + <entry> + max time to live for Volatile Index + </entry> - </row> - <row> - <entry> - rdbms-reindexing - </entry> - <entry> - indicate that need to use rdbms reindexing mechanism if possible, the default value is true - </entry> + </row> + <row> + <entry> + rdbms-reindexing + </entry> + <entry> + indicate that need to use rdbms reindexing mechanism if possible, the default value is true + </entry> - </row> - <row> - <entry> - reindexing-page-size - </entry> - <entry> - maximum amount of nodes which can be retrieved from storage for re-indexing purpose, the default value is 100 - </entry> + </row> + <row> + <entry> + reindexing-page-size + </entry> + <entry> + maximum amount of nodes which can be retrieved from storage for re-indexing purpose, the default value is 100 + </entry> - </row> - <row> - <entry> - index-recovery-mode - </entry> - <entry> - If the parameter has been set to <command>from-indexing</command>, so a full indexing will be automatically launched (default behavior), if the parameter has been set to <command>from-coordinator</command>, the index will be retrieved from coordinator - </entry> + </row> + <row> + <entry> + index-recovery-mode + </entry> + <entry> + If the parameter has been set to <command>from-indexing</command>, so a full indexing will be automatically launched (default behavior), if the parameter has been set to <command>from-coordinator</command>, the index will be retrieved from coordinator + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuration-Cluster_ready_indexing_strategies"> - <title>Cluster-ready indexing strategies</title> - <para> - For both cluster-ready implementations JBoss Cache, JGroups and Changes Filter values must be defined. Shared index requires some kind of remote or shared file system to be attached in a system (i.e. NFS, SMB or etc). Indexing directory ("indexDir" value) must point to it. Setting "changesfilter-class" to "org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" will enable shared index implementation. - </para> - + </section> + + <!--<section id="sect-Reference_Guide_eXo_JCR_1.14-Configuration-Cluster_ready_indexing_strategies"> + <title>Cluster-ready indexing strategies</title> + <para> + For both cluster-ready implementations JBoss Cache, JGroups and Changes Filter values must be defined. Shared index requires some kind of remote or shared file system to be attached in a system (i.e. NFS, SMB or etc). Indexing directory ("indexDir" value) must point to it. Setting "changesfilter-class" to "org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" will enable shared index implementation. + </para> + <programlisting language="XML" role="XML">&lt;workspace name="ws"&gt; &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; &lt;properties&gt; @@ -204,10 +204,10 @@ &lt;/properties&gt; &lt;/query-handler&gt; &lt;/workspace&gt;</programlisting> - <para> - In order to use cluster-ready strategy based on local indexes, when each node has own copy of index on local file system, the following configuration must be applied. Indexing directory must point to any folder on local file system and "changesfilter-class" must be set to "org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter". - </para> - + <para> + In order to use cluster-ready strategy based on local indexes, when each node has own copy of index on local file system, the following configuration must be applied. Indexing directory must point to any folder on local file system and "changesfilter-class" must be set to "org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter". + </para> + <programlisting language="XML" role="XML">&lt;workspace name="ws"&gt; &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; &lt;properties&gt; @@ -227,17 +227,16 @@ &lt;/workspace&gt; </programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuration-JBoss_Cache_template_configuration"> - <title>JBoss-Cache template configuration</title> - <para> - JBoss-Cache template configuration for query handler is about the same for both clustered strategies. - </para> - <para> - jbosscache-indexer.xml - </para> - + </section> --> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuration-JBoss_Cache_template_configuration"> + <title>JBoss-Cache template configuration</title> + <para> + JBoss-Cache template configuration for query handler is about the same for both clustered strategies. + </para> + +<example> + <title>jbosscache-indexer.xml</title> <programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; &lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; @@ -245,7 +244,7 @@ lockAcquisitionTimeout="20000" /&gt; &lt;!-- Configure the TransactionManager --&gt; &lt;transaction transactionManagerLookupClass="org.jboss.cache.transaction.JBoss<remark>Standalone</remark> - JTAManagerLookup" /&gt; + JTAManagerLookup" /&gt; &lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; @@ -261,16 +260,18 @@ &lt;/eviction&gt; &lt;/jbosscache&gt;</programlisting> - <para> - See more about template configurations <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration" />. - </para> +</example> - </section> - + <para> + Read more about template configurations <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-JBoss_Cache_configuration" />. + </para> - </section> - + </section> + + </section> + + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/aggregation-rule.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/aggregation-rule.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/aggregation-rule.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,20 +4,20 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_ntfile_node_by_content_of_child_jcrcontent_node"> - <title>Finding nt:file node by content of child jcr:content node</title> - <para> - The node type nt:file represents a file. It requires a single child node, called jcr:content. This node type represents images and other binary content in a JCRWiki entry. The node type of jcr:content is nt:resource which represents the actual content of a file. - </para> - <para> - Find node with the primary type is 'nt:file' and which whose 'jcr:content' child node contains "cats". - </para> - <para> - Normally, we can't find nodes (in our case) using just JCR SQL or XPath queries. But we can configure indexing so that nt:file aggregates jcr:content child node. - </para> - <para> - So, change indexing-configuration.xml: - </para> - + <title>Finding nt:file node by content of child jcr:content node</title> + <para> + The node type nt:file represents a file. It requires a single child node, called jcr:content. This node type represents images and other binary content in a JCRWiki entry. The node type of jcr:content is nt:resource which represents the actual content of a file. + </para> + <para> + Find node with the primary type is 'nt:file' and which whose 'jcr:content' child node contains "cats". + </para> + <para> + Normally, we can't find nodes (in our case) using just JCR SQL or XPath queries. But we can configure indexing so that nt:file aggregates jcr:content child node. + </para> + <para> + So, change indexing-configuration.xml: + </para> + <programlisting language="XML" role="XML">&lt;?xml version="1.0"?&gt; &lt;!DOCTYPE configuration SYSTEM "http://www.exoplatform.org/dtd/indexing-configuration-1.2.dtd"&gt; &lt;configuration xmlns:jcr="http://www.jcp.org/jcr/1.0" @@ -28,80 +28,80 @@ &lt;include-property&gt;jcr:content/jcr:lastModified&lt;/include-property&gt; &lt;/aggregate&gt; &lt;/configuration&gt;</programlisting> - <para> - Now the content of 'nt:file' and 'jcr:content' ('nt:resource') nodes are concatenated in a single Lucene document. Then, we can make a fulltext search query by content of 'nt:file'; this search includes the content of child 'jcr:content' node. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_ntfile_node_by_content_of_child_jcrcontent_node-Repository_structure"> - <title>Repository structure:</title> - <para> - Repository contains different nt:file nodes. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (nt:file) - </para> - <itemizedlist> - <listitem> - <para> - jcr:content (nt:resource) jcr:data = "The quick brown fox jumps over the lazy dog." - </para> + <para> + Now the content of 'nt:file' and 'jcr:content' ('nt:resource') nodes are concatenated in a single Lucene document. Then, we can make a fulltext search query by content of 'nt:file'; this search includes the content of child 'jcr:content' node. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_ntfile_node_by_content_of_child_jcrcontent_node-Repository_structure"> + <title>Repository structure:</title> + <para> + Repository contains different nt:file nodes. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (nt:file) + </para> + <itemizedlist> + <listitem> + <para> + jcr:content (nt:resource) jcr:data = "The quick brown fox jumps over the lazy dog." + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> - <listitem> - <para> - document2 (nt:file) - </para> - <itemizedlist> - <listitem> - <para> - jcr:content (nt:resource) jcr:data = "Dogs do not like cats." - </para> + </listitem> + <listitem> + <para> + document2 (nt:file) + </para> + <itemizedlist> + <listitem> + <para> + jcr:content (nt:resource) jcr:data = "Dogs do not like cats." + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> - <listitem> - <para> - document3 (nt:file) - </para> - <itemizedlist> - <listitem> - <para> - jcr:content (nt:resource) jcr:data = "Cats jumping high." - </para> + </listitem> + <listitem> + <para> + document3 (nt:file) + </para> + <itemizedlist> + <listitem> + <para> + jcr:content (nt:resource) jcr:data = "Cats jumping high." + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_ntfile_node_by_content_of_child_jcrcontent_node-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_ntfile_node_by_content_of_child_jcrcontent_node-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -109,10 +109,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -121,27 +121,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_ntfile_node_by_content_of_child_jcrcontent_node-Fetching_the_result"> - <title>Fetching the result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_ntfile_node_by_content_of_child_jcrcontent_node-Fetching_the_result"> + <title>Fetching the result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "document2" and "document3". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "document2" and "document3". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -150,52 +150,52 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_result-Table_content"> - <title>Table content</title> - <tgroup cols="2"> - <thead> - <row> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + </para> + <table> + <title>Table content</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - /document2 - </entry> - <entry> - 1030 - </entry> + </thead> + <tbody> + <row> + <entry> + /document2 + </entry> + <entry> + 1030 + </entry> - </row> - <row> - <entry> - /document3 - </entry> - <entry> - 1030 - </entry> + </row> + <row> + <entry> + /document3 + </entry> + <entry> + 1030 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/and-constraint.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/and-constraint.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/and-constraint.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,63 +4,63 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-AND_Constraint"> - <title>AND Constraint</title> - <para> - Find all fairytales with a page count more than 90 pages. - </para> - <para> - How does it sound in jcr terms - Find all nodes with mixin type 'mix:title' where the property 'jcr:description' equals "fairytale" and whose "prop_pagecount" property value is less than 90. - </para> - <note> - <para> - See also <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Multivalue_Property_Comparison" />. - </para> + <title>AND Constraint</title> + <para> + Find all fairytales with a page count more than 90 pages. + </para> + <para> + How does it sound in jcr terms - Find all nodes with mixin type 'mix:title' where the property 'jcr:description' equals "fairytale" and whose "prop_pagecount" property value is less than 90. + </para> + <note> + <para> + See also <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Multivalue_Property_Comparison" />. + </para> - </note> - <section id="sect-Reference_Guide_eXo_JCR_1.14-AND_Constraint-Repository_Structure"> - <title>Repository Structure:</title> - <para> - The repository contains mix:title nodes, where prop_pagecount has different values. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:title="War and peace" jcr:description="novel" prop_pagecount=1000 - </para> + </note> + <section id="sect-Reference_Guide_eXo_JCR_1.14-AND_Constraint-Repository_Structure"> + <title>Repository Structure:</title> + <para> + The repository contains mix:title nodes, where prop_pagecount has different values. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:title="War and peace" jcr:description="novel" prop_pagecount=1000 + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:title="Cinderella" jcr:description="fairytale" prop_pagecount=100 - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:title="Cinderella" jcr:description="fairytale" prop_pagecount=100 + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:title="Puss in Boots" jcr:description="fairytale" prop_pagecount=60 - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:title="Puss in Boots" jcr:description="fairytale" prop_pagecount=60 + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-AND_Constraint-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-AND_Constraint-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -68,10 +68,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -80,27 +80,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-AND_Constraint-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-AND_Constraint-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "document2". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "document2". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -109,62 +109,62 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="5"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - jcr:description - </entry> - <entry> - prop_pagecount - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + <table> + <title>Table content</title> + <tgroup cols="5"> + <thead> + <row> + <entry> + jcr:title + </entry> + <entry> + jcr:description + </entry> + <entry> + prop_pagecount + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - Cinderella - </entry> - <entry> - fairytale - </entry> - <entry> - 100 - </entry> - <entry> - /document2 - </entry> - <entry> - 7086 - </entry> + </thead> + <tbody> + <row> + <entry> + Cinderella + </entry> + <entry> + fairytale + </entry> + <entry> + 100 + </entry> + <entry> + /document2 + </entry> + <entry> + 7086 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/child-node-constraint.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/child-node-constraint.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/child-node-constraint.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,78 +4,33 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Child_Node_Constraint"> - <title>Child Node Constraint</title> - <para> - Find all nodes with the primary type 'nt:folder' that are children of node by path "/root1/root2". Only find children, do not find further descendants. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Child_Node_Constraint-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository is filled by "nt:folder" nodes. The nodes are placed in a multilayer tree. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - folder1 (nt:folder) - </para> - <itemizedlist> - <listitem> - <para> - folder2 (nt:folder) - </para> - <itemizedlist> - <listitem> - <para> - folder3 (nt:folder) // This node we want to find - </para> - <itemizedlist> - <listitem> - <para> - folder4 (nt:folder) // This node is not child but a descendant of '/folder1/folder2/'. - </para> - - </listitem> - - </itemizedlist> - - </listitem> - <listitem> - <para> - folder5 (nt:folder) // This node we want to find - </para> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Child_Node_Constraint-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - <para> - The use of "%" in the LIKE statement includes any string, therefore there is a second LIKE statement that excludes that the string contains "/". This way child nodes are included but descendant nodes are excluded. - </para> - + <title>Child Node Constraint</title> + <para> + Find all nodes with the primary type '<literal>nt:folder</literal>' that are children of node by path "<filename>/root1/root2</filename>". Only find children, do not find further descendants. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Child_Node_Constraint-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository is filled by "<literal>nt:folder</literal>" nodes. The nodes are placed in a multilayer tree. + </para> +<screen>root +└── folder1 (nt:folder) + └── folder2 (nt:folder) + ├── folder3 (nt:folder) // This node we want to find + │ └── folder4 (nt:folder) // This node is not child but a descendant of '/folder1/folder2/' + └── folder5 (nt:folder) // This node we want to find +</screen> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Child_Node_Constraint-Query_Execution"> + <title>Query Execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <para> + The use of "%" in the LIKE statement includes any string, therefore there is a second LIKE statement that excludes that the string contains "/". This way child nodes are included but descendant nodes are excluded. + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -83,10 +38,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -95,27 +50,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Child_Node_Constraint-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Child_Node_Constraint-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - The NodeIterator will return "folder3" and "folder5". - </para> - <para> - We can also get a table: - </para> - + <para> + The NodeIterator will return "folder3" and "folder5". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -124,53 +79,53 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - The table content is: - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="2"> - <thead> - <row> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + The table content is: + <table> + <title>Table content</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - /folder1/folder2/folder3 - </entry> - <entry> - 1707 - </entry> + </thead> + <tbody> + <row> + <entry> + /folder1/folder2/folder3 + </entry> + <entry> + 1707 + </entry> - </row> - <row> - <entry> - /folder1/folder2/folder5 - </entry> - <entry> - 1707 - </entry> + </row> + <row> + <entry> + /folder1/folder2/folder5 + </entry> + <entry> + 1707 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/date-property-comparison.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/date-property-comparison.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/date-property-comparison.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,87 +4,87 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Date_Property_Comparison"> - <title>Date Property Comparison</title> - <para> - Find all nodes of primary type "nt:resource" whose jcr:lastModified property value is greater than 2006-06-04 and less than 2008-06-04. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Date_Property_Comparison-Repository_Structure"> - <title>Repository Structure</title> - <para> - Repository contains nt:resource nodes with different values of jcr:lastModified property - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (nt:file) - </para> - <itemizedlist> - <listitem> - <para> - jcr:content (nt:resource) jcr:lastModified="2006-01-19T15:34:15.917+02:00" - </para> + <title>Date Property Comparison</title> + <para> + Find all nodes of primary type "nt:resource" whose jcr:lastModified property value is greater than 2006-06-04 and less than 2008-06-04. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Date_Property_Comparison-Repository_Structure"> + <title>Repository Structure</title> + <para> + Repository contains nt:resource nodes with different values of jcr:lastModified property + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (nt:file) + </para> + <itemizedlist> + <listitem> + <para> + jcr:content (nt:resource) jcr:lastModified="2006-01-19T15:34:15.917+02:00" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> - <listitem> - <para> - document2 (nt:file) - </para> - <itemizedlist> - <listitem> - <para> - jcr:content (nt:resource) jcr:lastModified="2005-01-19T15:34:15.917+02:00" - </para> + </listitem> + <listitem> + <para> + document2 (nt:file) + </para> + <itemizedlist> + <listitem> + <para> + jcr:content (nt:resource) jcr:lastModified="2005-01-19T15:34:15.917+02:00" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> - <listitem> - <para> - document3 (nt:file) - </para> - <itemizedlist> - <listitem> - <para> - jcr:content (nt:resource) jcr:lastModified="2007-01-19T15:34:15.917+02:00" - </para> + </listitem> + <listitem> + <para> + document3 (nt:file) + </para> + <itemizedlist> + <listitem> + <para> + jcr:content (nt:resource) jcr:lastModified="2007-01-19T15:34:15.917+02:00" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Date_Property_Comparison-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - <para> - In SQL you have to use the keyword <emphasis role="bold">TIMESTAMP</emphasis> for date comparisons. Otherwise, the date would be interpreted as a string. The date has to be surrounded by single quotes (TIMESTAMP 'datetime') and in the ISO standard format: YYYY-MM-DDThh:mm:ss.sTZD ( <ulink url="http://en.wikipedia.org/wiki/ISO_8601">http://en.wikipe... and well explained in a W3C note <ulink url="http://www.w3.org/TR/NOTE-datetime">http://www.w3.org/T...>). - </para> - <para> - You will see that it can be a date only (YYYY-MM-DD) but also a complete date and time with a timezone designator (TZD). - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Date_Property_Comparison-Query_Execution"> + <title>Query Execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <para> + In SQL you have to use the keyword <emphasis role="bold">TIMESTAMP</emphasis> for date comparisons. Otherwise, the date would be interpreted as a string. The date has to be surrounded by single quotes (TIMESTAMP 'datetime') and in the ISO standard format: YYYY-MM-DDThh:mm:ss.sTZD ( <ulink url="http://en.wikipedia.org/wiki/ISO_8601">http://en.wikipe... and well explained in a W3C note <ulink url="http://www.w3.org/TR/NOTE-datetime">http://www.w3.org/T...>). + </para> + <para> + You will see that it can be a date only (YYYY-MM-DD) but also a complete date and time with a timezone designator (TZD). + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -101,13 +101,13 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - <para> - Compared to the SQL format, you have to use the keyword <emphasis role="bold">xs:dateTime</emphasis> and surround the datetime by extra brackets: xs:dateTime('datetime'). The actual format of the datetime also conforms with the ISO date standard. - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <para> + Compared to the SQL format, you have to use the keyword <emphasis role="bold">xs:dateTime</emphasis> and surround the datetime by extra brackets: xs:dateTime('datetime'). The actual format of the datetime also conforms with the ISO date standard. + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -123,27 +123,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Date_Property_Comparison-Fetching_the_result"> - <title>Fetching the result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Date_Property_Comparison-Fetching_the_result"> + <title>Fetching the result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node foundNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "/document3/jcr:content". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "/document3/jcr:content". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -152,50 +152,50 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - The table content is: - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_result-Table_content"> - <title>Table content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - jcr:lastModified - </entry> - <entry> - ... - </entry> - <entry> - jcr:path - </entry> + <para> + The table content is: + <table> + <title>Table content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + jcr:lastModified + </entry> + <entry> + ... + </entry> + <entry> + jcr:path + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - 2007-01-19T15:34:15.917+02:00 - </entry> - <entry> - ... - </entry> - <entry> - /document3/jcr:content - </entry> + </thead> + <tbody> + <row> + <entry> + 2007-01-19T15:34:15.917+02:00 + </entry> + <entry> + ... + </entry> + <entry> + /document3/jcr:content + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/escaping-like-statements.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/escaping-like-statements.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/escaping-like-statements.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,65 +4,65 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Escaping_in_LIKE_Statements"> - <title>Escaping in LIKE Statements</title> - <para> - Find all nodes with a mixin type 'mix:title' and whose property 'jcr:title' starts with 'P%ri'. - </para> - <para> - As you see "P%rison break" contains the symbol '%'. This symbol is reserved for LIKE comparisons. So what can we do? - </para> - <para> - Within the LIKE pattern, literal instances of percent ("%") or underscore ("_") must be escaped. The SQL ESCAPE clause allows the definition of an arbitrary escape character within the context of a single LIKE statement. The following example defines the backslash ' \' as escape character: - </para> - + <title>Escaping in LIKE Statements</title> + <para> + Find all nodes with a mixin type 'mix:title' and whose property 'jcr:title' starts with 'P%ri'. + </para> + <para> + As you see "P%rison break" contains the symbol '%'. This symbol is reserved for LIKE comparisons. So what can we do? + </para> + <para> + Within the LIKE pattern, literal instances of percent ("%") or underscore ("_") must be escaped. The SQL ESCAPE clause allows the definition of an arbitrary escape character within the context of a single LIKE statement. The following example defines the backslash ' \' as escape character: + </para> + <programlisting>SELECT * FROM mytype WHERE a LIKE 'foo\%' ESCAPE '\'</programlisting> - <para> - XPath does not have any specification for defining escape symbols, so we must use the default escape character (' \'). - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Escaping_in_LIKE_Statements-Repository_structure"> - <title>Repository structure</title> - <para> - The repository contains mix:title nodes, where jcr:title can have different values. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:title="Star wars" jcr:description="Dart rules!!" - </para> + <para> + XPath does not have any specification for defining escape symbols, so we must use the default escape character (' \'). + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Escaping_in_LIKE_Statements-Repository_structure"> + <title>Repository structure</title> + <para> + The repository contains mix:title nodes, where jcr:title can have different values. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:title="Star wars" jcr:description="Dart rules!!" + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:title="P%rison break" jcr:description="Run, Forest, run ))" - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:title="P%rison break" jcr:description="Run, Forest, run ))" + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:title="Panopticum" jcr:description="It's imagine film" - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:title="Panopticum" jcr:description="It's imagine film" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Escaping_in_LIKE_Statements-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Escaping_in_LIKE_Statements-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -70,10 +70,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -82,27 +82,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Escaping_in_LIKE_Statements-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Escaping_in_LIKE_Statements-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "document2". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "document2". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -111,56 +111,56 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - The table content is - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - jcr:description - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + The table content is + <table> + <title>Table content</title> + <tgroup cols="4"> + <thead> + <row> + <entry> + jcr:title + </entry> + <entry> + jcr:description + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - P%rison break - </entry> - <entry> - Run, Forest, run )) - </entry> - <entry> - /document2 - </entry> - <entry> - 7452 - </entry> + </thead> + <tbody> + <row> + <entry> + P%rison break + </entry> + <entry> + Run, Forest, run )) + </entry> + <entry> + /document2 + </entry> + <entry> + 7452 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/exact-path-constraint.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/exact-path-constraint.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/exact-path-constraint.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,75 +4,75 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Exact_Path_Constraint"> - <title>Exact Path Constraint</title> - <para> - Find a node with the primary type 'nt:file' that is located on the exact path "/folder1/folder2/document1". - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Exact_Path_Constraint-Repository_Structure"> - <title>Repository Structure</title> - <para> - Repository filled by different nodes. There are several folders which contain other folders and files. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - folder1 (nt:folder) - </para> - <itemizedlist> - <listitem> - <para> - folder2 (nt:folder) - </para> - <itemizedlist> - <listitem> - <para> - document1 (nt:file) // This document we want to find - </para> + <title>Exact Path Constraint</title> + <para> + Find a node with the primary type 'nt:file' that is located on the exact path "/folder1/folder2/document1". + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Exact_Path_Constraint-Repository_Structure"> + <title>Repository Structure</title> + <para> + Repository filled by different nodes. There are several folders which contain other folders and files. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + folder1 (nt:folder) + </para> + <itemizedlist> + <listitem> + <para> + folder2 (nt:folder) + </para> + <itemizedlist> + <listitem> + <para> + document1 (nt:file) // This document we want to find + </para> - </listitem> - <listitem> - <para> - folder3 (nt:folder) - </para> - <itemizedlist> - <listitem> - <para> - document1 (nt:file) - </para> + </listitem> + <listitem> + <para> + folder3 (nt:folder) + </para> + <itemizedlist> + <listitem> + <para> + document1 (nt:file) + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Exact_Path_Constraint-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Exact_Path_Constraint-Query_Execution"> + <title>Query Execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // we want find 'document1' @@ -81,10 +81,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // we want to find 'document1' @@ -93,31 +93,31 @@ Query query = queryManager.createQuery(xpathStatement, Query.XPATH); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - Remark: The indexes [1] are used in order to get the same result as the SQL statement. SQL by default only returns the first node, whereas XPath fetches by default all nodes. - </para> + <para> + Remark: The indexes [1] are used in order to get the same result as the SQL statement. SQL by default only returns the first node, whereas XPath fetches by default all nodes. + </para> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Exact_Path_Constraint-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Exact_Path_Constraint-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return expected "document1". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return expected "document1". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -126,44 +126,44 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="2"> - <thead> - <row> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + <table> + <title>Table content</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - /folder1/folder2/document1 - </entry> - <entry> - 1030 - </entry> + </thead> + <tbody> + <row> + <entry> + /folder1/folder2/document1 + </entry> + <entry> + 1030 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-all-descendant-nodes.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-all-descendant-nodes.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-all-descendant-nodes.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,75 +4,75 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Descendant_Nodes"> - <title>Finding All Descendant Nodes</title> - <para> - Find all nodes with the primary type 'nt:folder' that are descendants of the node "/folder1/folder2". - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Descendant_Nodes-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository contains "nt:folder" nodes. The nodes are placed in a multilayer tree. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - folder1 (nt:folder) - </para> - <itemizedlist> - <listitem> - <para> - folder2 (nt:folder) - </para> - <itemizedlist> - <listitem> - <para> - folder3 (nt:folder) // This node we want to find - </para> - <itemizedlist> - <listitem> - <para> - folder4 (nt:folder) // This node we want to find - </para> + <title>Finding All Descendant Nodes</title> + <para> + Find all nodes with the primary type 'nt:folder' that are descendants of the node "/folder1/folder2". + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Descendant_Nodes-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository contains "nt:folder" nodes. The nodes are placed in a multilayer tree. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + folder1 (nt:folder) + </para> + <itemizedlist> + <listitem> + <para> + folder2 (nt:folder) + </para> + <itemizedlist> + <listitem> + <para> + folder3 (nt:folder) // This node we want to find + </para> + <itemizedlist> + <listitem> + <para> + folder4 (nt:folder) // This node we want to find + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> - <listitem> - <para> - folder5 (nt:folder) // This node we want to find - </para> + </listitem> + <listitem> + <para> + folder5 (nt:folder) // This node we want to find + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Descendant_Nodes-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Descendant_Nodes-Query_Execution"> + <title>Query Execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -80,10 +80,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -92,27 +92,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Descendant_Nodes-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Descendant_Nodes-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - The NodeIterator will return "folder3", "folder4" and "folder5" nodes. - </para> - <para> - We can also get a table: - </para> - + <para> + The NodeIterator will return "folder3", "folder4" and "folder5" nodes. + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -121,62 +121,62 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="2"> - <thead> - <row> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + <table> + <title>Table content</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - /folder1/folder2/folder3 - </entry> - <entry> - 1000 - </entry> + </thead> + <tbody> + <row> + <entry> + /folder1/folder2/folder3 + </entry> + <entry> + 1000 + </entry> - </row> - <row> - <entry> - /folder1/folder2/folder3/folder4 - </entry> - <entry> - 1000 - </entry> + </row> + <row> + <entry> + /folder1/folder2/folder3/folder4 + </entry> + <entry> + 1000 + </entry> - </row> - <row> - <entry> - /folder1/folder2/folder5 - </entry> - <entry> - 1000 - </entry> + </row> + <row> + <entry> + /folder1/folder2/folder5 + </entry> + <entry> + 1000 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-all-nodes.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-all-nodes.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-all-nodes.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,72 +4,72 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Nodes"> - <title>Finding All Nodes</title> - <para> - Find all nodes in the repository. Only those nodes are found to which the session has READ permission. See also <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Access_Control" />. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Nodes-Repository_structure"> - <title>Repository structure:</title> - <para> - Repository contains many different nodes. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - folder1 (nt:folder) - </para> - <itemizedlist> - <listitem> - <para> - document1 (nt:file) - </para> + <title>Finding All Nodes</title> + <para> + Find all nodes in the repository. Only those nodes are found to which the session has READ permission. See also <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Access_Control" />. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Nodes-Repository_structure"> + <title>Repository structure:</title> + <para> + Repository contains many different nodes. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + folder1 (nt:folder) + </para> + <itemizedlist> + <listitem> + <para> + document1 (nt:file) + </para> - </listitem> - <listitem> - <para> - folder2 (nt:folder) - </para> - <itemizedlist> - <listitem> - <para> - document2 (nt:unstructured) - </para> + </listitem> + <listitem> + <para> + folder2 (nt:folder) + </para> + <itemizedlist> + <listitem> + <para> + document2 (nt:unstructured) + </para> - </listitem> - <listitem> - <para> - document3 (nt:folder) - </para> + </listitem> + <listitem> + <para> + document3 (nt:folder) + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Nodes-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Nodes-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -77,10 +77,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -89,27 +89,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Nodes-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_All_Nodes-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "folder1", "folder2","document1","document2","document3", and each other nodes in workspace if they are here. - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "folder1", "folder2","document1","document2","document3", and each other nodes in workspace if they are here. + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -118,88 +118,88 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="2"> - <thead> - <row> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is + </para> + <table> + <title>Table content</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - /folder1 - </entry> - <entry> - 1000 - </entry> + </thead> + <tbody> + <row> + <entry> + /folder1 + </entry> + <entry> + 1000 + </entry> - </row> - <row> - <entry> - /folder1/document1 - </entry> - <entry> - 1000 - </entry> + </row> + <row> + <entry> + /folder1/document1 + </entry> + <entry> + 1000 + </entry> - </row> - <row> - <entry> - /folder1/folder2 - </entry> - <entry> - 1000 - </entry> + </row> + <row> + <entry> + /folder1/folder2 + </entry> + <entry> + 1000 + </entry> - </row> - <row> - <entry> - /folder1/folder2/document2 - </entry> - <entry> - 1000 - </entry> + </row> + <row> + <entry> + /folder1/folder2/document2 + </entry> + <entry> + 1000 + </entry> - </row> - <row> - <entry> - /folder1/folder2/document3 - </entry> - <entry> - 1000 - </entry> + </row> + <row> + <entry> + /folder1/folder2/document3 + </entry> + <entry> + 1000 + </entry> - </row> - <row> - <entry> - ... - </entry> - <entry> - ... - </entry> + </row> + <row> + <entry> + ... + </entry> + <entry> + ... + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-by-mixin-type.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-by-mixin-type.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-by-mixin-type.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,54 +4,54 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Mixin_Type"> - <title>Finding Nodes by Mixin Type</title> - <para> - Find all nodes in repository, that contain a mixin type "mix:title". - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Mixin_Type-Repository_structure"> - <title>Repository structure:</title> - <para> - The repository contains nodes with different primary types and mixin types. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 primarytype = "nt:unstructured" mixintype = "mix:title" - </para> + <title>Finding Nodes by Mixin Type</title> + <para> + Find all nodes in repository, that contain a mixin type "mix:title". + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Mixin_Type-Repository_structure"> + <title>Repository structure:</title> + <para> + The repository contains nodes with different primary types and mixin types. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 primarytype = "nt:unstructured" mixintype = "mix:title" + </para> - </listitem> - <listitem> - <para> - document2 primarytype = "nt:file" mixintype = "mix:lockable" - </para> + </listitem> + <listitem> + <para> + document2 primarytype = "nt:file" mixintype = "mix:lockable" + </para> - </listitem> - <listitem> - <para> - document3 primarytype = "nt:file" mixintype = "mix:title" - </para> + </listitem> + <listitem> + <para> + document3 primarytype = "nt:file" mixintype = "mix:title" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Mixin_Type-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Mixin_Type-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -59,10 +59,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -71,27 +71,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Mixin_Type-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Mixin_Type-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - The NodeIterator will return "document1" and "document3". - </para> - <para> - We can also get a table: - </para> - + <para> + The NodeIterator will return "document1" and "document3". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -100,71 +100,71 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - ... - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is + <table> + <title>Table content</title> + <tgroup cols="4"> + <thead> + <row> + <entry> + jcr:title + </entry> + <entry> + ... + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - First document - </entry> - <entry> - ... - </entry> - <entry> - /document1 - </entry> - <entry> - 2674 - </entry> + </thead> + <tbody> + <row> + <entry> + First document + </entry> + <entry> + ... + </entry> + <entry> + /document1 + </entry> + <entry> + 2674 + </entry> - </row> - <row> - <entry> - Second document - </entry> - <entry> - ... - </entry> - <entry> - /document3 - </entry> - <entry> - 2674 - </entry> + </row> + <row> + <entry> + Second document + </entry> + <entry> + ... + </entry> + <entry> + /document3 + </entry> + <entry> + 2674 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-by-primary-type.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-by-primary-type.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-by-primary-type.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,54 +4,54 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Primary_Type"> - <title>Finding Nodes by Primary Type</title> - <para> - Find all nodes whose primary type is "nt:file". - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Primary_Type-Repository_structure"> - <title>Repository structure:</title> - <para> - The repository contains nodes with different primary types and mixin types. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 primarytype = "nt:unstructured" mixintype = "mix:title" - </para> + <title>Finding Nodes by Primary Type</title> + <para> + Find all nodes whose primary type is "nt:file". + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Primary_Type-Repository_structure"> + <title>Repository structure:</title> + <para> + The repository contains nodes with different primary types and mixin types. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 primarytype = "nt:unstructured" mixintype = "mix:title" + </para> - </listitem> - <listitem> - <para> - document2 primarytype = "nt:file" mixintype = "mix:lockable" - </para> + </listitem> + <listitem> + <para> + document2 primarytype = "nt:file" mixintype = "mix:lockable" + </para> - </listitem> - <listitem> - <para> - document3 primarytype = "nt:file" mixintype = "mix:title" - </para> + </listitem> + <listitem> + <para> + document3 primarytype = "nt:file" mixintype = "mix:title" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Primary_Type-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Primary_Type-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -59,10 +59,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -71,27 +71,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Primary_Type-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_by_Primary_Type-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "document2" and "document3". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "document2" and "document3". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -100,53 +100,53 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - The table content is - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="2"> - <thead> - <row> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + The table content is + <table> + <title>Table content</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - /document2 - </entry> - <entry> - 2674 - </entry> + </thead> + <tbody> + <row> + <entry> + /document2 + </entry> + <entry> + 2674 + </entry> - </row> - <row> - <entry> - /document3 - </entry> - <entry> - 2674 - </entry> + </row> + <row> + <entry> + /document3 + </entry> + <entry> + 2674 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-case-insensitive.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-case-insensitive.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-nodes-case-insensitive.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,63 +4,63 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_in_a_Case_Insensitive_Way"> - <title>Finding Nodes in a Case-Insensitive Way</title> - <para> - Find all nodes with a mixin type 'mix:title' and where the property 'jcr:title' equals 'casesensitive' in lower or upper case. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_in_a_Case_Insensitive_Way-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository contains mix:title nodes, whose jcr:title properties have different values. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:title="CaseSensitive" - </para> + <title>Finding Nodes in a Case-Insensitive Way</title> + <para> + Find all nodes with a mixin type 'mix:title' and where the property 'jcr:title' equals 'casesensitive' in lower or upper case. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_in_a_Case_Insensitive_Way-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository contains mix:title nodes, whose jcr:title properties have different values. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:title="CaseSensitive" + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:title="casesensitive" - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:title="casesensitive" + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:title="caseSENSITIVE" - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:title="caseSENSITIVE" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_in_a_Case_Insensitive_Way-Query_Execution"> - <title>Query Execution</title> - <itemizedlist> - <listitem> - <para> - UPPER case - </para> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_in_a_Case_Insensitive_Way-Query_Execution"> + <title>Query Execution</title> + <itemizedlist> + <listitem> + <para> + UPPER case + </para> - </listitem> + </listitem> - </itemizedlist> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </itemizedlist> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -68,10 +68,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -79,19 +79,19 @@ Query query = queryManager.createQuery(xpathStatement, Query.XPATH); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <itemizedlist> - <listitem> - <para> - LOWER case - </para> + <itemizedlist> + <listitem> + <para> + LOWER case + </para> - </listitem> + </listitem> - </itemizedlist> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </itemizedlist> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -99,10 +99,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -111,27 +111,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_in_a_Case_Insensitive_Way-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Nodes_in_a_Case_Insensitive_Way-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "document1", "document2" and "document3" (in all examples). - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "document1", "document2" and "document3" (in all examples). + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -140,74 +140,74 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - ... - </entry> - <entry> - jcr:path - </entry> + <para> + Table content is: + <table> + <title>Table content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + jcr:title + </entry> + <entry> + ... + </entry> + <entry> + jcr:path + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - CaseSensitive - </entry> - <entry> - ... - </entry> - <entry> - /document1 - </entry> + </thead> + <tbody> + <row> + <entry> + CaseSensitive + </entry> + <entry> + ... + </entry> + <entry> + /document1 + </entry> - </row> - <row> - <entry> - casesensitive - </entry> - <entry> - ... - </entry> - <entry> - /document2 - </entry> + </row> + <row> + <entry> + casesensitive + </entry> + <entry> + ... + </entry> + <entry> + /document2 + </entry> - </row> - <row> - <entry> - caseSENSITIVE - </entry> - <entry> - ... - </entry> - <entry> - /document3 - </entry> + </row> + <row> + <entry> + caseSENSITIVE + </entry> + <entry> + ... + </entry> + <entry> + /document3 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-similar-nodes.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-similar-nodes.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/find-similar-nodes.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,23 +4,23 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Similar_Nodes"> - <title>Finding Similar Nodes</title> - <para> - Find similar nodes to node by path '/baseFile/jcr:content'. - </para> - <para> - In our example, baseFile will contain text where "terms" word happens many times. That's a reason why the existence of this word will be used as a criteria of node similarity (for node baseFile). - </para> - <note> - <para> - See also about Similarity and configuration - <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Searching_Repository_Content" /> - </para> + <title>Finding Similar Nodes</title> + <para> + Find similar nodes to node by path '/baseFile/jcr:content'. + </para> + <para> + In our example, baseFile will contain text where "terms" word happens many times. That's a reason why the existence of this word will be used as a criteria of node similarity (for node baseFile). + </para> + <note> + <para> + See also about Similarity and configuration - <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Searching_Repository_Content" /> + </para> - </note> - <para> - Higlighting support must be added to configuration. test-jcr-config.xml: - </para> - + </note> + <para> + Higlighting support must be added to configuration. test-jcr-config.xml: + </para> + <programlisting language="Java" role="Java">&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; &lt;properties&gt; ... @@ -28,92 +28,92 @@ ... &lt;/properties&gt; &lt;/query-handler&gt;</programlisting> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Similar_Nodes-Repository_structure"> - <title>Repository structure:</title> - <para> - Repository contains many nt:file nodes" - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - baseFile (nt:file) - </para> - <itemizedlist> - <listitem> - <para> - jcr:content (nt:resource) jcr:data="Similarity is determined by looking up <emphasis role="bold">terms</emphasis> that are common to nodes. There are some conditions that must be met for a <emphasis role="bold">term</emphasis> to be considered. This is required to limit the number possibly relevant <emphasis role="bold">terms</emphasis>. Only <emphasis role="bold">terms</emphasis> with at least 4 characters are considered. Only <emphasis role="bold">terms</emphasis> that occur at least 2 times in the source node are considered. Only <emphasis role="bold">terms</emphasis> that occur in at least 5 nodes are considered." - </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Similar_Nodes-Repository_structure"> + <title>Repository structure:</title> + <para> + Repository contains many nt:file nodes" + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + baseFile (nt:file) + </para> + <itemizedlist> + <listitem> + <para> + jcr:content (nt:resource) jcr:data="Similarity is determined by looking up <emphasis role="bold">terms</emphasis> that are common to nodes. There are some conditions that must be met for a <emphasis role="bold">term</emphasis> to be considered. This is required to limit the number possibly relevant <emphasis role="bold">terms</emphasis>. Only <emphasis role="bold">terms</emphasis> with at least 4 characters are considered. Only <emphasis role="bold">terms</emphasis> that occur at least 2 times in the source node are considered. Only <emphasis role="bold">terms</emphasis> that occur in at least 5 nodes are considered." + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> - <listitem> - <para> - target1 (nt:file) - </para> - <itemizedlist> - <listitem> - <para> - jcr:content (nt:resource) jcr:data="Similarity is determined by looking up <emphasis role="bold">terms</emphasis> that are common to nodes." - </para> + </listitem> + <listitem> + <para> + target1 (nt:file) + </para> + <itemizedlist> + <listitem> + <para> + jcr:content (nt:resource) jcr:data="Similarity is determined by looking up <emphasis role="bold">terms</emphasis> that are common to nodes." + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> - <listitem> - <para> - target2 (nt:file) - </para> - <itemizedlist> - <listitem> - <para> - jcr:content (nt:resource) jcr:data="There is no you know what" - </para> + </listitem> + <listitem> + <para> + target2 (nt:file) + </para> + <itemizedlist> + <listitem> + <para> + jcr:content (nt:resource) jcr:data="There is no you know what" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> - <listitem> - <para> - target3 (nt:file) - </para> - <itemizedlist> - <listitem> - <para> - jcr:content (nt:resource) jcr:data=" <emphasis role="bold">Terms</emphasis> occurs here" - </para> + </listitem> + <listitem> + <para> + target3 (nt:file) + </para> + <itemizedlist> + <listitem> + <para> + jcr:content (nt:resource) jcr:data=" <emphasis role="bold">Terms</emphasis> occurs here" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Similar_Nodes-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Similar_Nodes-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -121,10 +121,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -133,30 +133,30 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Similar_Nodes-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Finding_Similar_Nodes-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "/baseFile/jcr:content","/target1/jcr:content" and "/target3/jcr:content". - </para> - <para> - As you see the base node are also in result set. - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "/baseFile/jcr:content","/target1/jcr:content" and "/target3/jcr:content". + </para> + <para> + As you see the base node are also in result set. + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -165,73 +165,73 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - The table content is - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - jcr:path - </entry> - <entry> - ... - </entry> - <entry> - jcr:score - </entry> + <para> + The table content is + </para> + <table> + <title>Table content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + jcr:path + </entry> + <entry> + ... + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - /baseFile/jcr:content - </entry> - <entry> - ... - </entry> - <entry> - 2674 - </entry> + </thead> + <tbody> + <row> + <entry> + /baseFile/jcr:content + </entry> + <entry> + ... + </entry> + <entry> + 2674 + </entry> - </row> - <row> - <entry> - /target1/jcr:content - </entry> - <entry> - ... - </entry> - <entry> - 2674 - </entry> + </row> + <row> + <entry> + /target1/jcr:content + </entry> + <entry> + ... + </entry> + <entry> + 2674 + </entry> - </row> - <row> - <entry> - /target3/jcr:content - </entry> - <entry> - ... - </entry> - <entry> - 2674 - </entry> + </row> + <row> + <entry> + /target3/jcr:content + </entry> + <entry> + ... + </entry> + <entry> + 2674 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/fulltext-search-by-all-properties.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/fulltext-search-by-all-properties.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/fulltext-search-by-all-properties.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,54 +4,54 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_All_Properties_in_Node"> - <title>Fulltext Search by All Properties in Node</title> - <para> - Find nodes with mixin type 'mix:title' where any property contains 'break' string. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_All_Properties_in_Node-Repository_structure"> - <title>Repository structure:</title> - <para> - Repository filled with different nodes with mixin type 'mix:title' and different values of 'jcr:title' and 'jcr:description' properties. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:title ='Star Wars' jcr:description = 'Dart rules!!' - </para> + <title>Fulltext Search by All Properties in Node</title> + <para> + Find nodes with mixin type 'mix:title' where any property contains 'break' string. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_All_Properties_in_Node-Repository_structure"> + <title>Repository structure:</title> + <para> + Repository filled with different nodes with mixin type 'mix:title' and different values of 'jcr:title' and 'jcr:description' properties. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:title ='Star Wars' jcr:description = 'Dart rules!!' + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:title ='Prison <emphasis>break</emphasis>' jcr:description = 'Run, Forest, run ))' - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:title ='Prison <emphasis>break</emphasis>' jcr:description = 'Run, Forest, run ))' + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:title ='Titanic' jcr:description = 'An iceberg <emphasis>break</emphasis>s a ship.' - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:title ='Titanic' jcr:description = 'An iceberg <emphasis>break</emphasis>s a ship.' + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_All_Properties_in_Node-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_All_Properties_in_Node-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); String sqlStatement = "SELECT * FROM mix:title WHERE CONTAINS(*,'break')"; @@ -59,10 +59,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // we want find 'document1' @@ -72,27 +72,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_All_Properties_in_Node-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_All_Properties_in_Node-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); while(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "document1" and "document2". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "document1" and "document2". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -101,70 +101,70 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - jcr:description - </entry> - <entry> - ... - </entry> - <entry> - jcr:path - </entry> + <para> + Table content is: + </para> + <table> + <title>Table content</title> + <tgroup cols="4"> + <thead> + <row> + <entry> + jcr:title + </entry> + <entry> + jcr:description + </entry> + <entry> + ... + </entry> + <entry> + jcr:path + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - Prison break. - </entry> - <entry> - Run, Forest, run )) - </entry> - <entry> - ... - </entry> - <entry> - /document2 - </entry> + </thead> + <tbody> + <row> + <entry> + Prison break. + </entry> + <entry> + Run, Forest, run )) + </entry> + <entry> + ... + </entry> + <entry> + /document2 + </entry> - </row> - <row> - <entry> - Titanic - </entry> - <entry> - An iceberg breaks a ship. - </entry> - <entry> - ... - </entry> - <entry> - /document3 - </entry> + </row> + <row> + <entry> + Titanic + </entry> + <entry> + An iceberg breaks a ship. + </entry> + <entry> + ... + </entry> + <entry> + /document3 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/fulltext-search-by-property.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/fulltext-search-by-property.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/fulltext-search-by-property.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,60 +4,60 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_Property"> - <title>Fulltext Search by Property</title> - <para> - Find all nodes containing a mixin type 'mix:title' and whose 'jcr:description' contains "forest" string. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_Property-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository is filled with nodes of the mixin type 'mix:title' and different values of the 'jcr:description' property. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:description = "The quick brown fox jumps over the lazy dog." - </para> + <title>Fulltext Search by Property</title> + <para> + Find all nodes containing a mixin type 'mix:title' and whose 'jcr:description' contains "forest" string. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_Property-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository is filled with nodes of the mixin type 'mix:title' and different values of the 'jcr:description' property. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:description = "The quick brown fox jumps over the lazy dog." + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:description = "The brown fox lives in a <emphasis role="underscore">forest</emphasis>." // This is the node we want to find - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:description = "The brown fox lives in a <emphasis role="underscore">forest</emphasis>." // This is the node we want to find + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:description = "The fox is a nice animal." - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:description = "The fox is a nice animal." + </para> - </listitem> - <listitem> - <para> - document4 (nt:unstructured) jcr:description = "There is the word forest, too." - </para> + </listitem> + <listitem> + <para> + document4 (nt:unstructured) jcr:description = "There is the word forest, too." + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_Property-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_Property-Query_Execution"> + <title>Query Execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // we want find document which contains "forest" word @@ -66,10 +66,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // we want find document which contains "forest" word @@ -79,27 +79,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_Property-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Fulltext_Search_by_Property-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "document2". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "document2". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -108,49 +108,49 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - jcr:description - </entry> - <entry> - ... - </entry> - <entry> - jcr:path - </entry> + <para> + Table content is: + </para> + <table> + <title>Table content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + jcr:description + </entry> + <entry> + ... + </entry> + <entry> + jcr:path + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - The brown fox lives in forest. - </entry> - <entry> - ... - </entry> - <entry> - /document2 - </entry> + </thead> + <tbody> + <row> + <entry> + The brown fox lives in forest. + </entry> + <entry> + ... + </entry> + <entry> + /document2 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/higlight.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/higlight.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/higlight.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,19 +4,19 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-High_lighting_Result_of_Fulltext_Search"> - <title>High-lighting Result of Fulltext Search</title> - <para> - It's also called excerption (see Excerpt configuration in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration" /> article). - </para> - <para> - The goal of this query is to find words "eXo" and "implementation" with fulltext search and high-light this words in result value. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-High_lighting_Result_of_Fulltext_Search-Base_info"> - <title>Base info</title> - <para> - High-lighting is not default feature so we must set it in jcr-config.xml, also excerpt provider must be defined: - </para> - + <title>High-lighting Result of Fulltext Search</title> + <para> + It's also called excerption (see Excerpt configuration in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration" /> article). + </para> + <para> + The goal of this query is to find words "eXo" and "implementation" with fulltext search and high-light this words in result value. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-High_lighting_Result_of_Fulltext_Search-Base_info"> + <title>Base info</title> + <para> + High-lighting is not default feature so we must set it in jcr-config.xml, also excerpt provider must be defined: + </para> + <programlisting language="XML" role="XML">&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; &lt;properties&gt; ... @@ -25,64 +25,64 @@ ... &lt;properties&gt; &lt;/query-handler&gt;</programlisting> - <para> - Also, remember that we can make indexing rules, as in the example below: - </para> - <para> - Let's write rule for all nodes with primary node type 'nt:unstructured' where property 'rule' equal to "excerpt" string. For those nodes, we will exclude property "title" from high-lighting and set "text" property as highlightable. Indexing-configuration.xml must contain the next rule: - </para> - + <para> + Also, remember that we can make indexing rules, as in the example below: + </para> + <para> + Let's write rule for all nodes with primary node type 'nt:unstructured' where property 'rule' equal to "excerpt" string. For those nodes, we will exclude property "title" from high-lighting and set "text" property as highlightable. Indexing-configuration.xml must contain the next rule: + </para> + <programlisting language="XML" role="XML">&lt;index-rule nodeType="nt:unstructured" condition="@rule='excerpt'"&gt; &lt;property useInExcerpt="false"&gt;title&lt;/property&gt; &lt;property&gt;text&lt;/property&gt; &lt;/index-rule&gt;</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-High_lighting_Result_of_Fulltext_Search-Repository_structure"> - <title>Repository structure:</title> - <para> - We have single node with primary type 'nt:unstructured' - </para> - <itemizedlist> - <listitem> - <para> - document (nt:unstructured) - </para> - <itemizedlist> - <listitem> - <para> - rule = "excerpt" - </para> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-High_lighting_Result_of_Fulltext_Search-Repository_structure"> + <title>Repository structure:</title> + <para> + We have single node with primary type 'nt:unstructured' + </para> + <itemizedlist> + <listitem> + <para> + document (nt:unstructured) + </para> + <itemizedlist> + <listitem> + <para> + rule = "excerpt" + </para> - </listitem> - <listitem> - <para> - title = "eXoJCR" - </para> + </listitem> + <listitem> + <para> + title = "eXoJCR" + </para> - </listitem> - <listitem> - <para> - text = "eXo is a JCR implementation" - </para> + </listitem> + <listitem> + <para> + text = "eXo is a JCR implementation" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-High_lighting_Result_of_Fulltext_Search-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-High_lighting_Result_of_Fulltext_Search-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -90,10 +90,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -102,14 +102,14 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-High_lighting_Result_of_Fulltext_Search-Fetching_result"> - <title>Fetching result</title> - <para> - Now let's see on the result table: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-High_lighting_Result_of_Fulltext_Search-Fetching_result"> + <title>Fetching result</title> + <para> + Now let's see on the result table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -118,59 +118,59 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - rep:excerpt() - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is + </para> + <table> + <title>Table content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + rep:excerpt() + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - \&lt;div\&gt;\&lt;span\&gt;\&lt;strong\&gt;eXo\&lt;/strong\&gt; is a JCR \&lt;strong\&gt;implementation\&lt;/strong\&gt;\&lt;/span\&gt;\&lt;/div\&gt; - </entry> - <entry> - /testroot/node1 - </entry> - <entry> - 335 - </entry> + </thead> + <tbody> + <row> + <entry> + \&lt;div\&gt;\&lt;span\&gt;\&lt;strong\&gt;eXo\&lt;/strong\&gt; is a JCR \&lt;strong\&gt;implementation\&lt;/strong\&gt;\&lt;/span\&gt;\&lt;/div\&gt; + </entry> + <entry> + /testroot/node1 + </entry> + <entry> + 335 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> - <para> - As you see, words "eXo" and "implementation" is highlighted. - </para> - <para> - Also, we can get exactly "rep:excerpt" value: - </para> - + </table> + <para> + As you see, words "eXo" and "implementation" is highlighted. + </para> + <para> + Also, we can get exactly "rep:excerpt" value: + </para> + <programlisting language="Java" role="Java">RowIterator rows = result.getRows(); Value excerpt = rows.nextRow().getValue("rep:excerpt(.)"); // excerpt will be equal to "&lt;div&gt;&lt;span\&gt;&lt;strong&gt;eXo&lt;/strong&gt; is a JCR &lt;strong&gt;implementation&lt;/strong&gt;&lt;/span&gt;&lt;/div&gt;"</programlisting> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/ignore-accent-symbols.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/ignore-accent-symbols.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/ignore-accent-symbols.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,50 +4,50 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Ignoring_Accent_Symbols._New_Analyzer_Setting."> - <title>Ignoring Accent Symbols. New Analyzer Setting.</title> - <para> - In this example, we will create new Analyzer, set it in QueryHandler configuration, and make query to check it. - </para> - <para> - Standard analyzer does not normalize accents like é,è,à. So, a word like 'tréma' will be stored to index as 'tréma'. But if we want to normalize such symbols or not? We want to store 'tréma' word as 'trema'. - </para> - <para> - There is two ways of setting up new Analyzer (no matter standarts or our): - </para> - <itemizedlist> - <listitem> - <para> - The first way: Create descendant class of SearchIndex with new Analyzer (see <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration" />); - </para> + <title>Ignoring Accent Symbols. New Analyzer Setting.</title> + <para> + In this example, we will create new Analyzer, set it in QueryHandler configuration, and make query to check it. + </para> + <para> + Standard analyzer does not normalize accents like é,è,à. So, a word like 'tréma' will be stored to index as 'tréma'. But if we want to normalize such symbols or not? We want to store 'tréma' word as 'trema'. + </para> + <para> + There is two ways of setting up new Analyzer (no matter standarts or our): + </para> + <itemizedlist> + <listitem> + <para> + The first way: Create descendant class of SearchIndex with new Analyzer (see <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration" />); + </para> - </listitem> + </listitem> - </itemizedlist> - <para> - There is only one way - create new Analyzer (if there is no previously created and accepted for our needs) and set it in Search index. - </para> - <itemizedlist> - <listitem> - <para> - The second way: Register new Analyzer in QueryHandler configuration (this one accepted since 1.12 version); - </para> + </itemizedlist> + <para> + There is only one way - create new Analyzer (if there is no previously created and accepted for our needs) and set it in Search index. + </para> + <itemizedlist> + <listitem> + <para> + The second way: Register new Analyzer in QueryHandler configuration (this one accepted since 1.12 version); + </para> - </listitem> + </listitem> - </itemizedlist> - <para> - We will use the last one: - </para> - <itemizedlist> - <listitem> - <para> - Create new MyAnalyzer - </para> + </itemizedlist> + <para> + We will use the last one: + </para> + <itemizedlist> + <listitem> + <para> + Create new MyAnalyzer + </para> - </listitem> + </listitem> - </itemizedlist> - + </itemizedlist> + <programlisting language="Java" role="Java">public class MyAnalyzer extends Analyzer { @Override @@ -65,16 +65,16 @@ return result; } }</programlisting> - <itemizedlist> - <listitem> - <para> - Then, register new MyAnalyzer in configuration - </para> + <itemizedlist> + <listitem> + <para> + Then, register new MyAnalyzer in configuration + </para> - </listitem> + </listitem> - </itemizedlist> - + </itemizedlist> + <programlisting language="XML" role="XML">&lt;workspace name="ws"&gt; ... &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; @@ -85,50 +85,50 @@ &lt;/query-handler&gt; ... &lt;/workspace&gt;</programlisting> - <para> - After that, check it with query: - </para> - <para> - Find node with mixin type 'mix:title' where 'jcr:title' contains "tréma" and "naïve" strings. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Ignoring_Accent_Symbols._New_Analyzer_Setting.-Repository_structure"> - <title>Repository structure:</title> - <para> - Repository filled by nodes with mixin type 'mix:title' and different values of 'jcr:title' property. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - node1 (mix:title) jcr:title = "tréma blabla naïve" - </para> + <para> + After that, check it with query: + </para> + <para> + Find node with mixin type 'mix:title' where 'jcr:title' contains "tréma" and "naïve" strings. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Ignoring_Accent_Symbols._New_Analyzer_Setting.-Repository_structure"> + <title>Repository structure:</title> + <para> + Repository filled by nodes with mixin type 'mix:title' and different values of 'jcr:title' property. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + node1 (mix:title) jcr:title = "tréma blabla naïve" + </para> - </listitem> - <listitem> - <para> - node2 (mix:title) jcr:description = "trema come text naive" - </para> + </listitem> + <listitem> + <para> + node2 (mix:title) jcr:description = "trema come text naive" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Ignoring_Accent_Symbols._New_Analyzer_Setting.-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Ignoring_Accent_Symbols._New_Analyzer_Setting.-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -136,10 +136,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -148,27 +148,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Ignoring_Accent_Symbols._New_Analyzer_Setting.-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Ignoring_Accent_Symbols._New_Analyzer_Setting.-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "node1" and "node2". How is it possible? Remember that our MyAnalyzer transforms 'tréma' word to 'trema'. So node2 accepts our constraints to. - </para> - <para> - Also, we can get a table: - </para> - + <para> + NodeIterator will return "node1" and "node2". How is it possible? Remember that our MyAnalyzer transforms 'tréma' word to 'trema'. So node2 accepts our constraints to. + </para> + <para> + Also, we can get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -177,61 +177,61 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - cr:title - </entry> - <entry> - ... - </entry> - <entry> - cr:path - </entry> + <para> + Table content is + </para> + <table> + <title>Table content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + cr:title + </entry> + <entry> + ... + </entry> + <entry> + cr:path + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - trèma blabla naïve - </entry> - <entry> - ... - </entry> - <entry> - /node1 - </entry> + </thead> + <tbody> + <row> + <entry> + trèma blabla naïve + </entry> + <entry> + ... + </entry> + <entry> + /node1 + </entry> - </row> - <row> - <entry> - trema come text naive - </entry> - <entry> - ... - </entry> - <entry> - /node2 - </entry> + </row> + <row> + <entry> + trema come text naive + </entry> + <entry> + ... + </entry> + <entry> + /node2 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/like-constraint.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/like-constraint.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/like-constraint.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,60 +4,60 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-LIKE_Constraint"> - <title>LIKE Constraint</title> - <para> - Find all nodes with mixin type 'mix:title' and where the property 'jcr:title' starts with 'P'. - </para> - <note> - <para> - See also the article about "<xref linkend="sect-Reference_Guide_eXo_JCR_1.14-NOT_Constraint" />" - </para> + <title>LIKE Constraint</title> + <para> + Find all nodes with mixin type 'mix:title' and where the property 'jcr:title' starts with 'P'. + </para> + <note> + <para> + See also the article about "<xref linkend="sect-Reference_Guide_eXo_JCR_1.14-NOT_Constraint" />" + </para> - </note> - <section id="sect-Reference_Guide_eXo_JCR_1.14-LIKE_Constraint-Repository_structure"> - <title>Repository structure:</title> - <para> - The repository contains 3 mix:title nodes, where each jcr:title has a different value. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:title="Star wars" jcr:description="Dart rules!!" - </para> + </note> + <section id="sect-Reference_Guide_eXo_JCR_1.14-LIKE_Constraint-Repository_structure"> + <title>Repository structure:</title> + <para> + The repository contains 3 mix:title nodes, where each jcr:title has a different value. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:title="Star wars" jcr:description="Dart rules!!" + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:title="Prison break" jcr:description="Run, Forest, run ))" - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:title="Prison break" jcr:description="Run, Forest, run ))" + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:title="Panopticum" jcr:description="It's imagine film" - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:title="Panopticum" jcr:description="It's imagine film" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-LIKE_Constraint-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-LIKE_Constraint-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -65,10 +65,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -77,27 +77,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-LIKE_Constraint-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-LIKE_Constraint-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - The NodeIterator will return "document2" and "document3". - </para> - <para> - We can also get a table: - </para> - + <para> + The NodeIterator will return "document2" and "document3". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -106,71 +106,71 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - The table content is - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - jcr:description - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + The table content is + <table> + <title>Table content</title> + <tgroup cols="4"> + <thead> + <row> + <entry> + jcr:title + </entry> + <entry> + jcr:description + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - Prison break - </entry> - <entry> - Run, Forest, run )) - </entry> - <entry> - /document2 - </entry> - <entry> - 4713 - </entry> + </thead> + <tbody> + <row> + <entry> + Prison break + </entry> + <entry> + Run, Forest, run )) + </entry> + <entry> + /document2 + </entry> + <entry> + 4713 + </entry> - </row> - <row> - <entry> - Panopticum - </entry> - <entry> - It's imagine film - </entry> - <entry> - /document3 - </entry> - <entry> - 5150 - </entry> + </row> + <row> + <entry> + Panopticum + </entry> + <entry> + It's imagine film + </entry> + <entry> + /document3 + </entry> + <entry> + 5150 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/multivalue-property-comparison.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/multivalue-property-comparison.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/multivalue-property-comparison.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,54 +4,54 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Multivalue_Property_Comparison"> - <title>Multivalue Property Comparison</title> - <para> - Find all nodes with the primary type 'nt:unstructured' whose property 'multiprop' contains both values "one" and "two". - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Multivalue_Property_Comparison-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository contains nt:unstructured nodes with different 'multiprop' properties. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - node1 (nt:unstructured) multiprop = [ "one","two" ] - </para> + <title>Multivalue Property Comparison</title> + <para> + Find all nodes with the primary type 'nt:unstructured' whose property 'multiprop' contains both values "one" and "two". + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Multivalue_Property_Comparison-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository contains nt:unstructured nodes with different 'multiprop' properties. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + node1 (nt:unstructured) multiprop = [ "one","two" ] + </para> - </listitem> - <listitem> - <para> - node1 (nt:unstructured) multiprop = [ "one","two","three" ] - </para> + </listitem> + <listitem> + <para> + node1 (nt:unstructured) multiprop = [ "one","two","three" ] + </para> - </listitem> - <listitem> - <para> - node1 (nt:unstructured) multiprop = [ "one","five" ] - </para> + </listitem> + <listitem> + <para> + node1 (nt:unstructured) multiprop = [ "one","five" ] + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Multivalue_Property_Comparison-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Multivalue_Property_Comparison-Query_Execution"> + <title>Query Execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -59,10 +59,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -71,27 +71,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Multivalue_Property_Comparison-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Multivalue_Property_Comparison-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - The NodeIterator will return "node1" and "node2". - </para> - <para> - We can also get a table: - </para> - + <para> + The NodeIterator will return "node1" and "node2". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -100,62 +100,62 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - jcr:primarytyp - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + <table> + <title>Table content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + jcr:primarytyp + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - nt:unstructured - </entry> - <entry> - /node1 - </entry> - <entry> - 3806 - </entry> + </thead> + <tbody> + <row> + <entry> + nt:unstructured + </entry> + <entry> + /node1 + </entry> + <entry> + 3806 + </entry> - </row> - <row> - <entry> - nt:unstructured - </entry> - <entry> - /node2 - </entry> - <entry> - 3806 - </entry> + </row> + <row> + <entry> + nt:unstructured + </entry> + <entry> + /node2 + </entry> + <entry> + 3806 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/node-name-constraint.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/node-name-constraint.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/node-name-constraint.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,60 +4,60 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Node_Name_Constraint"> - <title>Node Name Constraint</title> - <para> - Find all nodes with primary type 'nt:file' whose node name is 'document'. The node name is accessible by a function called "fn:name()". - </para> - <note> - <para> - fn:name() can be used ONLY with an equal('=') comparison. - </para> + <title>Node Name Constraint</title> + <para> + Find all nodes with primary type 'nt:file' whose node name is 'document'. The node name is accessible by a function called "fn:name()". + </para> + <note> + <para> + fn:name() can be used ONLY with an equal('=') comparison. + </para> - </note> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Node_Name_Constraint-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository contains nt:file nodes with different names. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (nt:file) - </para> + </note> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Node_Name_Constraint-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository contains nt:file nodes with different names. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (nt:file) + </para> - </listitem> - <listitem> - <para> - file (nt:file) - </para> + </listitem> + <listitem> + <para> + file (nt:file) + </para> - </listitem> - <listitem> - <para> - somename (nt:file) - </para> + </listitem> + <listitem> + <para> + somename (nt:file) + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Node_Name_Constraint-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Node_Name_Constraint-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -65,10 +65,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -77,27 +77,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Node_Name_Constraint-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Node_Name_Constraint-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - The NodeIterator will return the node whose fn:name equals "document". - </para> - <para> - Also we can get a table: - </para> - + <para> + The NodeIterator will return the node whose fn:name equals "document". + </para> + <para> + Also we can get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -106,44 +106,44 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="2"> - <thead> - <row> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + <table> + <title>Table content</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - /document1 - </entry> - <entry> - 3575 - </entry> + </thead> + <tbody> + <row> + <entry> + /document1 + </entry> + <entry> + 3575 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/node-scope-index.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/node-scope-index.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/node-scope-index.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,14 +4,14 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Removing_Nodes_Property_From_Indexing_Scope"> - <title>Removing Nodes Property From Indexing Scope</title> - <para> - In this example, we will exclude some 'text' property of nt:unstructured node from indexing. And, therefore, node will not be found by the content of this property, even if it accepts all constraints. - </para> - <para> - First of all, add rules to indexing-configuration.xml: - </para> - + <title>Removing Nodes Property From Indexing Scope</title> + <para> + In this example, we will exclude some 'text' property of nt:unstructured node from indexing. And, therefore, node will not be found by the content of this property, even if it accepts all constraints. + </para> + <para> + First of all, add rules to indexing-configuration.xml: + </para> + <programlisting language="XML" role="XML">&lt;index-rule nodeType="nt:unstructured" condition="@rule='nsiTrue'"&gt; &lt;!-- default value for nodeScopeIndex is true --&gt; &lt;property&gt;text&lt;/property&gt; @@ -21,56 +21,56 @@ &lt;!-- do not include text in node scope index --&gt; &lt;property nodeScopeIndex="false"&gt;text&lt;/property&gt; &lt;/index-rule&gt;</programlisting> - <note> - <para> - See <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration" /> - </para> + <note> + <para> + See <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration" /> + </para> - </note> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Removing_Nodes_Property_From_Indexing_Scope-Repository_structure"> - <title>Repository structure:</title> - <para> - Repository contains nt:unstructured nodes, with same 'text'property and different 'rule' properties (even null) - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - node1 (nt:unstructured) rule="nsiTrue" text="The quick brown fox ..." - </para> + </note> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Removing_Nodes_Property_From_Indexing_Scope-Repository_structure"> + <title>Repository structure:</title> + <para> + Repository contains nt:unstructured nodes, with same 'text'property and different 'rule' properties (even null) + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + node1 (nt:unstructured) rule="nsiTrue" text="The quick brown fox ..." + </para> - </listitem> - <listitem> - <para> - node2 (nt:unstructured) rule="nsiFalse" text="The quick brown fox ..." - </para> + </listitem> + <listitem> + <para> + node2 (nt:unstructured) rule="nsiFalse" text="The quick brown fox ..." + </para> - </listitem> - <listitem> - <para> - node3 (nt:unstructured) text="The quick brown fox ..." // as you see this node not mentioned in indexing-configuration - </para> + </listitem> + <listitem> + <para> + node3 (nt:unstructured) text="The quick brown fox ..." // as you see this node not mentioned in indexing-configuration + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Removing_Nodes_Property_From_Indexing_Scope-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Removing_Nodes_Property_From_Indexing_Scope-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -78,10 +78,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -90,27 +90,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Removing_Nodes_Property_From_Indexing_Scope-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Removing_Nodes_Property_From_Indexing_Scope-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "node1" and "node3". Node2, as you see, is not in result set. - </para> - <para> - Also, we can get a table: - </para> - + <para> + NodeIterator will return "node1" and "node3". Node2, as you see, is not in result set. + </para> + <para> + Also, we can get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -119,61 +119,61 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - jcr:primarytype - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is + </para> + <table> + <title>Table content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + jcr:primarytype + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - nt:unstructured - </entry> - <entry> - /node1 - </entry> - <entry> - 3806 - </entry> + </thead> + <tbody> + <row> + <entry> + nt:unstructured + </entry> + <entry> + /node1 + </entry> + <entry> + 3806 + </entry> - </row> - <row> - <entry> - nt:unstructured - </entry> - <entry> - /node3 - </entry> - <entry> - 3806 - </entry> + </row> + <row> + <entry> + nt:unstructured + </entry> + <entry> + /node3 + </entry> + <entry> + 3806 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/not-constraint.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/not-constraint.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/not-constraint.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,54 +4,54 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-NOT_Constraint"> - <title>NOT Constraint</title> - <para> - Find all nodes with a mixin type 'mix:title' and where the property 'jcr:title' does NOT start with a 'P' symbol - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-NOT_Constraint-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository contains a mix:title nodes, where the jcr:title has different values. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:title="Star wars" jcr:description="Dart rules!!" - </para> + <title>NOT Constraint</title> + <para> + Find all nodes with a mixin type 'mix:title' and where the property 'jcr:title' does NOT start with a 'P' symbol + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-NOT_Constraint-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository contains a mix:title nodes, where the jcr:title has different values. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:title="Star wars" jcr:description="Dart rules!!" + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:title="Prison break" jcr:description="Run, Forest, run ))" - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:title="Prison break" jcr:description="Run, Forest, run ))" + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:title="Panopticum" jcr:description="It's imagine film" - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:title="Panopticum" jcr:description="It's imagine film" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-NOT_Constraint-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-NOT_Constraint-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -59,10 +59,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -71,27 +71,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-NOT_Constraint-Fetching_the_result"> - <title>Fetching the result</title> - <para> - Let's get the nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-NOT_Constraint-Fetching_the_result"> + <title>Fetching the result</title> + <para> + Let's get the nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "document1". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "document1". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -100,56 +100,56 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_result-Table_content"> - <title>Table content</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - jcr:description - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is + <table> + <title>Table content</title> + <tgroup cols="4"> + <thead> + <row> + <entry> + jcr:title + </entry> + <entry> + jcr:description + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - Star wars - </entry> - <entry> - Dart rules!! - </entry> - <entry> - /document1 - </entry> - <entry> - 4713 - </entry> + </thead> + <tbody> + <row> + <entry> + Star wars + </entry> + <entry> + Dart rules!! + </entry> + <entry> + /document1 + </entry> + <entry> + 4713 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/or-constraint.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/or-constraint.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/or-constraint.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,57 +4,57 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-OR_Constraint"> - <title>OR Constraint</title> - <para> - Find all documents whose title is 'Cinderella' or whose description is 'novel'. - </para> - <para> - How does it sound in jcr terms? - Find all nodes with a mixin type 'mix:title' whose property 'jcr:title' equals "Cinderella" or whose "jcr:description" property value is "novel". - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-OR_Constraint-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository contains mix:title nodes, where jcr:title and jcr:description have different values. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:title="War and peace" jcr:description="novel" - </para> + <title>OR Constraint</title> + <para> + Find all documents whose title is 'Cinderella' or whose description is 'novel'. + </para> + <para> + How does it sound in jcr terms? - Find all nodes with a mixin type 'mix:title' whose property 'jcr:title' equals "Cinderella" or whose "jcr:description" property value is "novel". + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-OR_Constraint-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository contains mix:title nodes, where jcr:title and jcr:description have different values. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:title="War and peace" jcr:description="novel" + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:title="Cinderella" jcr:description="fairytale" - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:title="Cinderella" jcr:description="fairytale" + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:title="Puss in Boots" jcr:description="fairytale" - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:title="Puss in Boots" jcr:description="fairytale" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-OR_Constraint-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-OR_Constraint-Query_Execution"> + <title>Query Execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -62,10 +62,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -74,27 +74,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-OR_Constraint-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-OR_Constraint-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "document1" and "document2". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return "document1" and "document2". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -103,71 +103,71 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - jcr:description - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + <table> + <title>Table content</title> + <tgroup cols="4"> + <thead> + <row> + <entry> + jcr:title + </entry> + <entry> + jcr:description + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - War and peace - </entry> - <entry> - novel - </entry> - <entry> - /document1 - </entry> - <entry> - 3806 - </entry> + </thead> + <tbody> + <row> + <entry> + War and peace + </entry> + <entry> + novel + </entry> + <entry> + /document1 + </entry> + <entry> + 3806 + </entry> - </row> - <row> - <entry> - Cinderella - </entry> - <entry> - fairytale - </entry> - <entry> - /document2 - </entry> - <entry> - 3806 - </entry> + </row> + <row> + <entry> + Cinderella + </entry> + <entry> + fairytale + </entry> + <entry> + /document2 + </entry> + <entry> + 3806 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-descendant.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-descendant.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-descendant.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,129 +4,129 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Descendant_Nodes_Property_XPath_only"> - <title>Ordering by Descendant Nodes Property (XPath only)</title> - <para> - Find all nodes with the primary type 'nt:unstructured' and sort them by the property value of descendant nodes with the relative path '/a/b'. - </para> - <note> - <para> - This ORDER BY construction only works in XPath! - </para> + <title>Ordering by Descendant Nodes Property (XPath only)</title> + <para> + Find all nodes with the primary type 'nt:unstructured' and sort them by the property value of descendant nodes with the relative path '/a/b'. + </para> + <note> + <para> + This ORDER BY construction only works in XPath! + </para> - </note> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Descendant_Nodes_Property_XPath_only-Repository_structure"> - <title>Repository structure:</title> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - node1 (nt:unstructured) - </para> - <itemizedlist> - <listitem> - <para> - a (nt:unstructured) - </para> - <itemizedlist> - <listitem> - <para> - b (nt:unstructured) - </para> + </note> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Descendant_Nodes_Property_XPath_only-Repository_structure"> + <title>Repository structure:</title> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + node1 (nt:unstructured) + </para> + <itemizedlist> + <listitem> + <para> + a (nt:unstructured) + </para> + <itemizedlist> + <listitem> + <para> + b (nt:unstructured) + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> - <listitem> - <para> - node2 (nt:unstructured) - </para> - <itemizedlist> - <listitem> - <para> - a (nt:unstructured) - </para> - <itemizedlist> - <listitem> - <para> - b (nt:unstructured) - </para> - <itemizedlist> - <listitem> - <para> - c (nt:unstructured) prop = "a" - </para> + </listitem> + <listitem> + <para> + node2 (nt:unstructured) + </para> + <itemizedlist> + <listitem> + <para> + a (nt:unstructured) + </para> + <itemizedlist> + <listitem> + <para> + b (nt:unstructured) + </para> + <itemizedlist> + <listitem> + <para> + c (nt:unstructured) prop = "a" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> - <listitem> - <para> - node3 (nt:unstructured) - </para> - <itemizedlist> - <listitem> - <para> - a (nt:unstructured) - </para> - <itemizedlist> - <listitem> - <para> - b (nt:unstructured) - </para> - <itemizedlist> - <listitem> - <para> - c (nt:unstructured) prop = "b" - </para> + </listitem> + <listitem> + <para> + node3 (nt:unstructured) + </para> + <itemizedlist> + <listitem> + <para> + a (nt:unstructured) + </para> + <itemizedlist> + <listitem> + <para> + b (nt:unstructured) + </para> + <itemizedlist> + <listitem> + <para> + c (nt:unstructured) prop = "b" + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Descendant_Nodes_Property_XPath_only-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Descendant_Nodes_Property_XPath_only-Query_Execution"> + <title>Query Execution</title> + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -135,27 +135,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Descendant_Nodes_Property_XPath_only-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Descendant_Nodes_Property_XPath_only-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return nodes in the following order - "node3","node2" and "node1". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return nodes in the following order - "node3","node2" and "node1". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -164,73 +164,73 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - jcr:primaryType - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + </para> + <table> + <title>Table content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + jcr:primaryType + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - nt:unstructured - </entry> - <entry> - /testroot/node3 - </entry> - <entry> - 1000 - </entry> + </thead> + <tbody> + <row> + <entry> + nt:unstructured + </entry> + <entry> + /testroot/node3 + </entry> + <entry> + 1000 + </entry> - </row> - <row> - <entry> - nt:unstructured - </entry> - <entry> - /testroot/node2 - </entry> - <entry> - 1000 - </entry> + </row> + <row> + <entry> + nt:unstructured + </entry> + <entry> + /testroot/node2 + </entry> + <entry> + 1000 + </entry> - </row> - <row> - <entry> - nt:unstructured - </entry> - <entry> - /testroot/node1 - </entry> - <entry> - 1000 - </entry> + </row> + <row> + <entry> + nt:unstructured + </entry> + <entry> + /testroot/node1 + </entry> + <entry> + 1000 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-property.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-property.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-property.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,54 +4,54 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Sorting_Nodes_by_Property"> - <title>Sorting Nodes by Property</title> - <para> - Select all nodes with the mixin type ''mix:title' and order them by the 'prop_pagecount' property. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Sorting_Nodes_by_Property-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository contains several mix:title nodes, where prop_pagecount has different values. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:title="War and peace" jcr:description="roman" prop_pagecount=4 - </para> + <title>Sorting Nodes by Property</title> + <para> + Select all nodes with the mixin type ''mix:title' and order them by the 'prop_pagecount' property. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Sorting_Nodes_by_Property-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository contains several mix:title nodes, where prop_pagecount has different values. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:title="War and peace" jcr:description="roman" prop_pagecount=4 + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:title="Cinderella" jcr:description="fairytale" prop_pagecount=7 - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:title="Cinderella" jcr:description="fairytale" prop_pagecount=7 + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:title="Puss in Boots" jcr:description="fairytale" prop_pagecount=1 - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:title="Puss in Boots" jcr:description="fairytale" prop_pagecount=1 + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Sorting_Nodes_by_Property-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Sorting_Nodes_by_Property-Query_Execution"> + <title>Query Execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -59,10 +59,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -71,27 +71,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Sorting_Nodes_by_Property-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Sorting_Nodes_by_Property-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - The NodeIterator will return nodes in the following order "document3", "document1", "document2". - </para> - <para> - We can also get a table: - </para> - + <para> + The NodeIterator will return nodes in the following order "document3", "document1", "document2". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -100,97 +100,97 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="5"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - jcr:description - </entry> - <entry> - prop_pagecount - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + </para> + <table> + <title>Table content</title> + <tgroup cols="5"> + <thead> + <row> + <entry> + jcr:title + </entry> + <entry> + jcr:description + </entry> + <entry> + prop_pagecount + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - Puss in Boots - </entry> - <entry> - fairytale - </entry> - <entry> - 1 - </entry> - <entry> - /document3 - </entry> - <entry> - 1405 - </entry> + </thead> + <tbody> + <row> + <entry> + Puss in Boots + </entry> + <entry> + fairytale + </entry> + <entry> + 1 + </entry> + <entry> + /document3 + </entry> + <entry> + 1405 + </entry> - </row> - <row> - <entry> - War and peace - </entry> - <entry> - roman - </entry> - <entry> - 4 - </entry> - <entry> - /document1 - </entry> - <entry> - 1405 - </entry> + </row> + <row> + <entry> + War and peace + </entry> + <entry> + roman + </entry> + <entry> + 4 + </entry> + <entry> + /document1 + </entry> + <entry> + 1405 + </entry> - </row> - <row> - <entry> - Cinderella - </entry> - <entry> - fairytale - </entry> - <entry> - 7 - </entry> - <entry> - /document2 - </entry> - <entry> - 1405 - </entry> + </row> + <row> + <entry> + Cinderella + </entry> + <entry> + fairytale + </entry> + <entry> + 7 + </entry> + <entry> + /document2 + </entry> + <entry> + 1405 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-score.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-score.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/order-by-score.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,78 +4,78 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Score"> - <title>Ordering by Score</title> - <para> - Select all nodes with the mixin type 'mix:title' containing any word from the set {'brown','fox','jumps'}. Then, sort result by the score in ascending node. This way nodes that match better the query statement are ordered at the last positions in the result list. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Score-Info"> - <title>Info</title> - <para> - SQL and XPath queries support both score constructions jcr:score and jcr:score() - </para> - + <title>Ordering by Score</title> + <para> + Select all nodes with the mixin type 'mix:title' containing any word from the set {'brown','fox','jumps'}. Then, sort result by the score in ascending node. This way nodes that match better the query statement are ordered at the last positions in the result list. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Score-Info"> + <title>Info</title> + <para> + SQL and XPath queries support both score constructions jcr:score and jcr:score() + </para> + <programlisting>SELECT * FROM nt:base ORDER BY jcr:score [ASC|DESC] SELECT * FROM nt:base ORDER BY jcr:score()[ASC|DESC] //element(*,nt:base) order by jcr:score() [descending] //element(*,nt:base) order by @jcr:score [descending]</programlisting> - <para> - Do not use "ascending" combined with jcr:score in XPath. The following XPath statement may throw an exception: - </para> - + <para> + Do not use "ascending" combined with jcr:score in XPath. The following XPath statement may throw an exception: + </para> + <programlisting>... order by jcr:score() ascending</programlisting> - <para> - Do not set any ordering specifier - ascending is default: - </para> - + <para> + Do not set any ordering specifier - ascending is default: + </para> + <programlisting>... order by jcr:score()</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Score-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository contains mix:title nodes, where the jcr:description has different values. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:description="The quick brown fox jumps over the lazy dog." - </para> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Score-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository contains mix:title nodes, where the jcr:description has different values. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:description="The quick brown fox jumps over the lazy dog." + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:description="The brown fox lives in the forest." - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:description="The brown fox lives in the forest." + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:description="The fox is a nice animal." - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:description="The fox is a nice animal." + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Score-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Score-Query_Execution"> + <title>Query Execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -83,10 +83,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -95,27 +95,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Score-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Ordering_by_Score-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + Let's get nodes + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return nodes in the following order: "document3", "document2", "document1". - </para> - <para> - We can also get a table: - </para> - + <para> + NodeIterator will return nodes in the following order: "document3", "document2", "document1". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -124,85 +124,85 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - jcr:description - </entry> - <entry> - ... - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + </para> + <table> + <title>Table content</title> + <tgroup cols="4"> + <thead> + <row> + <entry> + jcr:description + </entry> + <entry> + ... + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - The fox is a nice animal. - </entry> - <entry> - ... - </entry> - <entry> - /document3 - </entry> - <entry> - 2512 - </entry> + </thead> + <tbody> + <row> + <entry> + The fox is a nice animal. + </entry> + <entry> + ... + </entry> + <entry> + /document3 + </entry> + <entry> + 2512 + </entry> - </row> - <row> - <entry> - The brown fox lives in the forest. - </entry> - <entry> - ... - </entry> - <entry> - /document2 - </entry> - <entry> - 3595 - </entry> + </row> + <row> + <entry> + The brown fox lives in the forest. + </entry> + <entry> + ... + </entry> + <entry> + /document2 + </entry> + <entry> + 3595 + </entry> - </row> - <row> - <entry> - The quick brown fox jumps over the lazy dog. - </entry> - <entry> - ... - </entry> - <entry> - /document1 - </entry> - <entry> - 5017 - </entry> + </row> + <row> + <entry> + The quick brown fox jumps over the lazy dog. + </entry> + <entry> + ... + </entry> + <entry> + /document1 + </entry> + <entry> + 5017 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/property-comparison.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/property-comparison.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/property-comparison.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,54 +4,54 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Comparison"> - <title>Property Comparison</title> - <para> - Find all nodes with mixin type 'mix:title' where the prop_pagecount property contains a value less than 90. Only select the title of each node. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Comparison-Repository_structure"> - <title>Repository structure:</title> - <para> - Repository contains several mix:title nodes, where each prop_pagecount contains a different value. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:title="War and peace" prop_pagecount=1000 - </para> + <title>Property Comparison</title> + <para> + Find all nodes with mixin type 'mix:title' where the prop_pagecount property contains a value less than 90. Only select the title of each node. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Comparison-Repository_structure"> + <title>Repository structure:</title> + <para> + Repository contains several mix:title nodes, where each prop_pagecount contains a different value. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + document1 (mix:title) jcr:title="War and peace" prop_pagecount=1000 + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:title="Cinderella" prop_pagecount=100 - </para> + </listitem> + <listitem> + <para> + document2 (mix:title) jcr:title="Cinderella" prop_pagecount=100 + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:title="Puss in Boots" prop_pagecount=60 - </para> + </listitem> + <listitem> + <para> + document3 (mix:title) jcr:title="Puss in Boots" prop_pagecount=60 + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Comparison-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Comparison-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -59,10 +59,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -71,27 +71,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Comparison-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Comparison-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - The NodeIterator will return "document3". - </para> - <para> - We can also get a table: - </para> - + <para> + The NodeIterator will return "document3". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -100,50 +100,50 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - The table content is - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_Content"> - <title>Table Content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + The table content is + <table> + <title>Table Content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + jcr:title + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - Puss in Boots - </entry> - <entry> - /document3 - </entry> - <entry> - 1725 - </entry> + </thead> + <tbody> + <row> + <entry> + Puss in Boots + </entry> + <entry> + /document3 + </entry> + <entry> + 1725 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/property-existance-constraint.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/property-existance-constraint.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/property-existance-constraint.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,54 +4,53 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Existence_Constraint"> - <title>Property Existence Constraint</title> - <para> - Find all nodes with a mixin type 'mix:title' where the property 'jcr:description' does not exist (is null). - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Existence_Constraint-Repository_Structure"> - <title>Repository Structure</title> - <para> - The repository contains mix:title nodes, in one of these nodes the jcr:description property is null. - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - document1 (mix:title) jcr:title="Star wars" jcr:description="Dart rules!!" - </para> + <title>Property Existence Constraint</title> + <para> + Find all nodes with a mixin type '<literal>mix:title</literal>' where the property '<parameter>jcr:description</parameter>' does not exist (is null). + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Existence_Constraint-Repository_Structure"> + <title>Repository Structure</title> + <para> + The repository contains <literal>mix:title</literal> nodes, in one of these nodes the <literal>jcr:description</literal> property is null. + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + <filename>document1</filename> (<literal>mix:title</literal>) <literal>jcr:title</literal>="Star Wars" <literal>jcr:description</literal>="Darth rules!!" + </para> - </listitem> - <listitem> - <para> - document2 (mix:title) jcr:title="Prison break" jcr:description="Run, Forest, run ))" - </para> + </listitem> + <listitem> + <para> + <filename>document2</filename> (<literal>mix:title</literal>) <literal>jcr:title</literal>="Prison Break" <literal>jcr:description</literal>="Run, Forest, run ))" + </para> - </listitem> - <listitem> - <para> - document3 (mix:title) jcr:title="Titanic" // The description property does not exist. This is the node we wish to find. - </para> + </listitem> + <listitem> + <para> + <filename>document3</filename> (<literal>mix:title</literal>) <literal>jcr:title</literal>="Titanic" // The description property does not exist. This is the node we wish to find. + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Existence_Constraint-Query_Execution"> - <title>Query Execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Existence_Constraint-Query_Execution"> + <title>Query Execution</title> + +<example> + <title>SQL</title> <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -59,10 +58,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - +</example> + +<example> + <title>XPath</title> <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -70,28 +69,29 @@ Query query = queryManager.createQuery(xpathStatement, Query.XPATH); // execute query and fetch result QueryResult result = query.execute();</programlisting> +</example> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Existence_Constraint-Fetching_the_Result"> - <title>Fetching the Result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Property_Existence_Constraint-Fetching_the_Result"> + <title>Fetching the Result</title> + <para> + To fetch the nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "document3". - </para> - <para> - We can also get a table: - </para> - + <para> + <literal>NodeIterator</literal> will return "<filename>document3</filename>". + </para> + <para> + We can also get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -100,56 +100,56 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_the_Result-Table_content"> - <title>Table content</title> - <tgroup cols="4"> - <thead> - <row> - <entry> - jcr:title - </entry> - <entry> - jcr:description - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + <table> + <title>Table content</title> + <tgroup cols="4"> + <thead> + <row> + <entry> + <literal>jcr:title</literal> + </entry> + <entry> + <literal>jcr:description</literal> + </entry> + <entry> + <literal>jcr:path</literal> + </entry> + <entry> + <literal>jcr:score</literal> + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - Titanic - </entry> - <entry> - null - </entry> - <entry> - /document3 - </entry> - <entry> - 1947 - </entry> + </thead> + <tbody> + <row> + <entry> + Titanic + </entry> + <entry> + null + </entry> + <entry> + /document3 + </entry> + <entry> + 1947 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </para> + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/regexp-indexing-rule.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/regexp-indexing-rule.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/searching/regexp-indexing-rule.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,67 +4,67 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-Regular_Expression_as_Property_Name_in_Indexing_Rules"> - <title>Regular Expression as Property Name in Indexing Rules</title> - <para> - In this example, we want to configure indexing in the next way. All properties of nt:unstructured nodes must be excluded from search, except properties whoes names ends with 'Text' string. First of all, add rules to indexing-configuration.xml: - </para> - + <title>Regular Expression as Property Name in Indexing Rules</title> + <para> + In this example, we want to configure indexing in the next way. All properties of nt:unstructured nodes must be excluded from search, except properties whoes names ends with 'Text' string. First of all, add rules to indexing-configuration.xml: + </para> + <programlisting language="XML" role="XML">&lt;index-rule nodeType="nt:unstructured""&gt; &lt;property isRegexp="true"&gt;.*Text&lt;/property&gt; &lt;/index-rule&gt;</programlisting> - <note> - <para> - See <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration" /> - </para> + <note> + <para> + See <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Search_Configuration" /> + </para> - </note> - <para> - Now, let's check this rule with simple query - select all nodes with primary type 'nt:unstructured' and containing 'quick' string (fulltext search by full node). - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Regular_Expression_as_Property_Name_in_Indexing_Rules-Repository_structure"> - <title>Repository structure:</title> - <para> - Repository contains nt:unstructured nodes, with different 'text'-like named properties - </para> - <itemizedlist> - <listitem> - <para> - root - </para> - <itemizedlist> - <listitem> - <para> - node1 (nt:unstructured) Text="The quick brown fox ..." - </para> + </note> + <para> + Now, let's check this rule with simple query - select all nodes with primary type 'nt:unstructured' and containing 'quick' string (fulltext search by full node). + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Regular_Expression_as_Property_Name_in_Indexing_Rules-Repository_structure"> + <title>Repository structure:</title> + <para> + Repository contains nt:unstructured nodes, with different 'text'-like named properties + </para> + <itemizedlist> + <listitem> + <para> + root + </para> + <itemizedlist> + <listitem> + <para> + node1 (nt:unstructured) Text="The quick brown fox ..." + </para> - </listitem> - <listitem> - <para> - node2 (nt:unstructured) OtherText="The quick brown fox ..." - </para> + </listitem> + <listitem> + <para> + node2 (nt:unstructured) OtherText="The quick brown fox ..." + </para> - </listitem> - <listitem> - <para> - node3 (nt:unstructured) Textle="The quick brown fox ..." - </para> + </listitem> + <listitem> + <para> + node3 (nt:unstructured) Textle="The quick brown fox ..." + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Regular_Expression_as_Property_Name_in_Indexing_Rules-Query_execution"> - <title>Query execution</title> - <para> - <emphasis role="bold">SQL</emphasis> - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Regular_Expression_as_Property_Name_in_Indexing_Rules-Query_execution"> + <title>Query execution</title> + <para> + <emphasis role="bold">SQL</emphasis> + </para> + <programlisting language="Java" role="Java">// make SQL query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -72,10 +72,10 @@ Query query = queryManager.createQuery(sqlStatement, Query.SQL); // execute query and fetch result QueryResult result = query.execute();</programlisting> - <para> - <emphasis role="bold">XPath</emphasis> - </para> - + <para> + <emphasis role="bold">XPath</emphasis> + </para> + <programlisting language="Java" role="Java">// make XPath query QueryManager queryManager = workspace.getQueryManager(); // create query @@ -84,27 +84,27 @@ // execute query and fetch result QueryResult result = query.execute();</programlisting> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Regular_Expression_as_Property_Name_in_Indexing_Rules-Fetching_result"> - <title>Fetching result</title> - <para> - Let's get nodes: - </para> - + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Regular_Expression_as_Property_Name_in_Indexing_Rules-Fetching_result"> + <title>Fetching result</title> + <para> + Let's get nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes(); if(it.hasNext()) { Node findedNode = it.nextNode(); }</programlisting> - <para> - NodeIterator will return "node1" and "node2". "node3", as you see, is not in result set. - </para> - <para> - Also, we can get a table: - </para> - + <para> + NodeIterator will return "node1" and "node2". "node3", as you see, is not in result set. + </para> + <para> + Also, we can get a table: + </para> + <programlisting language="Java" role="Java">String[] columnNames = result.getColumnNames(); RowIterator rit = result.getRows(); while (rit.hasNext()) @@ -113,61 +113,61 @@ // get values of the row Value[] values = row.getValues(); }</programlisting> - <para> - Table content is: - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Fetching_result-Table_content"> - <title>Table content</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - jcr:primarytype - </entry> - <entry> - jcr:path - </entry> - <entry> - jcr:score - </entry> + <para> + Table content is: + </para> + <table> + <title>Table content</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + jcr:primarytype + </entry> + <entry> + jcr:path + </entry> + <entry> + jcr:score + </entry> - </row> + </row> - </thead> - <tbody> - <row> - <entry> - nt:unstructured - </entry> - <entry> - /node1 - </entry> - <entry> - 3806 - </entry> + </thead> + <tbody> + <row> + <entry> + nt:unstructured + </entry> + <entry> + /node1 + </entry> + <entry> + 3806 + </entry> - </row> - <row> - <entry> - nt:unstructured - </entry> - <entry> - /node2 - </entry> - <entry> - 3806 - </entry> + </row> + <row> + <entry> + nt:unstructured + </entry> + <entry> + /node2 + </entry> + <entry> + 3806 + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/statistics.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/statistics.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr/statistics.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,280 +4,292 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-eXo_JCR_statistics"> - <title>eXo JCR statistics</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-eXo_JCR_statistics-Statistics_on_the_Database_Access_Layer"> - <title>Statistics on the Database Access Layer</title> - <para> - In order to have a better idea of the time spent into the database access layer, it can be interesting to get some statistics on that part of the code, knowing that most of the time spent into eXo JCR is mainly the database access. This statistics will then allow you to identify without using any profiler what is normally slow in this layer, which could help to fix the problem quickly. - </para> - <para> - In case you use <envar>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</envar> or <envar>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</envar> as <envar>WorkspaceDataContainer</envar>, you can get statistics on the time spent into the database access layer. The database access layer (in eXo JCR) is represented by the methods of the interface <envar>org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</envar>, so for all the methods defined in this interface, we can have the following figures: - </para> - <itemizedlist> - <listitem> - <para> - The minimum time spent into the method. - </para> + <title>eXo JCR statistics</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-eXo_JCR_statistics-Statistics_on_the_Database_Access_Layer"> + <title>Statistics on the Database Access Layer</title> + <para> + In order to have a better idea of the time spent into the database access layer, it can be interesting to get some statistics on that part of the code, knowing that most of the time spent into eXo JCR is mainly the database access. + </para> + <para> + These statistics will then allow you to identify, without using any profiler, what is abnormally slow in this layer which could help diagnose, and fix, a problem. + </para> + <para> + If you use <envar>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</envar> or <envar>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</envar> as <envar>WorkspaceDataContainer</envar>, you can get statistics on the time spent into the database access layer. + </para> + <para> + The database access layer (in eXo JCR) is represented by the methods of the interface <envar>org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</envar>, so for all the methods defined in this interface, we can have the following figures: + </para> + <itemizedlist> + <listitem> + <para> + The minimum time spent into the method. + </para> - </listitem> - <listitem> - <para> - The maximum time spent into the method. - </para> + </listitem> + <listitem> + <para> + The maximum time spent into the method. + </para> - </listitem> - <listitem> - <para> - The average time spent into the method. - </para> + </listitem> + <listitem> + <para> + The average time spent into the method. + </para> - </listitem> - <listitem> - <para> - The total amount of time spent into the method. - </para> + </listitem> + <listitem> + <para> + The total amount of time spent into the method. + </para> - </listitem> - <listitem> - <para> - The total amount of time the method has been called. - </para> + </listitem> + <listitem> + <para> + The total amount of time the method has been called. + </para> - </listitem> + </listitem> - </itemizedlist> - <para> - Those figures are also available globaly for all the methods which gives us the global behavior of this layer. - </para> - <para> - If you want to enable the statistics, you just need to set the JVM parameter called <emphasis>JDBCWorkspaceDataContainer.statistics.enabled</emphasis> to <emphasis>true</emphasis>. The corresponding CSV file is <emphasis>StatisticsJDBCStorageConnection-${creation-timestamp}.csv</emphasis> for more details about how the csv files are managed, please refer to the section dedicated to the statistics manager. - </para> - <para> - The format of each column header is ${method-alias}-${metric-alias}. The metric alias are described in the statistics manager section. - </para> - <para> - The name of the category of statistics corresponding to these statistics is <emphasis>JDBCStorageConnection</emphasis>, this name is mostly needed to access to the statistics through JMX. - </para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Statistics_on_the_Database_Access_Layer-Method_Alias"> - <title>Method Alias</title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - global - </entry> - <entry> - This is the alias for all the methods. - </entry> + </itemizedlist> + <para> + Those figures are also available globaly for all the methods which gives us the global behavior of this layer. + </para> + <para> + If you want to enable the statistics, you just need to set the JVM parameter called <parameter>JDBCWorkspaceDataContainer.statistics.enabled</parameter> to <emphasis>true</emphasis>. The corresponding CSV file is <filename>StatisticsJDBCStorageConnection-${creation-timestamp}.csv</filename> for more details about how the csv files are managed, please refer to the section dedicated to the statistics manager. + </para> + <para> + The format of each column header is <replaceable>${method-alias}</replaceable>-<replaceable>${metric-alias}</replaceable>. The metric alias are described in the statistics manager section. + </para> + <para> + The name of the category of statistics corresponding to these statistics is <literal>JDBCStorageConnection</literal>, this name is mostly needed to access to the statistics through JMX. + </para> + <table id="tabl-Reference_Guide_eXo_JCR_1.14-Statistics_on_the_Database_Access_Layer-Method_Alias"> + <title>Method Alias</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> + global + </entry> + <entry> + This is the alias for all the methods. + </entry> - </row> - <row> - <entry> - getItemDataById - </entry> - <entry> - This is the alias for the method <emphasis>getItemData(String identifier).</emphasis> - </entry> + </row> + <row> + <entry> + getItemDataById + </entry> + <entry> + This is the alias for the method <emphasis>getItemData(String identifier).</emphasis> + </entry> - </row> - <row> - <entry> - getItemDataByNodeDataNQPathEntry - </entry> - <entry> - This is the alias for the method <emphasis>getItemData(NodeData parentData, QPathEntry name).</emphasis> - </entry> + </row> + <row> + <entry> + getItemDataByNodeDataNQPathEntry + </entry> + <entry> + This is the alias for the method <emphasis>getItemData(NodeData parentData, QPathEntry name).</emphasis> + </entry> - </row> - <row> - <entry> - getChildNodesData - </entry> - <entry> - This is the alias for the method <emphasis>getChildNodesData(NodeData parent).</emphasis> - </entry> + </row> + <row> + <entry> + getChildNodesData + </entry> + <entry> + This is the alias for the method <emphasis>getChildNodesData(NodeData parent).</emphasis> + </entry> - </row> - <row> - <entry> - getChildNodesCount - </entry> - <entry> - This is the alias for the method <emphasis>getChildNodesCount(NodeData parent).</emphasis> - </entry> + </row> + <row> + <entry> + getChildNodesCount + </entry> + <entry> + This is the alias for the method <emphasis>getChildNodesCount(NodeData parent).</emphasis> + </entry> - </row> - <row> - <entry> - getChildPropertiesData - </entry> - <entry> - This is the alias for the method <emphasis>getChildPropertiesData(NodeData parent).</emphasis> - </entry> + </row> + <row> + <entry> + getChildPropertiesData + </entry> + <entry> + This is the alias for the method <emphasis>getChildPropertiesData(NodeData parent).</emphasis> + </entry> - </row> - <row> - <entry> - listChildPropertiesData - </entry> - <entry> - This is the alias for the method <emphasis>listChildPropertiesData(NodeData parent).</emphasis> - </entry> + </row> + <row> + <entry> + listChildPropertiesData + </entry> + <entry> + This is the alias for the method <emphasis>listChildPropertiesData(NodeData parent).</emphasis> + </entry> - </row> - <row> - <entry> - getReferencesData - </entry> - <entry> - This is the alias for the method <emphasis>getReferencesData(String nodeIdentifier).</emphasis> - </entry> + </row> + <row> + <entry> + getReferencesData + </entry> + <entry> + This is the alias for the method <emphasis>getReferencesData(String nodeIdentifier).</emphasis> + </entry> - </row> - <row> - <entry> - commit - </entry> - <entry> - This is the alias for the method <emphasis>commit().</emphasis> - </entry> + </row> + <row> + <entry> + commit + </entry> + <entry> + This is the alias for the method <emphasis>commit().</emphasis> + </entry> - </row> - <row> - <entry> - addNodeData - </entry> - <entry> - This is the alias for the method <emphasis>add(NodeData data).</emphasis> - </entry> + </row> + <row> + <entry> + addNodeData + </entry> + <entry> + This is the alias for the method <emphasis>add(NodeData data).</emphasis> + </entry> - </row> - <row> - <entry> - addPropertyData - </entry> - <entry> - This is the alias for the method <emphasis>add(PropertyData data).</emphasis> - </entry> + </row> + <row> + <entry> + addPropertyData + </entry> + <entry> + This is the alias for the method <emphasis>add(PropertyData data).</emphasis> + </entry> - </row> - <row> - <entry> - updateNodeData - </entry> - <entry> - This is the alias for the method <emphasis>update(NodeData data).</emphasis> - </entry> + </row> + <row> + <entry> + updateNodeData + </entry> + <entry> + This is the alias for the method <emphasis>update(NodeData data).</emphasis> + </entry> - </row> - <row> - <entry> - updatePropertyData - </entry> - <entry> - This is the alias for the method <emphasis>update(PropertyData data).</emphasis> - </entry> + </row> + <row> + <entry> + updatePropertyData + </entry> + <entry> + This is the alias for the method <emphasis>update(PropertyData data).</emphasis> + </entry> - </row> - <row> - <entry> - deleteNodeData - </entry> - <entry> - This is the alias for the method <emphasis>delete(NodeData data).</emphasis> - </entry> + </row> + <row> + <entry> + deleteNodeData + </entry> + <entry> + This is the alias for the method <emphasis>delete(NodeData data).</emphasis> + </entry> - </row> - <row> - <entry> - deletePropertyData - </entry> - <entry> - This is the alias for the method <emphasis>delete(PropertyData data).</emphasis> - </entry> + </row> + <row> + <entry> + deletePropertyData + </entry> + <entry> + This is the alias for the method <emphasis>delete(PropertyData data).</emphasis> + </entry> - </row> - <row> - <entry> - renameNodeData - </entry> - <entry> - This is the alias for the method <emphasis>rename(NodeData data).</emphasis> - </entry> + </row> + <row> + <entry> + renameNodeData + </entry> + <entry> + This is the alias for the method <emphasis>rename(NodeData data).</emphasis> + </entry> - </row> - <row> - <entry> - rollback - </entry> - <entry> - This is the alias for the method <emphasis>rollback().</emphasis> - </entry> + </row> + <row> + <entry> + rollback + </entry> + <entry> + This is the alias for the method <emphasis>rollback().</emphasis> + </entry> - </row> - <row> - <entry> - isOpened - </entry> - <entry> - This is the alias for the method <emphasis>isOpened().</emphasis> - </entry> + </row> + <row> + <entry> + isOpened + </entry> + <entry> + This is the alias for the method <emphasis>isOpened().</emphasis> + </entry> - </row> - <row> - <entry> - close - </entry> - <entry> - This is the alias for the method <emphasis>close().</emphasis> - </entry> + </row> + <row> + <entry> + close + </entry> + <entry> + This is the alias for the method <emphasis>close().</emphasis> + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> + </table> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-eXo_JCR_statistics-Statistics_on_the_JCR_API_accesses"> - <title>Statistics on the JCR API accesses</title> - <para> - In order to know exactly how your application uses eXo JCR, it can be interesting to register all the JCR API accesses in order to easily create real life test scenario based on pure JCR calls and also to tune your eXo JCR to better fit your requirements. - </para> - <para> - In order to allow you to specify the configuration which part of eXo JCR needs to be monitored without applying any changes in your code and/or building anything, we choose to rely on the Load-time Weaving proposed by AspectJ. - </para> - <para> - To enable this feature, you will have to add in your classpath the following jar files: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar corresponding to your eXo JCR version that you can get from the jboss maven repository <ulink url="http://repository.jboss.com/maven2/org/exoplatform/jcr/exo.jcr....;. - </para> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-eXo_JCR_statistics-Statistics_on_the_JCR_API_accesses"> + <title>Statistics on the JCR API accesses</title> + <para> + In order to know exactly how your application uses eXo JCR, it can be interesting to register all the JCR API accesses in order to easily create real life test scenario based on pure JCR calls and also to tune your eXo JCR to better fit your requirements. + </para> + <para> + In order to allow you to specify the configuration which part of eXo JCR needs to be monitored without applying any changes in your code and/or building anything, we choose to rely on the Load-time Weaving proposed by AspectJ. + </para> + <para> + To enable this feature, you will have to add in your classpath the following jar files: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar corresponding to your eXo JCR version that you can get from the jboss maven repository <ulink url="http://repository.jboss.com/maven2/org/exoplatform/jcr/exo.jcr....;. + </para> - </listitem> - <listitem> - <para> - aspectjrt-1.6.8.jar that you can get from the main maven repository <ulink url="http://repo2.maven.org/maven2/org/aspectj/aspectjrt">&l...;. - </para> + </listitem> + <listitem> + <para> + aspectjrt-1.6.8.jar that you can get from the main maven repository <ulink url="http://repo2.maven.org/maven2/org/aspectj/aspectjrt">&l...;. + </para> - </listitem> + </listitem> - </itemizedlist> - <para> - You will also need to get aspectjweaver-1.6.8.jar from the main maven repository <ulink url="http://repo2.maven.org/maven2/org/aspectj/aspectjweaver"&g...;. At this stage, to enable the statistics on the JCR API accesses, you will need to add the JVM parameter <emphasis>-javaagent:${pathto}/aspectjweaver-1.6.8.jar</emphasis> to your command line, for more details please refer to <ulink url="http://www.eclipse.org/aspectj/doc/released/devguide/ltw-config...;. - </para> - <para> - By default, the configuration will collect statistics on all the methods of the internal interfaces <emphasis>org.exoplatform.services.jcr.core.ExtendedSession</emphasis> and <emphasis>org.exoplatform.services.jcr.core.ExtendedNode</emphasis>, and the JCR API interface <emphasis>javax.jcr.Property</emphasis>. To add and/or remove some interfaces to monitor, you have two configuration files to change that are bundled into the jar <emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar, which are <emphasis>conf/configuration.xml</emphasis> and <emphasis>META-INF/aop.xml</emphasis>. - </para> - <para> - The file content below is the content of <emphasis>conf/configuration.xml</emphasis> that you will need to modify to add and/or remove the full qualified name of the interfaces to monitor, into the list of parameter values of the init param called <emphasis>targetInterfaces</emphasis>. - </para> - + </itemizedlist> + <para> + You will also need to get <filename>aspectjweaver-1.6.8.jar</filename> from the main maven repository <ulink url="http://repo2.maven.org/maven2/org/aspectj/aspectjweaver"&g...;. + </para> + <para> + At this stage, to enable the statistics on the JCR API accesses, you will need to add the JVM parameter <parameter>-javaagent:${pathto}/aspectjweaver-1.6.8.jar</parameter> to your command line, for more details please refer to <ulink url="http://www.eclipse.org/aspectj/doc/released/devguide/ltw-config...;. + </para> + <para> + By default, the configuration will collect statistics on all the methods of the internal interfaces <literal>org.exoplatform.services.jcr.core.ExtendedSession</literal> and <literal>org.exoplatform.services.jcr.core.ExtendedNode</literal>, and the JCR API interface <literal>javax.jcr.Property</literal>. + </para> + <para> + To add and/or remove some interfaces to monitor, you have two configuration files to change that are bundled into the jar <literal>exo.jcr.component.statistics-X.Y.Z</literal>.jar, which are <filename>conf/configuration.xml</filename> and <filename>META-INF/aop.xml</filename>. + </para> + <para> + The file content below is the content of <filename>conf/configuration.xml</filename> that you will need to modify to add and/or remove the full qualified name of the interfaces to monitor, into the list of parameter values of the init param called <literal>targetInterfaces</literal>. + </para> + <programlisting language="XML" role="XML">&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; @@ -293,10 +305,13 @@ &lt;/init-params&gt; &lt;/component&gt; &lt;/configuration&gt;</programlisting> - <para> - The file content below is the content of <emphasis>META-INF/aop.xml</emphasis> that you will to need to modify to add and/or remove the full qualified name of the interfaces to monitor, into the expression filter of the pointcut called <emphasis>JCRAPIPointcut</emphasis>. As you can see below, by default only JCR API calls from the exoplatform packages are took into account, do not hesitate to modify this filter to add your own package names. - </para> - + <para> + The file content below is the content of <filename>META-INF/aop.xml</filename> that you will to need to modify to add and/or remove the full qualified name of the interfaces to monitor, into the expression filter of the pointcut called <literal>JCRAPIPointcut</literal>. + </para> + <para> + By default only JCR API calls from the <literal>exoplatform</literal> packages are taken into account. This filter can be modified to add other package names. + </para> + <programlisting language="XML" role="XML">&lt;aspectj&gt; &lt;aspects&gt; &lt;concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect"&gt; @@ -308,170 +323,178 @@ &lt;include within="org.exoplatform..*" /&gt; &lt;/weaver&gt; &lt;/aspectj&gt;</programlisting> - <para> - The corresponding CSV files are of type <emphasis>Statistics${interface-name}-${creation-timestamp}.csv</emphasis> for more details about how the csv files are managed, please refer to the section dedicated to the statistics manager. - </para> - <para> - The format of each column header is ${method-alias}-${metric-alias}. The method alias will be of type ${method-name}(list of parameter types separated by ; to be compatible with the CSV format). - </para> - <para> - The metric alias are described in the statistics manager section. - </para> - <para> - The name of the category of statistics corresponding to these statistics is the simple name of the monitored interface (e.g. ExtendedSession for org.exoplatform.services.jcr.core.ExtendedSession), this name is mostly needed to access to the statistics through JMX. - </para> - <remark>Please note that this feature will affect the performances of eXo JCR so it must be used with caution.</remark> + <para> + The corresponding CSV files are of type <filename>Statistics<replaceable>${interface-name}</replaceable>-<replaceable>${creation-timestamp}</replaceable>.csv</filename> for more details about how the <emphasis>CSV</emphasis> files are managed, please refer to the section dedicated to the statistics manager. + </para> + <para> + The format of each column header is <replaceable>${method-alias}</replaceable>-<replaceable>${metric-alias}</replaceable>. The method alias will be of type <replaceable>${method-name}(semicolon-delimited-list-of-parameter-types-to-be-compatible-with-the-CSV-format)</replaceable>. + </para> + <para> + The metric alias are described in the statistics manager section. + </para> + <para> + The name of the category of statistics corresponding to these statistics is the simple name of the monitored interface (e.g. <literal>ExtendedSession</literal> for <literal>org.exoplatform.services.jcr.core.ExtendedSession</literal>), this name is mostly needed to access to the statistics through JMX. + </para> + <note> + <title>Performance Consideration</title> + <para> + Please note that this feature will affect the performances of eXo JCR so it must be used with caution. + </para> + </note> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-eXo_JCR_statistics-Statistics_Manager"> - <title>Statistics Manager</title> - <para> - The statistics manager manages all the statistics provided by eXo JCR, it is responsible of printing the data into the CSV files and also exposing the statistics through JMX and/or Rest. - </para> - <para> - The statistics manager will create all the CSV files for each category of statistics that it manages, the format of those files is <emphasis>Statistics${category-name}-${creation-timestamp}.csv</emphasis>. Those files will be created into the user directory if it is possible otherwise it will create them into the temporary directory. The format of those files is <envar>CSV</envar> (i.e. Comma-Separated Values), one new line will be added regularly (every 5 seconds by default) and one last line will be added at JVM exit. Each line, will be composed of the 5 figures described below for each method and globally for all the methods. - </para> - <para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Statistics_Manager-Metric_Alias"> - <title>Metric Alias</title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - Min - </entry> - <entry> - The minimum time spent into the method expressed in milliseconds. - </entry> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-eXo_JCR_statistics-Statistics_Manager"> + <title>Statistics Manager</title> + <para> + The statistics manager manages all the statistics provided by eXo JCR, it is responsible of printing the data into the CSV files and also exposing the statistics through JMX and/or Rest. + </para> + <para> + The statistics manager will create all the CSV files for each category of statistics that it manages, the format of those files is <emphasis>Statistics${category-name}-${creation-timestamp}.csv</emphasis>. Those files will be created into the user directory if it is possible otherwise it will create them into the temporary directory. The format of those files is <envar>CSV</envar> (i.e. Comma-Separated Values), one new line will be added regularly (every 5 seconds by default) and one last line will be added at JVM exit. Each line, will be composed of the 5 figures described below for each method and globally for all the methods. + </para> + <para> + <table id="tabl-Reference_Guide_eXo_JCR_1.14-Statistics_Manager-Metric_Alias"> + <title>Metric Alias</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> + Min + </entry> + <entry> + The minimum time spent into the method expressed in milliseconds. + </entry> - </row> - <row> - <entry> - Max - </entry> - <entry> - The maximum time spent into the method expressed in milliseconds. - </entry> + </row> + <row> + <entry> + Max + </entry> + <entry> + The maximum time spent into the method expressed in milliseconds. + </entry> - </row> - <row> - <entry> - Total - </entry> - <entry> - The total amount of time spent into the method expressed in milliseconds. - </entry> + </row> + <row> + <entry> + Total + </entry> + <entry> + The total amount of time spent into the method expressed in milliseconds. + </entry> - </row> - <row> - <entry> - Avg - </entry> - <entry> - The average time spent into the method expressed in milliseconds. - </entry> + </row> + <row> + <entry> + Avg + </entry> + <entry> + The average time spent into the method expressed in milliseconds. + </entry> - </row> - <row> - <entry> - Times - </entry> - <entry> - The total amount of times the method has been called. - </entry> + </row> + <row> + <entry> + Times + </entry> + <entry> + The total amount of times the method has been called. + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> - You can disable the persistence of the statistics by setting the JVM parameter called <emphasis>JCRStatisticsManager.persistence.enabled</emphasis> to <emphasis>false</emphasis>, by default, it is set to <emphasis>true</emphasis>. You can also define the period of time between each record (i.e. line of data into the file) by setting the JVM parameter called <emphasis>JCRStatisticsManager.persistence.timeout</emphasis> to your expected value expressed in milliseconds, by default it is set to <emphasis>5000</emphasis>. - </para> - <para> - You can also access to the statistics thanks to JMX, the available methods are the following: - </para> - <para> - <table id="tabl-Reference_Guide_eXo_JCR_1.14-Statistics_Manager-JMX_Methods"> - <title>JMX Methods</title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - getMin - </entry> - <entry> - Give the minimum time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. - </entry> + </table> + You can disable the persistence of the statistics by setting the JVM parameter called <parameter>JCRStatisticsManager.persistence.enabled</parameter> to <literal>false</literal>. It is set to <literal>true</literal> by default. + </para> + <para> + You can also define the period of time between each record (that is, line of data into the file) by setting the JVM parameter called <parameter>JCRStatisticsManager.persistence.timeout</parameter> to your expected value expressed in milliseconds. It is set to <literal>5000</literal> by default. + </para> + <para> + You can also access to the statistics via JMX. The available methods are: + </para> + <para> + <table id="tabl-Reference_Guide_eXo_JCR_1.14-Statistics_Manager-JMX_Methods"> + <title>JMX Methods</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> + getMin + </entry> + <entry> + Give the minimum time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics (<literal>JDBCStorageConnection</literal> for example) and the name of the expected method or global for the global value. + </entry> - </row> - <row> - <entry> - getMax - </entry> - <entry> - Give the maximum time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. - </entry> + </row> + <row> + <entry> + getMax + </entry> + <entry> + Give the maximum time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics and the name of the expected method or global for the global value. + </entry> - </row> - <row> - <entry> - getTotal - </entry> - <entry> - Give the total amount of time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. - </entry> + </row> + <row> + <entry> + getTotal + </entry> + <entry> + Give the total amount of time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics and the name of the expected method or global for the global value. + </entry> - </row> - <row> - <entry> - getAvg - </entry> - <entry> - Give the average time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. - </entry> + </row> + <row> + <entry> + getAvg + </entry> + <entry> + Give the average time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of statistics and the name of the expected method or global for the global value. + </entry> - </row> - <row> - <entry> - getTimes - </entry> - <entry> - Give the total amount of times the method has been called corresponding to the given ,category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. - </entry> + </row> + <row> + <entry> + getTimes + </entry> + <entry> + Give the total amount of times the method has been called corresponding to the given ,category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. + </entry> - </row> - <row> - <entry> - reset - </entry> - <entry> - Reset the statistics for the given category name and statistics name. The expected arguments are the name of the category of statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. - </entry> + </row> + <row> + <entry> + reset + </entry> + <entry> + Reset the statistics for the given category name and statistics name. The expected arguments are the name of the category of statistics and the name of the expected method or global for the global value. + </entry> - </row> - <row> - <entry> - resetAll - </entry> - <entry> - Reset all the statistics for the given category name. The expected argument is the name of the category of statistics (e.g. JDBCStorageConnection). - </entry> + </row> + <row> + <entry> + resetAll + </entry> + <entry> + Reset all the statistics for the given category name. The expected argument is the name of the category of statistics (e.g. JDBCStorageConnection). + </entry> - </row> + </row> - </tbody> + </tbody> - </tgroup> + </tgroup> - </table> - The full name of the related MBean is <emphasis>exo:service=statistic, view=jcr</emphasis>. - </para> + </table> + The full name of the related MBean is <literal>xo:service=statistic, view=jcr</literal>. + </para> - </section> - + </section> + </section> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr.xml 2011-10-31 20:30:56 UTC (rev 7916) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/jcr.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -4,51 +4,66 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide_eXo_JCR_1.14-eXoJCR"> - <title>eXoJCR</title> - <xi:include href="jcr/intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- concepts --> <!-- <xi:include href="jcr/concepts/why-jcr.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="jcr/concepts/jcr-exo-implementation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/concepts/jcr-advantages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/concepts/jcr-compatibility-levels.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/concepts/jcr-usage.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- <xi:include href="jcr/concepts/jcr-extensions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="jcr/concepts/jcr-applications.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/concepts/nodetypes-and-namespaces.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/concepts/nodetype-registration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/concepts/jcr-registry-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/concepts/jcr-namespace-altering.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- common configs --> <xi:include href="jcr/configuration/exo-jcr-configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/configuration/multilanguage-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/configuration/search-configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/configuration/configuration-persister.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/configuration/jdbc-data-container-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/configuration/external-value-storages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/configuration/workspace-persistence-storage.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/configuration/rest-services-on-groovy.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- cluster configs --> <!-- <xi:include href="jcr/cluster-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="jcr/jbosscache-configuration-templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/lock-manager-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/query-handler-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/jbossts-transaction-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/transaction-manager-lookup.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/repository-creation-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- search + <title>eXoJCR</title> + <xi:include href="jcr/intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- concepts --> + <!-- <xi:include href="jcr/concepts/why-jcr.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> + <xi:include href="jcr/concepts/jcr-exo-implementation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/concepts/jcr-advantages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/concepts/jcr-compatibility-levels.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/concepts/jcr-usage.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- <xi:include href="jcr/concepts/jcr-extensions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> + <xi:include href="jcr/concepts/jcr-applications.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/concepts/nodetypes-and-namespaces.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/concepts/nodetype-registration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/concepts/jcr-registry-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/concepts/jcr-namespace-altering.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- common configs --> + <xi:include href="jcr/configuration/exo-jcr-configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/configuration/multilanguage-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/configuration/search-configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/configuration/configuration-persister.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/configuration/jdbc-data-container-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/configuration/external-value-storages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/configuration/workspace-persistence-storage.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/configuration/rest-services-on-groovy.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- cluster configs --> + <xi:include href="jcr/cluster-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/jbosscache-configuration-templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/lock-manager-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/query-handler-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/jbossts-transaction-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/transaction-manager-lookup.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/repository-creation-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- search + DOC NOTE: Something in this section SEGFAULTS Publican. + Will look into a fix after 5.2.0 release <xi:include href="jcr/searching/jcr-query-usecases.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="jcr/searching/searching-repository-content.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/searching/fulltext-search-and-settings.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <!-- protocols --> <xi:include href="jcr/protocols/webdav.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/protocols/ftp.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- backup --> <xi:include href="jcr/backup/exojcr-backup-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/backup/backup-client.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/backup/use-external-backup-tool.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- other --> <xi:include href="jcr/statistics.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/jta.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/jca.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/other/acl.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/other/acl-ext.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/other/link-producer.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/other/binary-values-processing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jcr/other/jcr-resources.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- data container configs --> <xi:include href="jcr/data-container.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- <xi:include href="jcr/data-container-howto.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="jcr/db-cleaner-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- tuning guide - DOC NOTE: Could possibly be moved to a specific Tuning Guide later --> <xi:include href="jcr/performance-tuning-guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/searching/fulltext-search-and-settings.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> + <!-- protocols --> + <xi:include href="jcr/protocols/webdav.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/protocols/ftp.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- backup --> + <xi:include href="jcr/backup/exojcr-backup-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/backup/backup-client.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/backup/use-external-backup-tool.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- other --> + <xi:include href="jcr/statistics.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/jta.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/jca.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/other/acl.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/other/acl-ext.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/other/link-producer.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/other/binary-values-processing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/other/jcr-resources.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- data container configs --> + <xi:include href="jcr/data-container.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- <xi:include href="jcr/data-container-howto.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> + <xi:include href="jcr/db-cleaner-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- tuning guide + DOC NOTE: Could possibly be moved to a specific Tuning Guide later --> + <xi:include href="jcr/performance-tuning-guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </section> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/framework-for-cross-domain-ajax.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/framework-for-cross-domain-ajax.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/framework-for-cross-domain-ajax.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,120 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="WS.CrossDomainAJAX"> + <?dbhtml filename="ch-framework-for-cross-domain-ajax.html"?> + + <title>Framework for cross-domain AJAX</title> + + <para>(<ulink + url="https://anonsvn.jboss.org/repos/exo-jcr/ws/trunk/exo.ws.framewo... + + <section> + <title>Motivation</title> + + <para>XmlHttpRequest objects are bound by the same origin security policy + of browsers, which prevents a page from accessing data from another + server. This has put a serious limitation on Ajax developers: you can use + XmlHttpRequests to make background calls to a server, but it has to be the + same server that served up the current page. For more details, you can + visit <ulink + url="http://www.mozilla.org/projects/security/components/same-origin... + + <mediaobject> + <imageobject> + <imagedata fileref="images/ajax.gif" /> + </imageobject> + </mediaobject> + + <para>But actually writing client web applications that use this object + can be tricky given restrictions imposed by web browsers on network + connections across domains. So you need to find the way to bypass this + limitation of AJAX.</para> + </section> + + <section> + <title>Scheme (how it works)</title> + + <para>To describe our method for cross-domain AJAX solution, let's + consider the following scheme contains of 3 components:</para> + + <para>1). User agent (a browser).</para> + + <para>2). ServerA contains a main page with dedicated client and server + IFRAMEs (see below) and an HTML client page (client.html) referenced from + the client IFRAME. This client page contains dedicated script to push the + data for request into server IFRAME.</para> + + <para>3). ServerB contains remote service that want get access to and an + HTML server page (server.html) referenced from the server IFRAME. This + server page contains dedicated script to push the requested data into + client IFRAME.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/ajax-how-it-works.png" /> + </imageobject> + </mediaobject> + </section> + + <section> + <title>A Working Sequence:</title> + + <para>1) A Browser requests the Start page from the ServerA</para> + + <para>2) The Start page is retrieved from the ServerA.</para> + + <para>3) Create in the start page IFRAME (name it - "client iframe") and + insert it in the document from ServerA (client.</para> + + <para>4) In "client iframe" create ne IFRAME element ("server iframe") and + insert it in the document from ServerB (server.html). Documents + (client.html and server.html) contain special script that can transfer + data between ifarmes.</para> + + <para>5) "Client iframe" transfer information about HTTP method and URL + that we want do cross-domain request to "server iframe".</para> + + <para>6) "Server iframe" do simple XmlHttpRequest to the service that we + need (it can do that because download from same domain) and get informaton + from service.</para> + + <para>7) "Server iframe" transfer data to "client iframe" and now we get + information that we want.</para> + </section> + + <section> + <title>How to use it</title> + + <para>1). Place the file client.html and xda.js on the serverA.</para> + + <para>2). Place the file server.html on the serverB.</para> + + <para>3). Declare xda.js in the main page.</para> + + <programlisting language="html">&lt;script type="text/javascript" src="xda.js"&gt;&lt;/script&gt;</programlisting> + + <para>4). Create JS function which performs cross domain call as in the + following example:</para> + + <programlisting language="javascript">&lt;script type="text/javascript"&gt; + function test(){ + var facade = xdaInit(); + facade.clientURI = "http://localhost/cross-domain-ajax/client/client.html"; + facade.serverURI = "http://localhost:8080/cross-domain-ajax/server/server.html"; + facade.apiURI = "http://localhost:8080/cross-domain-ajax/server/test.txt"; + facade.method = "POST"; + facade.load = function(result) { + alert(result.responseText); + } + facade.setRequestHeader("keep-alive","200"); + xda.create(facade); + } +&lt;/script&gt;</programlisting> + + <para>5). Use this function (here it is bound to a button's onclick + event).</para> + + <programlisting language="html">&lt;button onclick='test()'&gt;test cross-domain&lt;/button&gt;</programlisting> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/groovy-scripts-as-rest-services.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/groovy-scripts-as-rest-services.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/groovy-scripts-as-rest-services.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,386 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="WS.GroovyScripts"> + <?dbhtml filename="ch-groovy-scripts-as-rest-services.html"?> + + <title>Groovy Scripts as REST Services</title> + + <section> + <title>Overview</title> + + <para>This article describes how to use Groovy scripts as REST services. + We are going to consider these operations:</para> + + <itemizedlist> + <listitem> + <para>Load script and save it in JCR.</para> + </listitem> + + <listitem> + <para>Instantiate script</para> + </listitem> + + <listitem> + <para>Deploy newly created Class as RESTful service.</para> + </listitem> + + <listitem> + <para>Script Lifecycle Management.</para> + </listitem> + + <listitem> + <para>And finally we will discover simple example which can get JCR + node UUID</para> + </listitem> + </itemizedlist> + + <para>In this article, we consider RESTful service compatible with JSR-311 + specification. Currently last feature available in version 1.11-SNAPSHOT + of JCR, 2.0-SNAPSHOT of WS and version 2.1.4-SNAPSHOT of core.</para> + </section> + + <section> + <title>Loading script and save it in JCR</title> + + <para>There are two ways to save a script in JCR. The first way is to save + it at server startup time by using configuration.xml and the second way is + to upload the script via HTTP.</para> + + <para><command>Load script at startup time</command></para> + + <para>This way can be used for load prepared scripts, to use this way. we + must configure + org.exoplatform.services.jcr.ext.script.groovy.GroovyScript2RestLoaderPlugin. + This is simple configuration example.</para> + + <programlisting language="xml">&lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.jcr.ext.script.groovy.GroovyScript2RestLoader&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;test&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.jcr.ext.script.groovy.GroovyScript2RestLoaderPlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;repository&lt;/name&gt; + &lt;value&gt;repository&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;workspace&lt;/name&gt; + &lt;value&gt;production&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;node&lt;/name&gt; + &lt;value&gt;/script/groovy&lt;/value&gt; + &lt;/value-param&gt; + &lt;properties-param&gt; + &lt;name&gt;JcrGroovyTest.groovy&lt;/name&gt; + &lt;property name="autoload" value="true" /&gt; + &lt;property name="path" value="file:/home/andrew/JcrGroovyTest.groovy" /&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; +&lt;/external-component-plugins&gt;</programlisting> + + <para>The first is value-param sets JCR repository, the second is + value-param sets workspace and the third one is sets JCR node where + scripts from plugin will be stored. If specified node does not exist, then + it will be created. List of scripts is set by properties-params. Name of + each properties-param will be used as node name for stored script, + property autoload says to deploy this script at startup time, property + path sets the source of script to be loaded. In this example we try to + load single script from local file + /home/andrew/JcrGroovyTest.groovy.</para> + + <para><command>Load script via HTTP</command></para> + + <para>This is samples of HTTP requests. In this example, we will upload + script from file with name test.groovy.</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X POST \ +-H 'Content-type:script/groovy' \ +--data-binary @test.groovy \ +http://localhost:8080/rest/script/groovy/add/repository/production/script/groovy/test.groovy</programlisting> + + <para>This example imitate sending data with HTML form + ('multipart/form-data'). Parameter autoload is optional. If parameter + autoload=true then script will be instantiate and deploy script + immediately.</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X POST \ +-F &quot;file=(a)test.groovy;name=test&quot; \ +-F "autoload=true" \ +http://localhost:8080/rest/script/groovy/add/repository/production/script/groovy/test1.groovy</programlisting> + </section> + + <section> + <title>Instantiation</title> + + <para>org.exoplatform.services.script.groovy.GroovyScriptInstantiator is + part of project exo.core.component.script.groovy. GroovyScriptInstantiator + can load script from specified URL and parse stream that contains Groovy + source code. It has possibility inject component from Container in Groovy + Class constructor. Configuration example:</para> + + <programlisting language="xml">&lt;component&gt; + &lt;type&gt;org.exoplatform.services.script.groovy.GroovyScriptInstantiator&lt;/type&gt; +&lt;/component&gt;</programlisting> + </section> + + <section> + <title>Deploying newly created Class as RESTful service</title> + + <para>To deploy script automatically at server statup time, its property + exo:autoload must be set as true. + org.exoplatform.services.jcr.ext.script.groovy.GroovyScript2RestLoader + check JCR workspaces which were specified in configuration and deploy all + auto-loadable scripts.</para> + + <para>Example of configuration.</para> + + <programlisting language="xml">&lt;component&gt; + &lt;type&gt;org.exoplatform.services.jcr.ext.script.groovy.GroovyScript2RestLoader&lt;/type&gt; + &lt;init-params&gt; + &lt;object-param&gt; + &lt;name&gt;observation.config&lt;/name&gt; + &lt;object type="org.exoplatform.services.jcr.ext.script.groovy.ObservationListenerConfiguration"&gt; + &lt;field name="repository"&gt; + &lt;string&gt;repository&lt;/string&gt; + &lt;/field&gt; + &lt;field name="workspaces"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;string&gt;production&lt;/string&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component&gt;</programlisting> + + <para>In example above JCR workspace "production" will be checked for + autoload scripts. At once, this workspace will be listened for changes + script's source code (property jcr:data).</para> + </section> + + <section> + <title>Script Lifecycle Management</title> + + <para>If GroovyScript2RestLoader configured as was decribed in the + previous section, then all "autoload" scripts deployed. In the first + section, we added script from file /home/andrew/JcrGroovyTest.groovy to + JCR node /script/groovy/JcrGroovyTest.groovy, repository repository, + workspace production. In section "Load script via HTTP", it was refered + about load scripts via HTTP, there is an opportunity to manage the life + cycle of script.</para> + + <para>Undeploy script, which is alredy deployed:</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X GET \ +http://localhost:8080/rest/script/groovy/load/repository/production/script/groovy/JcrGroovyTest.groovy?state=false</programlisting> + + <para>Then deploy it again:</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X GET \ +http://localhost:8080/rest/script/groovy/load/repository/production/script/groovy/JcrGroovyTest.groovy?state=true</programlisting> + + <para>or even more simple:</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X GET \ +http://localhost:8080/rest/script/groovy/load/repository/production/script/groovy/JcrGroovyTest.groovy</programlisting> + + <para>Disable scripts autoloading, NOTE it does not change current + state:</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X GET \ +http://localhost:8080/rest/script/groovy/repository/production/script/groovy/JcrGroovyTest.groovy/autoload?state=false</programlisting> + + <para>Enable it again:</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X GET \ +http://localhost:8080/rest/script/groovy/autoload/repository/production/script/groovy/JcrGroovyTest.groovy?state=true</programlisting> + + <para>and again more simpe variant:</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X GET \ +http://localhost:8080/rest/script/groovy/autoload/repository/production/script/groovy/JcrGroovyTest.groovy</programlisting> + + <para>Change script source code:</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X POST \ +-H 'Content-type:script/groovy' \ +--data-binary @JcrGroovyTest.groovy \ +http://localhost:8080/rest/script/groovy/update/repository/production/script/groovy/JcrGroovyTest.groovy</programlisting> + + <para>This example imitates sending data with HTML form + ('multipart/form-data').</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X POST \ +-F &quot;file=(a)JcrGroovyTest.groovy;name=test&quot; \ +http://localhost:8080/rest/script/groovy/update/repository/production/script/groovy/JcrGroovyTest.groovy</programlisting> + + <para>Remove script from JCR:</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X GET \ +http://localhost:8080/rest/script/groovy/delete/repository/production/script/groovy/JcrGroovyTest.groovy</programlisting> + </section> + + <section> + <title>Getting node UUID example</title> + + <para>Now we are going to try simple example of Groovy RESTfull service. + There is one limitation, even if we use groovy, we should use Java style + code and decline to use dynamic types, but of course we can use it in + private methods and feilds. Create file JcrGroovyTest.groovy, in this + example I save it in my home directory /home/andrew/JcrGroovyTest.groovy. + Then, configure GroovyScript2RestLoaderPlugin as described in section Load + script at startup time.</para> + + <programlisting language="java">import javax.jcr.Node +import javax.jcr.Session +import javax.ws.rs.GET +import javax.ws.rs.Path +import javax.ws.rs.PathParam +import org.exoplatform.services.jcr.RepositoryService +import org.exoplatform.services.jcr.ext.app.ThreadLocalSessionProviderService + +@Path("groovy/test/{repository}/{workspace}") +public class JcrGroovyTest { + private RepositoryService repositoryService + private ThreadLocalSessionProviderService sessionProviderService + + public JcrGroovyTest(RepositoryService repositoryService, + ThreadLocalSessionProviderService sessionProviderService) { + this.repositoryService = repositoryService + this.sessionProviderService = sessionProviderService + } + + + @GET + @Path("{path:.*}") + public String nodeUUID(@PathParam("repository") String repository, + @PathParam("workspace") String workspace, + @PathParam("path") String path) { + Session ses = null + try { + ses = sessionProviderService.getSessionProvider(null).getSession(workspace, repositoryService.getRepository(repository)) + Node node = (Node) ses.getItem("/" + path) + return node.getUUID() + "\n" + } finally { + if (ses != null) + ses.logout() + } + }</programlisting> + + <para>After configuration is done, start the server. If configuration is + correct and script does not have syntax error, you should see next:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/groovy-console1.png" /> + </imageobject> + </mediaobject> + + <para>In the screenshot, we can see the service deployed.</para> + + <para>First, create a folder via WebDAV in the repository production, + folder name 'test'. Now, we can try access this service. Open another + console and type command:</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +http://localhost:8080/rest/groovy/test/repository/production/test</programlisting> + + <para>Whe you try to execute this command, you should have exception, + because JCR node '/test' is not referenceable and has not UUID. We can try + add mixin mix:referenceable. To do this, add one more method in script. + Open script from local source code /home/andrew/JcrGroovyTest.groovy, add + following code and save file.</para> + + <programlisting language="java">@POST +@Path("{path:.*}") +public void addReferenceableMixin(@PathParam("repository") String repository, + @PathParam("workspace") String workspace, + @PathParam("path") String path) { + Session ses = null + try { + ses = sessionProviderService.getSessionProvider(null).getSession(workspace, repositoryService.getRepository(repository)) + Node node = (Node) ses.getItem("/" + path) + node.addMixin("mix:referenceable") + ses.save() + } finally { + if (ses != null) + ses.logout() + } +}</programlisting> + + <para>Now we can try to change script deployed on the server without + server restart. Type in console next command:</para> + + <programlisting>andrew@ossl:~&gt; curl -i -v -u root:exo \ +-X POST \ +--data-binary @JcrGroovyTest.groovy \ +-H 'Content-type:script/groovy' \ +http://localhost:8080/rest/script/groovy/update/repository/production/script/groovy/JcrGroovyTest.groovy</programlisting> + + <para>Node '/script/groovy/JcrGroovyTest.groovy' has property + exo:autoload=true so script will be re-deployed automatically when script + source code changed.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/groovy-console2.png" /> + </imageobject> + </mediaobject> + + <para>Script was redeployed, now try to access a newly created + method.</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +-X POST \ +http://localhost:8080/rest/groovy/test/repository/production/test</programlisting> + + <para>Method excution should be quiet, without output, traces, etc. Then + we can try again get node UUID.</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +http://localhost:8080/rest/groovy/test/repository/production/test +1b8c88d37f0000020084433d3af4941f</programlisting> + + <para>Node UUID: 1b8c88d37f0000020084433d3af4941f</para> + + <para>We don't need this scripts any more, so remove it from JCR.</para> + + <programlisting>andrew@ossl:~&gt; curl -u root:exo \ +http://localhost:8080/rest/script/groovy/delete/repository/production/script/groovy/JcrGroovyTest.groovy</programlisting> + + <mediaobject> + <imageobject> + <imagedata fileref="images/groovy-console3.png" /> + </imageobject> + </mediaobject> + </section> + + <section> + <title>Groovy script restrictions</title> + + <para>You should keep one class per one groovy file. The same actually for + interface and it implementation. It's limitation of groovy parser that + does not have type Class[] parseClass(InputStream) or Collection + parseClass(InputStream) but only Class parseClass(InputStream) + instead.</para> + + <para>That is all.</para> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/introduction-to-rest.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/introduction-to-rest.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/introduction-to-rest.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,212 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id = "WS.Introduction"> + <?dbhtml filename="ch-introduction-to-rest.html"?> + + <title>Introduction to the Representational State Transfer (REST)</title> + + <section> + <title>Introduction</title> + + <para><command>Representational State Transfer (REST)</command> is a style + of software architecture for distributed hypermedia systems such as the + World Wide Web. The term was introduced in the doctoral dissertation in + 2000 by Roy Fielding, one of the principal authors of the Hypertext + Transfer Protocol (HTTP) specification, and has come into widespread use + in the networking community.</para> + + <para>REST strictly refers to a collection of network architecture + principles that outline how resources are defined and addressed. The term + is often used in a looser sense to describe any simple interface that + transmits domain-specific data over HTTP without an additional messaging + layer such as SOAP or session tracking via HTTP cookies.</para> + + <para>The key abstraction of information in REST is a + <command>resource</command>. Any information that can be named can be a + resource: a document or image, a temporal service (e.g. "today's weather + in Los Angeles"), a collection of other resources, a non-virtual object + (e.g. a person), and so on. In other words, any concept that might be the + target of an author's hypertext reference must fit within the definition + of a resource. A resource is a conceptual mapping to a set of entities, + not the entity that corresponds to the mapping at any particular point in + time.</para> + + <para>REST uses a <command>resource identifier </command>to identify the + particular resource involved in an interaction between components. REST + connectors provide a generic interface for accessing and manipulating the + value set of a resource, regardless of how the membership function is + defined or the type of software that is handling the request. URL or URN + are the examples of a resource identifier.</para> + + <para>REST components perform actions with a resource by using a + <command>representation</command> to capture the current or intended state + of that resource and transferring that representation between components. + A representation is a sequence of bytes, plus <command>representation + metadata </command>to describe those bytes. Other commonly used but less + precise names for a representation include: <command>document, file, and + HTTP message entity, instance, or variant</command>. A representation + consists of data, metadata describing the data, and, on occasion, metadata + to describe the metadata (usually for the purpose of verifying message + integrity). Metadata are in the form of name-value pairs, where the name + corresponds to a standard that defines the value's structure and + semantics. The data format of a representation is known as a media + type.</para> + + <table> + <title>REST Data Elements</title> + + <tgroup cols="2"> + <thead> + <row> + <entry align="center">Data Element</entry> + + <entry align="center">Modern Web Examples</entry> + </row> + </thead> + + <tbody> + <row> + <entry>resource</entry> + + <entry>the intended conceptual target of a hypertext + reference</entry> + </row> + + <row> + <entry>resource identifier</entry> + + <entry>URL, URN</entry> + </row> + + <row> + <entry>representation</entry> + + <entry>HTML document, JPEG image</entry> + </row> + + <row> + <entry>representation metadata</entry> + + <entry>media type, last-modified time</entry> + </row> + + <row> + <entry>resource metadata</entry> + + <entry>source link, alternates, vary</entry> + </row> + + <row> + <entry>control data</entry> + + <entry>if-modified-since, cache-control</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>REST uses various <command>connector</command> types to encapsulate + the activities of accessing resources and transferring resource + representations. The connectors present an abstract interface for + component communication, enhancing simplicity by providing a complete + separation of concepts and hiding the underlying implementation of + resources and communication mechanisms.</para> + + <table> + <title>REST Connectors</title> + + <tgroup cols="2"> + <thead> + <row> + <entry align="center">Connector</entry> + + <entry align="center">Modern Web Examples</entry> + </row> + </thead> + + <tbody> + <row> + <entry>client</entry> + + <entry>libwww, libwww-perl</entry> + </row> + + <row> + <entry>server</entry> + + <entry>libwww, Apache API, NSAPI</entry> + </row> + + <row> + <entry>cache</entry> + + <entry>browser cache, Akamai cache network</entry> + </row> + + <row> + <entry>resolver</entry> + + <entry>bind (DNS lookup library)</entry> + </row> + + <row> + <entry>tunnel</entry> + + <entry><para></para>SOCKS, SSL after HTTP CONNECT</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>The primary connector types are client and server. The essential + difference between the two is that a client initiates communication by + making a request, whereas a server listens for connections and responds to + requests in order to supply access to its services. A component may + include both client and server connectors.</para> + + <para>An important part of RESTful architecture is a well-defined + interface to communicate, in particular it is a set of HTTP methods such + as POST, GET, PUT and DELETE. These methods are often compared with the + CREATE, READ, UPDATE, DELETE (CRUD) operations associated with database + technologies. An analogy can also be made:</para> + + <itemizedlist> + <listitem> + <para>PUT is analogous to CREATE or PASTE OVER,</para> + </listitem> + + <listitem> + <para>GET to READ or COPY,</para> + </listitem> + + <listitem> + <para>POST to UPDATE or PASTE AFTER, and</para> + </listitem> + + <listitem> + <para>DELETE to DELETE or CUT.</para> + </listitem> + </itemizedlist> + + <para><command>Note</command>: RESTful architecture is not limited to + those methods, one of good examples of extension is the WebDAV + protocol.</para> + + <para>The <command>CRUD</command> (Create, Read, Update and Delete) verbs + are designed to operate with atomic data within the context of a database + transaction. REST is designed around the atomic transfer of a more complex + state and can be viewed as a mechanism for transferring structured + information from one application to another.</para> + + <para>HTTP separates the notions of a web server and a web browser. This + allows the implementation of each to vary from the other based on the + client/server principle. When used RESTfully, HTTP is + <command>stateless</command>. Each message contains all the information + necessary to understand the request.</para> + + <para>As a result, neither the client nor the server needs to remember any + communication-state between messages. Any state retained by the server + must be modeled as a resource..</para> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/overwrite-default-providers.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/overwrite-default-providers.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/overwrite-default-providers.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,213 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="WS.OverwriteDefaultProviders"> + <?dbhtml filename="overwrite-default-providers.html"?> + + <title>OverwriteDefaultProviders</title> + + <section> + <title>Motivation</title> + + <para>There is set of providers embedded in eXo JAX-RS + implementation.</para> + + <para>Implementations of MessageBodyReader and MessageBodyWriters are + taking care about serialization/deserialization of message body (HTTP + request/response's body).</para> + + <para>The next set of media and Java types processed automatically, thanks + to embedded Readers (Writers).</para> + + <table> + <title>Embedded Reader and Writers of message body</title> + + <tgroup cols="2"> + <colspec align="center" /> + + <thead> + <row> + <entry align="center">Media Type</entry> + + <entry align="center">Java Type</entry> + </row> + </thead> + + <tbody> + <row> + <entry>*/*</entry> + + <entry>byte[]</entry> + </row> + + <row> + <entry>*/*</entry> + + <entry>javax.activation.DataSource</entry> + </row> + + <row> + <entry>*/*</entry> + + <entry>java.io.File</entry> + </row> + + <row> + <entry>*/*</entry> + + <entry>java.io.InputStream</entry> + </row> + + <row> + <entry>*/*</entry> + + <entry>java.io.Reader</entry> + </row> + + <row> + <entry>*/*</entry> + + <entry>java.lang.String</entry> + </row> + + <row> + <entry>*/*</entry> + + <entry>javax.ws.rs.core.StreamingOutput (Writer ONLY)</entry> + </row> + + <row> + <entry>application/json</entry> + + <entry>1. Object with simple constructor + get/set methods; 2. + Java Collection (java.uitl.List&lt;T&gt;, java.uitl.Set&lt;T&gt;, + java.util.Map&lt;String, T&gt;, etc) where T as described in + 1.</entry> + </row> + + <row> + <entry>application/x-www-form-urlencoded</entry> + + <entry>javax.ws.rs.core.MultivaluedMap&lt;String, + String&gt;</entry> + </row> + + <row> + <entry>multipart/*</entry> + + <entry>java.util.Iterator&lt;org.apache.commons.fileupload.FileItem&gt;</entry> + </row> + + <row> + <entry>application/xml, application/xhtml+xml, text/xml</entry> + + <entry>javax.xml.bind.JAXBElement</entry> + </row> + + <row> + <entry>application/xml, application/xhtml+xml, text/xml</entry> + + <entry>Object with JAXB annotations</entry> + </row> + + <row> + <entry>application/xml, application/xhtml+xml, text/xml</entry> + + <entry>javax.xml.transform.stream.StreamSource</entry> + </row> + + <row> + <entry>application/xml, application/xhtml+xml, text/xml</entry> + + <entry>javax.xml.transform.sax.SAXSource</entry> + </row> + + <row> + <entry>application/xml, application/xhtml+xml, text/xml</entry> + + <entry>javax.xml.transform.dom.DOMSource</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>In some case it may be required to use alternative provider for the + same media and java type but such changes must not impact to any other + services.</para> + </section> + + <section> + <title>Usage</title> + + <para>To be able overwrite default JAX-RS provider(s) developer + need:</para> + + <orderedlist> + <listitem> + <para>Deploy own RESTful service(s) by using subclass of + javax.ws.rs.core.Application (hereinafter Application).</para> + </listitem> + + <listitem> + <para>Service(s) NOT NEED to implement marker interface + ResourceContainer and MUST NOT be configured as component(s) of eXo + Container. Instead of it Application must be configured as component + of eXo Container.</para> + </listitem> + + <listitem> + <para>If RESTful services or providers require some dependencies from + eXo Container then Application should inject it by own constructor and + then delegate to services or providers. As alternative method + getClasses() may be used for deliver services/providers classes + instead of instances. In this case services/providers will work in + per-request mode and RESTful framework will take care about resolving + dependencies.</para> + </listitem> + </orderedlist> + </section> + + <section> + <title>Example</title> + + <para>In example below see how to use Jackson JSON provider instead of + embedded in eXo RESTful framework.</para> + + <para>Create subclass of javax.ws.rs.core.Application with code as bellow + and add it to the eXo Container configuration.</para> + + <programlisting language="java">package org.exoplatform.test.jackson; + +import org.codehaus.jackson.jaxrs.JacksonJaxbJsonProvider; + +import java.util.HashSet; +import java.util.Set; + +import javax.ws.rs.core.Application; + +public class Application1 extends Application +{ + @Override + public Set&lt;Class&lt;?&gt;&gt; getClasses() + { + Set&lt;Class&lt;?&gt;&gt; cls = new HashSet&lt;Class&lt;?&gt;&gt;(1); + cls.add(Resource1.class); + return cls; + } + + @Override + public Set&lt;Object&gt; getSingletons() + { + Set&lt;Object&gt; objs = new HashSet&lt;Object&gt;(1); + objs.add(new JacksonJaxbJsonProvider()); + return objs; + } +}</programlisting> + + <para>In this example we assumes Resource1 is Java class which carries + JAX-RS annotations and it uses JSON. In this case RESTful framework will + use JacksonJaxbJsonProvider for serializing/deserializing of all messages + to/from Resource1. But it will not impact to other services in any kind. + </para> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/restservicelist-service.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/restservicelist-service.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/restservicelist-service.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,215 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="WS.RestServicesList"> + <?dbhtml filename="ch-ws-restserviceslist-service.html"?> + + <title>RestServicesList Service</title> + + <section> + <title>Overview.</title> + + <para>RestServicesList service is intendet to provide information about + rest services deployed to the application server.</para> + + <itemizedlist> + <listitem> + <para>Path - path to service</para> + </listitem> + + <listitem> + <para>Regex - service's URL regular expression</para> + </listitem> + + <listitem> + <para>FQN - full qualified name of service's class</para> + </listitem> + </itemizedlist> + + <para>The list can be provided in two formats: HTML and JSON.</para> + </section> + + <section> + <title>Usage</title> + + <note> + <para>Class does not implement + org.exoplatform.services.rest.resource.ResourceContainer and must never + be binded to RESTful framework by using eXoContainer. This service must + works as per-request resource.</para> + </note> + + <section> + <title>HTML format</title> + + <para>To get the list of services in HTML format use listHTML() + method:</para> + + <programlisting language="java">@GET +(a)Produces({MediaType.TEXT_HTML}) +public byte[] listHTML() +{ + ... +} </programlisting> + + <para>To do this, perform a simple GET request to the RestServicesList + link.</para> + + <para>f.e. curl -u root:exo http://localhost:8080/rest/ will return such + HTML code:</para> + + <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"&gt; +&lt;html xmlns="http://www.w3.org/1999/xhtml"&gt; + &lt;head&gt; + &lt;title&gt;eXo JAXRS Implementation&lt;/title&gt; + &lt;/head&gt; + &lt;body&gt; + &lt;h3 style="text-align:center;"&gt;Root resources&lt;/h3&gt; + &lt;table width="90%" style="table-layout:fixed;"&gt; + &lt;tr&gt; + &lt;th&gt;Path&lt;/th&gt; + &lt;th&gt;Regex&lt;/th&gt; + &lt;th&gt;FQN&lt;/th&gt; + &lt;/tr&gt; + &lt;tr&gt; + &lt;td&gt;script/groovy&lt;/td&gt; + &lt;td&gt;/script/groovy(/.*)?&lt;/td&gt; + &lt;td&gt;org.exoplatform.services.jcr.ext.script.groovy.GroovyScript2RestLoader&lt;/td&gt; + &lt;/tr&gt; + &lt;tr&gt; + &lt;td&gt;/lnkproducer/&lt;/td&gt; + &lt;td&gt;/lnkproducer(/.*)?&lt;/td&gt; + &lt;td&gt;org.exoplatform.services.jcr.webdav.lnkproducer.LnkProducer&lt;/td&gt; + &lt;/tr&gt; + &lt;tr&gt; + &lt;td&gt;/registry/&lt;/td&gt; + &lt;td&gt;/registry(/.*)?&lt;/td&gt; + &lt;td&gt;org.exoplatform.services.jcr.ext.registry.RESTRegistryService&lt;/td&gt; + &lt;/tr&gt; + &lt;tr&gt; + &lt;td&gt;/jcr&lt;/td&gt; + &lt;td&gt;/jcr(/.*)?&lt;/td&gt; + &lt;td&gt;org.exoplatform.services.jcr.webdav.WebDavServiceImpl&lt;/td&gt; + &lt;/tr&gt; + &lt;tr&gt; + &lt;td&gt;/&lt;/td&gt; + &lt;td&gt;(/.*)?&lt;/td&gt; + &lt;td&gt;org.exoplatform.services.rest.ext.service.RestServicesList&lt;/td&gt; + &lt;/tr&gt; + &lt;/table&gt; + &lt;/body&gt; +&lt;/html&gt; </programlisting> + + <para>If you perform the same request with your browser, you'll see the + table with the list of deployed services like this:</para> + + <table> + <title>Root resources</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Path</entry> + + <entry>Regex</entry> + + <entry>FQN</entry> + </row> + </thead> + + <tbody> + <row> + <entry>script/groovy</entry> + + <entry>/script/groovy(/.*)?</entry> + + <entry>org.exoplatform.services.jcr.ext.script.groovy.GroovyScript2RestLoader</entry> + </row> + + <row> + <entry>/lnkproducer/</entry> + + <entry>/lnkproducer(/.*)?</entry> + + <entry>org.exoplatform.services.jcr.webdav.lnkproducer.LnkProducer</entry> + </row> + + <row> + <entry>/registry/</entry> + + <entry>/registry(/.*)?</entry> + + <entry>org.exoplatform.services.jcr.ext.registry.RESTRegistryService</entry> + </row> + + <row> + <entry>/jcr</entry> + + <entry>/jcr(/.*)?</entry> + + <entry>org.exoplatform.services.jcr.webdav.WebDavServiceImpl</entry> + </row> + + <row> + <entry>/</entry> + + <entry>(/.*)?</entry> + + <entry>org.exoplatform.services.rest.ext.service.RestServicesList</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>JSON format</title> + + <para>To get the list of services in HTML format use listJSON() + method:</para> + + <programlisting language="java">@GET +(a)Produces({MediaType.APPLICATION_JSON}) +public RootResourcesList listJSON() +{ + ... +}</programlisting> + + <para>To do this, add "Accept:application/json" header to your GET + request</para> + + <para>f.e. curl -u root:exo http://localhost:8080/rest/ -H + "Accept:application/json" will return such JSON:</para> + + <programlisting>{"rootResources":[ + { + "fqn":"org.exoplatform.services.jcr.ext.script.groovy.GroovyScript2RestLoader", + "regex":"/script/groovy(/.*)?", + "path":"script/groovy" + }, + { + "fqn":"org.exoplatform.services.jcr.webdav.lnkproducer.LnkProducer", + "regex":"/lnkproducer(/.*)?", + "path":"/lnkproducer/" + }, + { + "fqn":"org.exoplatform.services.jcr.ext.registry.RESTRegistryService", + "regex":"/registry(/.*)?", + "path":"/registry/" + }, + { + "fqn":"org.exoplatform.services.jcr.webdav.WebDavServiceImpl", + "regex":"/jcr(/.*)?", + "path":"/jcr" + }, + { + "fqn":"org.exoplatform.services.rest.ext.service.RestServicesList", + "regex":"(/.*)?", + "path":"/" + } +]}</programlisting> + + <para></para> + </section> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/ws.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/ws.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws/ws.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id = "WS"> + <?dbhtml filename="ch-ws.html"?> + + <title>eXo Web Services</title> + + <section> + <title>eXo Web Services introduction</title> + + <para>The Web Services module allows eXo technology to integrate with + external products and services.</para> + + <para>It's implementaion of API for RESTful Web Services with extensions, + Servlet and cross-domain AJAX web-frameworks and JavaBean-JSON + transformer.</para> + </section> +</chapter> Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/eXoJCR/ws.xml 2011-11-01 04:44:39 UTC (rev 7917) @@ -0,0 +1,27 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<part> + <?dbhtml filename="part-ws.html"?> + + <title>eXoWS</title> + + <xi:include href="ws/ws.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="ws/introduction-to-rest.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="ws/overwrite-default-providers.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="ws/restservicelist-service.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="ws/groovy-scripts-as-rest-services.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="ws/framework-for-cross-domain-ajax.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</part>