May 2013 - gatein-commits - Jboss List Archives

gatein SVN: r9283 - epp/docs/JPP/trunk/Development_Guide/en-US.

by do-not-reply＠jboss.org

Author: aakanksha_writer Date: 2013-05-31 07:53:58 -0400 (Fri, 31 May 2013) New Revision: 9283 Added: epp/docs/JPP/trunk/Development_Guide/en-US/OAuth_Provider_API.xml Log: new content added Added: epp/docs/JPP/trunk/Development_Guide/en-US/OAuth_Provider_API.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/OAuth_Provider_API.xml ___________________________________________________________________ Added: svn:mime-type + application/xml

11 years, 6 months

1
0
0 / 0

gatein SVN: r9282 - epp/docs/JPP/trunk/Development_Guide/en-US.

by do-not-reply＠jboss.org

Author: aakanksha_writer Date: 2013-05-31 07:52:47 -0400 (Fri, 31 May 2013) New Revision: 9282 Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Architectural_Choices.xml epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.xml epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.xml~ epp/docs/JPP/trunk/Development_Guide/en-US/Navigation.xml epp/docs/JPP/trunk/Development_Guide/en-US/Page.xml epp/docs/JPP/trunk/Development_Guide/en-US/PortalRequest_and_Portal.xml epp/docs/JPP/trunk/Development_Guide/en-US/Site.xml Log: new content added Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Architectural_Choices.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.xml 2013-05-22 05:52:42 UTC (rev 9281) +++ epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.xml 2013-05-31 11:52:47 UTC (rev 9282) @@ -15,10 +15,12 @@ </part> <part> <title>Portal API</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Introduction_Portal_API.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalRequest_and_Portal.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Site.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Navigation.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Page.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="OAuth_Provider_API.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="REST_API.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="OrganizationAPI.xml" encoding="UTF-8"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AccessingUserProfile.xml" encoding="UTF-8"/> Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.xml~ =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Navigation.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Page.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/PortalRequest_and_Portal.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Site.xml =================================================================== (Binary files differ)

11 years, 6 months

1
0
0 / 0

gatein SVN: r9281 - in epp/docs/JPP/trunk: Administration_and_Configuration_Guide/en-US/images and 3 other directories.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-05-22 01:52:42 -0400 (Wed, 22 May 2013) New Revision: 9281 Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/WSRP.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_create.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_end.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_init.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_missing.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_refresh.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_self.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wsdl.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wss_selected.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/consumer_operations.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration_warning.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_done.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_list.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_portlet_list.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_modified_page.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_original_page.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_selected_page.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_start.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_success.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_end.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_modify.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self_end.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_start.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_blank.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_default.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_email.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_registration.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets_category.png Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.ent epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/WSRP.xml epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml Log: Added missing graphics and WSRP section to the Admin Config Guide for Aakanksha to view. Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.ent =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.ent 2013-05-16 04:35:34 UTC (rev 9280) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.ent 2013-05-22 05:52:42 UTC (rev 9281) @@ -14,3 +14,4 @@ <!ENTITY VX "6"> <!ENTITY VY "6.1"> <!ENTITY VZ "6.1.0"> +<!ENTITY WSRP_VERSION "2.2.2.Final"> Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml 2013-05-16 04:35:34 UTC (rev 9280) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml 2013-05-22 05:52:42 UTC (rev 9281) @@ -1,5 +1,6 @@ <?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" [ +<!ENTITY WSRP_VERSION ''> <!ENTITY % BOOK_ENTITIES SYSTEM "Administration_and_Configuration_Guide.ent"> %BOOK_ENTITIES; ]> @@ -38,5 +39,2317 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Internationalization_Configuration.xml" encoding="UTF-8"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Localization_Configuration.xml" encoding="UTF-8"/> </part> + <part> + <title>Web Services for Remote Portlets</title> + <chapter id="wsrp-Introduction"> + <title>Introduction</title> + <remark>https://docs.jboss.org/author/display/GTNPORTAL35/Web+Services+for+Remote...</remark> + <para>The Web Services for Remote Portlets specification defines a web service interface for accessing and + interacting with interactive presentation-oriented web services. It has been produced through the efforts of + the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is based on the requirements + gathered and on the concrete proposals made to the committee. + </para> + <para>Scenarios that motivate WSRP functionality include: + </para> + <itemizedlist> + <listitem> + <para>Content hosts, such as portal servers, providing Portlets as presentation-oriented web services + that can be used by aggregation engines. + </para> + </listitem> + <listitem> + <para>Aggregating frameworks, including portal servers, consuming presentation-oriented web services + offered by content providers and integrating them into the framework. + </para> + </listitem> + </itemizedlist> + <para>More information on WSRP can be found on the + <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp">official website for WSRP</ulink>. + Further suggested reading is the + <ulink url="http://www.oasis-open.org/committees/download.php/10539/wsrp-primer-1.0.html">primer</ulink> + for a good, albeit technical, overview of WSRP. + </para> + </chapter> + <chapter id="wsrp_support"> + <title>Level of support in JBoss Portal Platform</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Level+of+support</remark> + <para>The WSRP Technical Committee defined + <ulink url="http://www.oasis-open.org/committees/download.php/3073">WSRP Use Profiles</ulink> + to help with WSRP interoperability. This section will refer to terms defined in that document. + </para> + <para>JBoss Portal Platform provides a Simple level of support for the WSRP Producer except that out-of-band registration + is not currently handled. In-band registration and persistent local state (which are + defined at the Complex level) are supported. + </para> + <para>On the Consumer side, JBoss Portal Platform provides a Medium level of support for WSRP, except that the consumer only handles + HTML markup (because JBoss Portal Platform itself does not handle other markup types). The platform does support explicit portlet + cloning and it fully supports the PortletManagement interface. + </para> + <para>As far as caching goes, the component has Level 1 Producer and Consumer. Cookie handling is supported properly on the + Consumer and the Producer requires initialization of cookies (it has been found that it improves interoperability + with some consumers). The component does not support custom window states or modes, as JBoss Portal Platform does not. The component does, + however, support CSS on both the Producer (though it is more a function of the portlets than inherent Producer + capability) and Consumer. + </para> + <para>While a complete implementation of WSRP 1.0 is provided, the community developers do need to go through the + <ulink url="http://www.oasis-open.org/committees/download.php/6018">Conformance statements</ulink> + and perform more interoperability testing (an area that needs to be better supported by the WSRP Technical + Committee and Community at large). + </para> + <para>JBoss Portal Platform supports WSRP 2.0 with a complete implementation of the non-optional features. The only + features not implemented are support for lifetimes and leasing + support. + </para> + <note> + <title>Note</title> + <para>As of version &VZ; of JBoss Portal Platform, WSRP is only activated and supported +using JBoss Portal Platform deployed on JBoss Enterprise Application Platform 6. + </para> + </note> + </chapter> + <chapter id="Deploying_JPP_WSRP_Services"> + <title>Deploying JBoss Portal Platform's WSRP services</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Deploying+GateIn%27s+WS...</remark> + <para> +JBoss Portal Platform provides complete support for WSRP 1.0 and 2.0 standard interfaces, and offers both consumer and + producer services. Starting with version 2.1.0-GA of the component, WSRP is packaged as a JBoss Portal Platform + extension, and is self-contained in a package named + <filename><replaceable>JPP_HOME</replaceable>/gatein/extensions/gatein-wsrp-integration.ear</filename> +. +</para> + <para>The only files of interest from a user perspective +are located in the + <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/wsrp</filename> +directory.</para> + <itemizedlist> + <listitem> + <para><filename>gatein-wsse-consumer.xml</filename>, which controls WS-Security support for the consumer.</para> + </listitem> + <listitem> + <para><filename>gatein-wsse-producer.xml</filename> which controls WS-Security support for + the producer.</para> + </listitem> + </itemizedlist> + <para>See + <xref linkend="wss_configuration"/> section for configuration required in these files. </para> + <para> + The extension itself is composed of the following components: + </para> + <itemizedlist> + <listitem> + <para> + <filename>META-INF</filename> + contains files necessary for EAR packaging. + </para> + </listitem> + <listitem> + <para> + The <filename>extension-component-&VZ;.jar</filename>, which contains the components needed to + integrate the WSRP component into JBoss Portal Platform. It also includes the default configuration files for + the WSRP producer and the default WSRP consumers. + </para> + </listitem> + <listitem> + <para> + The <filename>extension-config-&VZ;.jar</filename>, which contains the configuration file + needed by the GateIn extension mechanism to properly register this EAR as an extension. + </para> + </listitem> + <listitem> + <para> + The <filename>extension-war-&VZ;.war</filename>, which contains the configuration files + needed by the portal extension mechanism to properly setup the WSRP service. It includes + <filename>wsrp-configuration.xml</filename> + which, in particular, configures several options for the + <code>WSRPServiceIntegration</code> + component at the heart of the WSRP integration in JBoss Portal Platform. + </para> + </listitem> + <listitem> + <para> + The <filename>lib</filename> directory, which contains the different libraries needed by the WSRP service. + </para> + </listitem> + <listitem> + <para> + The <filename>wsrp-admin-gui-&WSRP_VERSION;.war</filename>, which contains the WSRP Configuration portlet + with which you can configure consumers to access remote servers and how the WSRP producer is + configured. + </para> + </listitem> + <listitem> + <para> + The <filename>wsrp-producer-jb5wsss-&WSRP_VERSION;.war</filename>, which contains the producer-side + support for WS-Security. + </para> + </listitem> + </itemizedlist> + <para> + If you are not going to use WSRP in JBoss Portal Platform, it will not adversely affect your installation to leave it + as is. Otherwise, you can just remove the + <filename>gatein-wsrp-integration.ear</filename> + file from your AS deploy directory. + </para> + <section id="wsrp-ports"> + <title>Considerations to use WSRP when running JBoss Portal Platform on a non-default port or hostname</title> + <para> + The web service stack that JBoss Portal Platform uses is based on JBoss WS. It updates the port and host name used in WSDL. For more information, refer to the <citetitle>Web Services</citetitle> chapter in the JBoss Enterprise Application Platform 6 <citetitle>Administration and Configuration User Guide</citetitle>. + </para> + <para>If you have modified the host name and port on which your server runs, you will + need to + update the configuration for the consumer used to consume JBoss Portal Platform's 'self' producer. </para> + </section> + </chapter> + <chapter id="Securing_WSRP"> + <title>Securing WSRP</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>There are two main ways to secure the communication between a producer and consumer:</para> + <orderedlist> + <listitem> + <para> + <emphasis role="underline">Securing the Transport Layer</emphasis> + + This requires using SSL and a HTTPS endpoint. By using this, the communication between the consumer and producer will be encrypted. + </para> + </listitem> + <listitem> + <para> + <emphasis role="underline">Securing the Contents of the SOAP message</emphasis> + + This option requires using ws-security to handle parts of the SOAP message. With this option you can specify things like encryption, signing, timestamps, etc as well as passing across user credentials to perform a login on the producer side. WS-Security is more powerful and has more options, but is requires more complex configurations. + </para> + </listitem> + </orderedlist> + <para>Depending on requirements, an HTTPs endpoint and/or ws-security can be used.</para> + <section id="WSRP_over_SSL_HTTPS_Endpoints"> + <title>WSRP over SSL with HTTPS endpoints</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para> + It is possible to use WSRP over SSL for a secure exchange of data. Since JBoss Portal Platform does not come initially configured for HTTPS connectors, we will need to configure the producer's server for this first. This is a global configuration change, and will affect more than just the portal and WSRP. Refer to the +JBoss Enterprise Application Platform 6 <citetitle>Administration and Configuration Guide</citetitle> for instructions about how to configure HTTPS connectors for the server. + </para> + <para> + Once the producer is configured for HTTPS connections, on the consumer you will just need to modify the URL for the WSRP endpoint to point to the new HTTPS based URL. This will require either manually updating the value in the WSRP administration application, or by specifying it using the + <emphasis role="italics">wsrp-consumers-config.xml</emphasis> + configuration file before the server is first started. + </para> + <section id="sid-54264620_SecuringWSRP-SampleConfigurationForEnablingSSLWithWSRP"> + <title>Sample Configuration For Enabling SSL With WSRP</title> + <remark>Sources: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <warning> + <para> + The following procedures are provided as an example of configuring HTTPS/SSL with WSRP. </para> + <para>It is not meant to show best practices for configuring HTTPS with the platform, and does things which should not be used in a production server (such as self-signed certificates). Refer to the JBoss Enterprise Application Platform 6 product documentation for detailed, best practice configuration guidelines. + </para> + </warning> + <procedure> + <title>Configure the Producer to Use HTTPS</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>Configure the producer's server to use HTTPS. This is handled in the same manner that you would configure any JBoss Enterprise Application server for HTTPS.</para> + <step> + <para>Generate the keystore for the producer by executing the following command.</para> + <programlisting>keytool -genkey -alias tomcat -keyalg RSA -keystore producerhttps.keystore -dname "cn=localhost" -keypass changeme -storepass changeme</programlisting> + </step> + <step> + <para> + Configure the server to add an HTTPS connection. This requires modifying the + <emphasis role="italics">standalone/configuration/standalone.xml</emphasis> + file with the following content in bold: + </para> + <programlisting> + <subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false"> + + <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/> + + <emphasis role="strong"><connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true"></emphasis> + + <emphasis role="strong"><ssl certificate-key-file="/path/to/producerhttps.keystore" password="changeme"/></emphasis> + + <emphasis role="strong"></connector></emphasis> + + <virtual-server name="default-host" enable-welcome-root="true"> + + <alias name="localhost"/> + + <alias name="example.com"/> + + </virtual-server> + + ...</programlisting> + </step> + <step> + <para> + Start the server and verify that + <ulink url="https://localhost:8443/portal"/> + is accessible. Note that since you are using a self-signed certificate that your browser will give a warning that the certificate cannot be trusted. + </para> + <note> + <para>In this example case we are accessing the portal using 'localhost' hence why we are using "cn=localhost" in the keytool command. If you are using this across another domain, you will need to make the necessary changes.</para> + </note> + </step> + </procedure> + <procedure> + <title>Configure the Consumer to Access the WSRP Endpoint over HTTPS</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <step> + <para>Export the producer's public key from the producer's keystore</para> + <programlisting>keytool -export -alias tomcat -file producerkey.rsa -keystore producerhttps.keystore -storepass changeme</programlisting> + </step> + <step> + <para>Import the producer's public key into a new keystore for the consumer</para> + <programlisting>keytool -import -alias tomcat -file producerkey.rsa -keystore consumerhttps.keystore -storepass changeme -noprompt</programlisting> + </step> + <step> + <para> + Configure the + <emphasis role="italics">bin/standalone.conf</emphasis> + file to add the following line at the end of the file: + </para> + <programlisting>JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=/path/to/consumerhttps.keystore -Djavax.net.ssl.trustStorePassword=changeme"</programlisting> + </step> + <step> + <para> + Start the consumer and change the selfv2 producer url to + <ulink url="https://localhost:8443/wsrp-producer/v2/MarkupService?wsdl"/> + and verify that the consumer can access the producer. + </para> + </step> + </procedure> + <note> + <para> + It is possible to modify the + <emphasis role="italics">wsrp-consumers-config.xml</emphasis> + configuration file to change the URL instead of modifying it in the administration GUI. + </para> + </note> + <para> + It is possible to use WSRP over SSL for secure exchange of data. Configure your server appropriately as described in the <citetitle>HTTPS Configuration</citetitle> section of the <citetitle>Installation Guide</citetitle>. + </para> + </section> + </section> + <section id="WSRP_and_WS-Security"> + <title>WSRP and WS-Security</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>Portlets may present different data or options depending on the currently authenticated user. For remote + portlets, this means having to propagate the user credentials from the consumer back to the producer in + a safe and secure manner. The WSRP specification does not directly specify how this should be + accomplished, but delegates this work to the existing WS-Security standards. The WS-Security standards can also be used to secure the soap message, such as encryption and signing the message. + </para> + <warning> + <title>Encryption is strongly recommended</title> + <para>Encrypt the credentials being sent between the consumer and producer, otherwise they + will be sent in plain text and could be easily intercepted. Configure WS-Security to + encrypt and sign the SOAP messages being sent, or secure the transport layer by using an HTTPS endpoint. + Failure to encrypt the soap message or transport layer will result in the username and password being + sent in plain text. + </para> + </warning> + <note> + <title>Web Container Compatibility</title> + <para>WSRP and WS-Security is only supported on JBoss Portal Platform when running on JBoss Enterprise Application Platform 6. + </para> + </note> + </section> + <section id="wsrp-Credentials"> + <title>Credentials</title> + <para>When the consumer sends the user credentials to the producer, it is sending the credentials for the + currently authenticated user in the consumer. This makes signing in to remote portlets transparent + to end users, but also requires that the producer and consumer use the same credentials. This means + that the username and password must be the same and valid on both servers. + </para> + <para>The recommended approach for this situation would be to use a common LDAP configuration. See chapter LDAP_Integration in the Administration and Configuration guide to correctly configure LDAP on JBoss Portal Platform. </para> + <section id="wss_configuration"> + <title><remark>BZ#839355 </remark>WS-Security Configuration</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <section id="sid-54264620_SecuringWSRP-Introduction"> + <title>Introduction</title> + <para>JBoss Enterprise Application Platform 6 uses a different web service implementation than the previous versions: it is now uses the JBossWS CXF Stack instead of the JBossWS Native Stack. Due to these changes, the way we configure WS-Security for WSRP with JBoss Portal Platform on JBoss Enterprise Application Platform 6 has changed.</para> + <note> + <para>We only support one ws-security configuration option for the producer. All consumers accessing the producer will have to conform to this security constraint. This means if the producer requires encryption, all consumers will be required to encrypt their messages when accessing the producer.</para> + <para>We only support one ws-security configuration option to be used by all the consumers. A consumer has the option to enable or disable ws-security, which allows for one or more consumers to use ws-security while the others do not.</para> + </note> + </section> + <section id="sid-54264620_SecuringWSRP-Overview"> + <title>Overview</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>CXF uses interceptors to extend and configure its behavior. There are two main types of interceptors: <firstterm>inInterceptors</firstterm> and <firstterm>outInterceptors</firstterm>. InInterceptors are invoked for communication coming into the client or server, while outInterceptors are invoked when the client or server sends a message.</para> + <para>So for the WSRP case, the communication from the consumer to the producer is governed by the consumer's OutInterceptor and the producer's InInterceptors. The communication from the producer to the consumer is governed by the producer's OutInterceptor and the consumer's InInterceptor. This may mean having to configure 4 Interceptors.</para> + <para>When dealing with user propagation, only the consumer sends the user credentials to the producer. So Username Tokens only need to be configured for the consumer's OutInterceptor and the producer's InInterceptor.</para> + <para>When dealing with things like encryption, you will most likely want to encrypt the message from the consumer to the producer and also the message from the producer to the consumer. This means that encryption properties must be configured for all 4 interceptors.</para> + <para> + Please see the CXF Documentation for more details on interceptors and their types: + <ulink url="http://cxf.apache.org/docs/interceptors.html"/> + </para> + <para> + To support ws-security, JBoss Portal Platform 6 uses CXF's WSS4J Interceptors which handle all ws-security related tasks. Please see the CXF Documentation for more details: + <ulink url="http://cxf.apache.org/docs/ws-security.html"/> + </para> + </section> + </section> + <section id="WSS4J_Interceptors_and_WSRP"> + <title>WSS4J Interceptors and WSRP</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>The WSS4J Interceptors are configured using using simple property files. + +WSRP looks for specific property files to know whether or not in/out interceptors must be added and configured for either consumers or producer. </para> + <para>Theses files are located in the standalone/configuration/jpp/wsrp/cxf/ws-security directory of your the JBoss Enterprise Application Server 6 home directory. </para> + <para>Consumer-specific files are in the consumer subdirectory while producer-specific files should be located in the producer subdirectory. To add and configure a WSS4J interceptor, you just need to add the proper configuration file in the proper directory. If no configuration file is found for a specific interceptor type, then no such interceptor will be added. </para> + <para>"In" interceptors are configured using WSS4JInInterceptor.properties files while "out" interceptors are configured using WSS4JOutInterceptor.properties files. +</para> + <table frame="all"> + <title>Files needed to configure interceptor for WSRP</title> + <tgroup cols="3" align="justify"> + <colspec colnum="1" colname="c1" colwidth="100"/> + <colspec colnum="2" colname="c2" colwidth="150"/> + <colspec colnum="3" colname="c3" colwidth="400"/> + <thead> + <row> + <entry>Side</entry> + <entry>Interceptor Type</entry> + <entry>Configuration File</entry> + </row> + </thead> + <tbody> + <row> + <entry>Consumer</entry> + <entry>IN</entry> + <entry> + <filename>standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JInInterceptor.properties</filename> + </entry> + </row> + <row> + <entry/> + <entry>OUT</entry> + <entry> + <filename>standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JOutInterceptor.properties</filename> + </entry> + </row> + <row> + <entry>Producer</entry> + <entry>IN</entry> + <entry> + <filename>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/WSS4JInInterceptor.properties</filename> + </entry> + </row> + <row> + <entry/> + <entry>OUT</entry> + <entry> + <filename>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/WSS4JOutInterceptor.properties</filename> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para>Please refer to the CXF or WSS4J documentation for instructions and options available for each type of interceptors.</para> + <section> + <title>User Propagation</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>User propagation can be configured to be used over WSRP with ws-security. What this means is that a user logged into a consumer can have their credentials propagated over to the producer. This allows the producer to authenticate the user and any portlet on the producer (a remote portlet from the consumer's perspective) will view the user as being properly authenticated. This allows for remote portlets to access things like user information.</para> + <para><note> + <para>This only works if the user's credentials on the producer and consumer are the same. This may require using a common authentication mechanism, such as LDAP.</para> + <para>This requires some special options when configuring the producer and server.</para> + </note></para> + </section> + </section> + <section> + <title><remark>BZ#839355</remark>WS-Security Consumer Configuration</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para> + In order to configure ws-security on the consumer side, you will have to configure the WSS4J Interceptors as seen above. This will require having to configure the WSS4JInInterceptor and/or WSS4JOutInterceptor. + + You will also need to check the 'Enable WS-Security' checkbox on the WSRP Admin Portlet for the consumer configuration to take effect. + </para> + <figure> + <title id="fig-WSRP_Consumers_Configuration">WSRP Consumers Configuration</title> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_wss_selected.png" format="PNG"/> + </imageobject> + </mediaobject> + </figure> + <section> + <title>Special JBoss Portal Platform Configuration Options for User Propagation</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>In order to handle user propagation in JBoss Portal Platform across ws-security, a couple of special configuration options have been created which should be applied to the consumer's WSS4JOutInterceptor.</para> + <section> + <title>Custom 'user' option</title> + <para><informalexample> + <programlisting>user=gtn.current.user</programlisting> + <para>This option sets the 'user' property to the currently authenticated user on the consumer.</para> + </informalexample></para> + </section> + <section> + <title>Custom 'action' option</title> + <para><informalexample> + <programlisting>action=gtn.UsernameToken.ifCurrentUserAuthenticated</programlisting> + <para>If a user is currently authenticated, it will replace the 'gtn.UsernameToken.ifCurrentUserAuthenticated' with 'UsernameToken'. If the current user is an unauthenticated user, 'gtn.UsernameToken.ifCurrentUserAuthenticated' will be removed from the action list. If no other actions are specified, then the WSS4J interceptor will not be added to the consumer. This allows you to only use ws-security when dealing with authenticated users, and not for anonymous users.</para> + </informalexample><note> + <para>This requires that the user option is set to 'gtn.current.user'</para> + </note></para> + </section> + <section> + <title>Custom PasswordCallbackClass</title> + <para>To set the password for the username token, we need to specify the password in a callback class. See the cxf ws-security documentation for more details <ulink url="http://cxf.apache.org/docs/ws-security.html"/></para> + <para>A special callback class has already been created which handles this for you: CurrentUserPasswordCallback. This class will retrieve the currently authenticated user's password and set this as the password in the callback object.</para> + <para><informalexample> + <programlisting>passwordCallbackClass=org.gatein.wsrp.wss.cxf.consumer.CurrentUserPasswordCallback</programlisting> + </informalexample></para> + </section> + </section> + </section> + <section id="sid-54264620_SecuringWSRP-ProducerConfiguration"> + <title>Producer Configuration</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>The configuration of the producer is similar to that of the consumer. It also requires having to configure the WSS4JInInterceptor and/or WSS4JOutInterceptor.</para> + <section> + <title>Special Configuration Options for User Propagation</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para> + To properly propagate user information on the producer-side, you will need to use GTNSubjectCreatingInterceptor instead of a regular WSS4JInInterceptor. This JBoss Portal Platform specific "in" interceptor is an extension of the traditional WSS4JInInterceptor and therefore can be configured similarly and accept the same configuration properties. To specify that you want to use the GTNSubjectCreatingInterceptor, please create a property file at + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/GTNSubjectCreatingInterceptor.properties</code> + instead of the regular WSS4JInInterceptor.properties file. + </para> + <para>This Interceptor will handle the ws-security headers and retrieve the users credentials. It will then use these credentials to perform a login on the producer site, thus authenticating the user on the producer and makes the user available to remote portlets.</para> + <note> + <para>This class also extends org.jboss.wsf.stack.cxf.security.authentication.SubjectCreatingInterceptor and can accept the same properties this class normally accepts. See the JBossWS documentation for options and more information.</para> + </note> + </section> + <section> + <title>Custom 'action' option</title> + <informalexample> + <programlisting>action=gtn.UsernameToken.ifAvailable</programlisting> + </informalexample> + <para>When this option is activated, the interceptor will set the action to 'UsernameToken' when the received SOAP message contains ws-security headers. If no ws-security header is included in the message, then no action is taken and the interceptor is not run. This is useful for dealing with authenticated and unauthentcated users trying to access the producer.</para> + </section> + </section> + <section id="sid-54264620_SecuringWSRP-SampleConfigurationusingtheUsernameTokenandUserPropagation"> + <title>Sample Configuration using the UsernameToken and User Propagation</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <warning> + <para>This example configuration does not encrypt the message. This means the username and password will be sent between the producer and consumer in plain text. This is a security concern and is only being shown as a simple example. It is up to administrators to properly configure the WSS4J Interceptors to encrypt messages or to only use https communication between the producer and consumer.</para> + </warning> + <section> + <title>Producer Setup</title> + <orderedlist> + <listitem> + <para> + create the following file: + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/GTNSubjectCreatingInterceptor.properties</code> + </para> + </listitem> + <listitem> + <para> + set the content of + <code>GTNSubjectCreatingInterceptor.properties</code> + created in step 1 to: + </para> + <informalexample> + <programlisting>action=gtn.UsernameToken.ifAvailable</programlisting> + </informalexample> + </listitem> + <listitem> + <para>start the producer server</para> + </listitem> + </orderedlist> + </section> + <section> + <title>Consumer Setup</title> + <orderedlist> + <listitem> + <para> + create the following file: + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JOutInterceptor.properties</code> + </para> + </listitem> + <listitem> + <para> + set the content of the + <code>WSS4JOutInterceptor.properties</code> + created in step 1 to: + </para> + <informalexample> + <programlisting>passwordType=PasswordText +user=gtn.current.user +action=gtn.UsernameToken.ifCurrentUserAuthenticated +passwordCallbackClass=org.gatein.wsrp.wss.cxf.consumer.CurrentUserPasswordCallback</programlisting> + </informalexample> + </listitem> + <listitem> + <para>start the consumer server</para> + </listitem> + <listitem> + <para>in the WSRP admin portlet, click the 'enable ws-security' checkbox</para> + </listitem> + <listitem> + <para>access a remote portlet (for example, the user identity portlet included as an example portlet in JBoss Portal Platform) and verify that the authenticated user is the same as the one on the consumer</para> + </listitem> + </orderedlist> + </section> + </section> + <section id="sid-54264620_SecuringWSRP-SampleConfigurationSecuringtheEndpointsusingEncryptionandSigning"> + <title>Sample Configuration Securing the Endpoints using Encryption and Signing</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>The following steps outline how to configure the producer and consumer to encrypt and sign SOAP messages passed between the producer and consumer. This example only deals with SOAP messages being sent between the producer and consumer, and not with user propagation.</para> + <note> + <para> + Some of the configuration options specified here are based on the content at + <ulink url="http://cxf.apache.org/docs/ws-security.html"/> + and + <ulink url="http://www.jroller.com/gmazza/entry/cxf_x509_profile"/> + More information may be available at these sites. + </para> + </note> + <section> + <title>Password Callback Class</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>WSS4J uses a Java class to specify the password when performing any security related actions. For the purpose of these encryption and signing examples, we will use the same password for the producer's and consumer's keystore (wsrpAliasPassword). This simplifies things a bit as it means we can use just one password callback class for both the producer and consumer.</para> + <para> + Example + <code>test.TestCallbackHandler</code> + class: + </para> + <informalexample> + <programlisting>package test; +  +import java.io.IOException; +import javax.security.auth.callback.Callback; +import javax.security.auth.callback.CallbackHandler; +import javax.security.auth.callback.UnsupportedCallbackException; +  +import org.apache.ws.security.WSPasswordCallback; +import org.gatein.wsrp.wss.cxf.consumer.CurrentUserPasswordCallback; +  +public class TestCallbackHandler implements CallbackHandler +{ +  +    @Override +    public void handle(Callback[] callbacks) throws IOException, +            UnsupportedCallbackException +    { +  +        //First check if we have any user name token call backs to add. +        //NOTE: only needed if using username tokens, and you want the currently authenticated users password added +        CurrentUserPasswordCallback currentUserPasswordCallback = new CurrentUserPasswordCallback(); +        currentUserPasswordCallback.handle(callbacks); +  +        for (Callback callback: callbacks) +        { +            if (callback instanceof WSPasswordCallback) +            { +                WSPasswordCallback wsPWCallback = (WSPasswordCallback)callback; +                // since the CurrentUserPasswordCallback already handles the USERNAME_TOKEN case, we don't want to set it in this case +                if (wsPWCallback.getUsage() != WSPasswordCallback.USERNAME_TOKEN) +                { +                    wsPWCallback.setPassword("wsrpAliasPassword"); +                } +            } +        } +    } +}</programlisting> + </informalexample> + <note> + <para> + CallbackHandler implementations are provided to JBoss Portal Platform using the standard Java + <ulink url="http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html">ServiceLoader</ulink> + infrastructure. As such, CallbackHandler implementations need to be bundled in a jar containing a file + <code>META-INF/services/javax.security.auth.callback.CallbackHandler</code> + specifying the fully qualified name of the CallbackHandler implementation class. This jar then needs to be put in the + <code>gatein/extensions</code> + directory of your JBoss Portal Platform installation. + </para> + </note> + <para> + You can see a working example of a CallbackHandler implentation at + <ulink url="https://github.com/gatein/gatein-wsrp/tree/master/examples/wss-callback"/> + </para> + </section> + <section> + <title>Configuring the Keystores</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <note> + <para>In this example we are making it a bit easier by specifying the same keystore password for both the producer and consumer, as they can use the same password callback class.</para> + </note> + <orderedlist> + <listitem> + <para>Generate the producer's private encryption keys</para> + <informalexample> + <programlisting>keytool -genkey -alias producerAlias -keypass wsrpAliasPassword -keystore producer.jks -storepass keyStorePassword -dname "cn=producerAlias" -keyalg RSA</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Export the producer's public key</para> + <informalexample> + <programlisting>keytool -export -alias producerAlias -file producerkey.rsa -keystore producer.jks -storepass keyStorePassword</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Generate the consumer's private encryption keys</para> + <informalexample> + <programlisting>keytool -genkey -alias consumerAlias -keypass wsrpAliasPassword -keystore consumer.jks -storepass keyStorePassword -dname "cn=consumerAlias" -keyalg RSA</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Export the consumer's public key</para> + <informalexample> + <programlisting>keytool -export -alias consumerAlias -file consumerkey.rsa -keystore consumer.jks -storepass keyStorePassword</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Import the consumer's public key into the producer's keystore</para> + <informalexample> + <programlisting>keytool -import -alias consumerAlias  -file consumerkey.rsa -keystore producer.jks -storepass keyStorePassword -noprompt</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Import the producer's public key into the consumer's keystore</para> + <informalexample> + <programlisting>keytool -import -alias producerAlias  -file producerkey.rsa -keystore consumer.jks -storepass keyStorePassword -noprompt</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + Copy the + <code>producer.jks</code> + file to the + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer</code> + directory on the producer + </para> + </listitem> + <listitem> + <para> + Copy the + <code>consumer.jks</code> + file to the + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/consumer</code> + directory on the consumer + </para> + </listitem> + </orderedlist> + </section> + <section> + <title>Configuring the Producer</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <orderedlist> + <listitem> + <para> + Create + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/WSS4JInInterceptor.properties</code> + with the following content. This will configure the incoming message between the producer and the consumer + </para> + <informalexample> + <programlisting>action=Signature Encrypt Timestamp +signaturePropFile=producer-security.properties +decryptionPropFile=producer-security.properties +passwordCallbackClass=test.TestCallbackHandler</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + Create + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/WSS4JOutInterceptor.properties</code> + with the following content. This will configure the outgoing message between the producer and the consumer + </para> + <informalexample> + <programlisting>action=Signature Encrypt Timestamp +signaturePropFile=producer-security.properties +encryptionPropFile=producer-security.properties +passwordCallbackClass=test.TestCallbackHandler +user=producerAlias +encryptionUser=consumerAlias +signatureUser=producerAlias</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + Create + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/producer-security.properties</code> + with the following content: + </para> + <informalexample> + <programlisting>org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=keyStorePassword +org.apache.ws.security.crypto.merlin.file=producer.jks</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + The + <code>passwordCallbackClass</code> + property in these configuration files needs to match the fully qualified name of your CallbackHandler implementation class. In our case, it is + <code>test.TestCallbackHandler</code> + . + </para> + </listitem> + </orderedlist> + </section> + <section> + <title>Configuring the Consumer</title> + <remark>Source: </remark> + <orderedlist> + <listitem> + <para> + Create standalone/ + <code>configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JOutInterceptor.properties</code> + with the following content. This will configure the outgoing message between the consumer and the producer + </para> + <informalexample> + <programlisting>action=Signature Encrypt Timestamp +signaturePropFile=consumer-security.properties +encryptionPropFile=consumer-security.properties +passwordCallbackClass=test.TestCallbackHandler +user=consumerAlias +encryptionUser=producerAlias +signatureUser=consumerAlias</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + Create standalone/ + <code>configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JInInterceptor.properties</code> + with the following content. This will configure the incoming message between the consumer and the producer + </para> + <informalexample> + <programlisting>action=Signature Encrypt Timestamp +signaturePropFile=consumer-security.properties +decryptionPropFile=consumer-security.properties +passwordCallbackClass=test.TestCallbackHandler</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Create standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/consumer-security.properties with the following content:</para> + <informalexample> + <programlisting>org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=keyStorePassword +org.apache.ws.security.crypto.merlin.file=consumer.jks</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + The + <code>passwordCallbackClass</code> + property in these configuration files needs to match the fully qualified name of your CallbackHandler implementation class. In our case, it is + <code>test.TestCallbackHandler</code> + . + </para> + </listitem> + </orderedlist> + </section> + </section> + <section> + <title>Sample Configuration using UsernameToken, Encryption and Signing with User Propagation</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para>The following steps outline how to configure the producer and consumer to encrypt and sign the soap message as well as use user propagation between the producer and consumer.</para> + <section> + <title>Configure the Producer</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para> + Follow the steps outlined in the + <link linkend="sid-54264620_SecuringWSRP-SampleConfigurationSecuringtheEndpointsusingEncryptionandSigning">Sample Configuration Securing the Endpoints using Encryption and Signing</link> + section but make the following changes: + </para> + <orderedlist> + <listitem> + <para> + rename the + <code>WSS4JInInterceptor.properties</code> + file to + <code>GTNSubjectCreatingInterceptor.properties</code> + </para> + </listitem> + <listitem> + <para> + set the action property in + <code>GTNSubjectCreatingInterceptor.properties</code> + as: + </para> + <informalexample> + <programlisting>action= gtn.UsernameToken.ifAvailable Signature Encrypt Timestamp</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + set the passwordType in + <code>GTNSubjectCreatingInterceptor.properties</code> + as: + </para> + <informalexample> + <programlisting>passwordType=PasswordText</programlisting> + </informalexample> + </listitem> + </orderedlist> + </section> + <section> + <title>Configure the Consumer</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW...</remark> + <para> + Follow the steps outlined in the + <link linkend="sid-54264620_SecuringWSRP-SampleConfigurationSecuringtheEndpointsusingEncryptionandSigning">Sample Configuration Securing the Endpoints using Encryption and Signing</link> + section but make the following changes: + </para> + <orderedlist> + <listitem> + <para> + set the action property in + <code>WSS4JOutInterceptor.properties</code> + as: + </para> + <informalexample> + <programlisting>action=gtn.UsernameToken.ifCurrentUserAuthenticated Signature Encrypt Timestamp</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + set the user in the + <code>WSS4JOutInterceptor.properties</code> + as: + </para> + <informalexample> + <programlisting>user=gtn.current.user</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + set the passwordType in the + <code>WSS4JOutInterceptor.properties</code> + as: + </para> + <informalexample> + <programlisting>passwordType=PasswordText</programlisting> + </informalexample> + </listitem> + </orderedlist> + </section> + </section> + </section> + </chapter> + <chapter> + <title>Making a portlet remotable</title> + <important> + <para> + Only JSR-286 (Portlet 2.0) portlets can be made remotable as the mechanism to expose a portlet to WSRP + relies on a JSR-286-only functionality. + </para> + </important> + <para>JBoss Portal Platform does +not, by default, expose local portlets for consumption + by remote WSRP consumers. In order to make a portlet remotely available, it must be made <firstterm>remotable</firstterm> by marking + it as such in the associated + <filename>portlet.xml</filename>. This is accomplished by using a specific + <code>org.gatein.pc.remotable container-runtime-option</code>. Setting its value to + <code>true</code> + makes the portlet available for remote consumption, while setting its value to + <code>false</code> + will not publish it remotely. As specifying the remotable status for a portlet is optional, you do not need to + do anything if you do not need your portlet to be available remotely. + </para> + <example> + <title>Single Portlet Remotable Example</title> + <para>The "BasicPortlet" portlet is specified as being remotable. + </para> + <para> + <programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> +<portlet-app> + <portlet> + <portlet-name>BasicPortlet</portlet-name> + + ... + + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>true</value> + </container-runtime-option> + </portlet> +</portlet-app>]]></programlisting> + </para> + </example> + <para> + It is also possible to specify that all the portlets declared within a given portlet application to be + remotable by default. This is done by specifying the + <code>container-runtime-option</code> + at the + <code>portlet-app</code> + element level. Individual portlets can override that value to not be remotely exposed. This is an + example: + </para> + <example> + <title>Multiple Portlets Remotable Example</title> + <para> + The example defines two portlets. The + <code>org.gatein.pc.remotable container-runtime-option</code> + being set to + <code>true</code> + at the + <code>portlet-app</code> + level, all portlets defined in this particular portlet application are exposed remotely by JBoss Portal Platform's + WSRP + producer. +</para> + <programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> +<portlet-app> + + <portlet> + <portlet-name>RemotelyExposedPortlet</portlet-name> + ... + </portlet> + <portlet> + <portlet-name>NotRemotelyExposedPortlet</portlet-name> + ... + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>false</value> + </container-runtime-option> + </portlet> + + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>true</value> + </container-runtime-option> +</portlet-app>]]> + </programlisting> + <para>It is possible to override the default behavior by specifying a value for the + <code>org.gatein.pc.remotable container-runtime-option</code> + at the + <code>portlet</code> + level. </para> + <para>The + <varname>RemotelyExposedPortlet</varname> + inherits the remotable status defined at the + <code>portlet-app</code> + level since it does not specify a value for the <code>org.gatein.pc.remotable container-runtime-option</code>. + The <varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely + exposed. Note that in the absence of a top-level + <code>org.gatein.pc.remotable container-runtime-option</code> + value set to <code>true</code>, portlets are not remotely exposed. + </para> + </example> + </chapter> + <chapter> + <title>Consuming WSRP portlets from a remote Consumer</title> + <para>WSRP Producers vary a lot as far as how they are configured. Most of them require that you specify + the URL for the Producer's WSDL definition. Please refer to the remote producer's documentation for specific + instructions. For instructions on how to do so in JBoss Portal Platform, please refer to + Consumer Configuration. + </para> + <para> +JBoss Portal Platform's Producer is automatically set up when you deploy a portal instance with the WSRP service. + You can access the WSDL file at + <filename>http://{hostname}:{port}/wsrp-producer/v2/MarkupService?wsdl</filename>. If you wish to use only the + WSRP 1 compliant version of the producer, please use the WSDL file found at + <filename>http://{hostname}:{port}/wsrp-producer/v1/MarkupService?wsdl</filename>. + The default hostname is + <literal>localhost</literal> + and the default port is 8080. + </para> + </chapter> + <chapter> + <title>Consuming remote WSRP portlets in JBoss Portal Platform</title> + <section> + <title>Overview</title> + <para> + To be able to consume WSRP portlets exposed by a remote producer, JBoss Portal Platform's WSRP consumer needs to + know how to access that remote producer. You can configure access to a remote producer using the provided + configuration portlet. Alternatively, it is also possible to configure access to remote producers using an + XML descriptor, though it is recommended (and easier) to do so via the configuration portlet. + </para> + <para> + Once a remote producer has been configured, the portlets that it exposes are then available in the + Application Registry to be added to categories and then to pages. + </para> + </section> + <section> + <title>Configuring a remote producer using the configuration portlet</title> + <para> + This section will cover the steps of defining access to a remote producer using the configuration portlet so that its portlets can be + consumed within JBoss Portal Platform. We will configure access to NetUnity's public WSRP producer. + </para> + <note> + <para> + Some WSRP producers do not support chunked encoding that is activated by default by JBoss WS. If your + producer does not support chunked encoding, your consumer will not be able to properly connect to the + producer. This will manifest itself with the following error: + <code>Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] - Service Unavailable</code>. + Please see this <ulink url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingisnotsupported">wiki page </ulink> + for more details. + </para> + </note> + <para> +JBoss Portal Platform provides a portlet to configure access (among other functions) to remote WSRP Producers + graphically. Starting with &VZ;, the WSRP configuration portlet is installed by default. You + can find it at + <ulink url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass..."> http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... </ulink> + </para> + <para> + You should see a screen similar to: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_init.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>This screen presents all the configured Consumers associated with their status and possible actions on + them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a + portlet provider. Note also that a Consumer can be marked as requiring refresh meaning that the + information held about it might not be up to date and refreshing it from the remote Producer might be a + good idea. This can happen for several reasons: the service description for that remote Producer has not + been fetched yet, the cached version has expired or modifications have been made to the configuration + that could potentially invalidate it, thus requiring re-validation of the information. + </para> + <note> + <title>Note</title> + <para> + The WSRP configuration was not installed by default in previous versions of JBoss Portal Platform. + We include here the legacy instructions on how to install this portlet in case you ever need to + re-install it. + </para> + <para> + Use the usual procedure to log in as a Portal administrator and go to the Application + Registry. With the default install, you can open the + <ulink url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass...">Group > Administration > Application Registry </ulink> +screen and add the WSRP Configuration portlet to the Administration category. If you use the Import Applications + functionality, the WSRP Configuration portlet will be automatically added to the Administration + category. + </para> + <para> + Now that the portlet is added to a category, it can be added to a page and used. It is recommended that you add + it to the same page as the Application Registry as operations relating to WSRP and adding portlets to + categories are somewhat related. Go ahead and add the WSRP Configuration portlet to the + page using the standard procedure. + </para> + </note> + <para> + Next, create a new Consumer called <literal>netunity</literal>. Type + "<literal>netunity</literal>" in + the "Create a consumer named:" field then click on "Create consumer": + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_create.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>You should now see a form allowing you to enter/modify the information about the Consumer. + Set the cache expiration value to 300 seconds, leave the default timeout value for web services (WS) + operations and enter the WSDL URL for the producer in the text field + and press the "Refresh & Save" button:</para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_wsdl.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>This will retrieve the service description associated with the Producer which WSRP interface is described + by the WSDL file found at the URL you just entered. In this case, querying the service description will + reveal that the Producer requires registration, requested three registration properties and that + some of these properties are missing values:</para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_missing.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>This particular producer requests simple + <literal>Yes</literal> + or + <literal>No</literal> + values for the three registration properties. Entering <literal>No</literal>, + <literal>Yes</literal> + and + <literal>No</literal> + (in that order) for the values and then pressing the "Refresh & Save" button should result in:</para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_end.png" format="PNG"/> + </imageobject> + </mediaobject> + <note> + <title>Note</title> + <para>At this point, there is no automated way to learn about which possible values (if any) are + expected by the remote Producer. Sometimes, the possible values will be indicated in the + registration + property description but this is not always the case... Please refer to the specific Producer's + documentation. + </para> + </note> + <para> + If you had been dealing with a producer which required registration but did not require any registration + properties, as is the case for the + <literal>selfv2</literal> + consumer (the consumer that accesses the portlets made remotely available by JBoss Portal Platform's producer via + WSRP 2), you would have seen something similar to the screenshot below, after pressing the "Refresh & Save" button: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_refresh.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + </section> + <section> + <title>Configuring access to remote producers via XML</title> + <para>While it is recommended you use the WSRP Configuration portlet to configure Consumers, the component provides an + alternative way to configure consumers by adding an XML file called + <filename>wsrp-consumers-config.xml</filename> in the + <filename><replaceable>JPP_DIST</replaceable>/standalone/configuration/gatein/wsrp/</filename> directory. + </para> + <note> + <title>Note</title> + <para>An XML Schema defining which elements are available to configure Consumers via XML can be found + in + <filename><replaceable>JPP_DIST</replaceable>/modules/org/gatein/wsrp/main/wsrp-integration-api-&WSRP_VERSION;.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> + </para> + </note> + <important> + <para>Once the XML configuration file for consumers has been read upon + the WSRP service first start, the associated information is put under control of JCR (Java Content + Repository). Subsequent launches of the WSRP service will use the JCR-stored information and ignore + the content of the XML configuration file. + </para> + </important> + <section> + <title>Required configuration information</title> + <para>This section covers what information needs to be provided to configure access to a remote producer. + </para> + <para>First, you need to provide an identifier for the producer you are configuring so that you can refer to it + afterwards. This is accomplished via the mandatory + <literal>id</literal> + attribute of the + <literal><wsrp-producer></literal> + element. + </para> + <para>JBoss Portal Platform also needs to learn about the remote producer's endpoints to be able to connect to the + remote web services and perform WSRP invocations. This is accomplished by specifying the URL for the + WSDL description for the remote WSRP service, using the + <literal><endpoint-wsdl-url></literal> + element. + </para> + <para>Both the + <literal>id</literal> + attribute and + <literal><endpoint-wsdl-url></literal> + elements are required for a functional remote producer configuration. + </para> + </section> + <section> + <title>Optional configuration</title> + <para>It is also possible to provide addtional configuration, which, in some cases, might be important to + establish a proper connection to the remote producer. + </para> + <para>One such optional configuration concerns caching. To prevent useless round-trips between the local + consumer and the remote producer, it is possible to cache some of the information sent by the producer + (such as the list of offered portlets) for a given duration. The rate at which the information is + refreshed is + defined by the + <literal>expiration-cache</literal> + attribute of the + <literal><wsrp-producer></literal> + element which specifies the refreshing period in seconds. For example, providing a value of 120 for + expiration-cache means that the producer information will not be refreshed for 2 minutes after it has + been somehow accessed. If no value is provided, JBoss Portal Platform will always access the remote producer + regardless of whether the remote information has changed or not. Since, in most instances, the + information provided by the producer does not change often, it is recommended that you use this caching + facility to minimize bandwidth usage. + </para> + <para>It is also possible to define a timeout after which WS operations are considered as failed. This is + helpful to avoid blocking the WSRP service, waiting on the service that does not answer. Use the + <literal>ws-timeout</literal> + attribute of the + <literal><wsrp-producer></literal> + element to specify how many milliseconds the WSRP service will wait for a response from the remote + producer before timing out and giving up. + </para> + <para>Additionally, some producers require consumers to register with them before authorizing them to access + their offered portlets. If you know that information beforehand, you can provide the required + registration information in the producer configuration so that the consumer can register with the remote + producer when required. + </para> + <note> + <title>Note</title> + <para>At this time, though, only simple String properties are supported and it is not possible to + configure complex registration data. This should, however, be sufficient for most cases. + </para> + </note> + <para>Registration configuration is done via the + <literal><registration-data></literal> + element. Since JBoss Portal Platform can generate the mandatory information for you, if the remote producer does + not require any registration properties, you only need to provide an empty + <literal><registration-data></literal> + element. Values for the registration properties + required by the remote producer can be provided via + <literal><property></literal> + elements. See the example below for more details. Additionally, you can override the default consumer + name automatically provided by JBoss Portal Platform via the + <literal><consumer-name></literal> + element. If you choose to provide a consumer name, please remember that this should uniquely identify + your consumer. + </para> + </section> + <section> + <title>Examples</title> + <remark>NEEDINFO - FILE PATHS - this file was not present at the location specified. Where is this file now?</remark> + <para> + Here is the configuration of the + <literal>selfv1</literal> + and + <literal>selfv2</literal> + consumers as found in + <filename><replaceable>JPP_HOME</replaceable>/gatein/extensions/gatein-wsrp-integration.ear/lib/extension-component-&WSRP_VERSION;.jar/conf/wsrp-consumers-config.xml</filename> + with a cache expiring every 500 seconds and with a 50 second timeout for web service operations. + <note> + <para> + This file contains the default configuration and you should not need to edit it. If you want to make + modifications to it, it is recommended that you follow the procedure detailed in +consumer_gui . + </para> + </note> + </para> + <example> + <title>Example</title> + <para> + <programlisting><![CDATA[ +<?xml version='1.0' encoding='UTF-8' ?> +<deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0 http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> + <deployment> + <wsrp-producer id="selfv1" expiration-cache="500" ws-timeout="50000"> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v1/MarkupService?wsdl</endpoint-wsdl-url> + <registration-data/> + </wsrp-producer> + </deployment> + <deployment> + <wsrp-producer id="selfv2" expiration-cache="500" ws-timeout="50000"> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v2/MarkupService?wsdl</endpoint-wsdl-url> + <registration-data/> + </wsrp-producer> + </deployment> +</deployments>]]> + </programlisting> + </para> + </example> + <example> + <title>Registration Data and Cache Expiry Example</title> + <para>This example shows a WSRP descriptor with registration data and cache expiring every minute:</para> + <para> + <programlisting><![CDATA[ +<?xml version='1.0' encoding='UTF-8' ?> +<deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0 http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> +<deployments> + <deployment> + <wsrp-producer id="AnotherProducer" expiration-cache="60"> + <endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoint-wsdl-url> + <registration-data> + <property> + <name>property name</name> + <lang>en</lang> + <value>property value</value> + </property> + </registration-data> + </wsrp-producer> + </deployment> +</deployments>]]></programlisting> + </para> + </example> + </section> + </section> + <section> + <title>Adding remote portlets to categories</title> + <para> + If you go to the Application Registry and examine the available portlets by clicking on the + Portlet link, you will now be able to see remote portlets if you click on the REMOTE tab in the left + column: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/remote_portlets.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + <para> + These portlets are, of course, available to be used such as regular portlets: they can be used in + categories and added to pages. If you use the Import Applications functionality, they will also be + automatically imported in categories based on the keywords they define. + </para> + <para> + More specifically, if you want to add a WSRP portlet to a category, you can access these portlets by + selecting + <literal>wsrp</literal> + in the Application Type drop-down menu: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/remote_portlets_category.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + </section> + <section> + <title>Adding remote portlets to pages</title> + <para> + Since remote portlets can be manipulated just like regular portlets, you can add them to pages just like you + would do for a regular portlet. Please refer to the appropriate section of the documentation for how to do + so. + </para> + <para> + Of note, though, is that, starting with version 5.2 of JBoss Portal Platform, it is now possible to also add a + remote portlet to a + <filename>pages.xml</filename> + configuration file. + This is accomplished using the + <literal><wsrp></literal> + element instead of the + <literal><portlet></literal> + element in your + <filename>pages.xml</filename> + document. While + <literal><portlet></literal> + references a local portlet using the name of the application in which the portlet is contained and the + portlet name itself to identify which portlet to use, + <literal><wsrp></literal> + references a remote portlet using a combination of the consumer identifier for the producer publishing the + portlet and the portlet handle identifying the portlet within the context of the producer. + </para> + <para> + The format for such a reference to a remote portlet is a follows: first, the identifier of the + consumer that accesses the remote producer publishing the remote portlet, then a separator (currently a + period (<literal>.</literal>)) and finally the portlet handle for that + portlet, which is a string provided by the producer to identify the portlet. + </para> + <para> + Since there currently is no easy way to determine the correct portlet handle, it is recommended that you use the + graphical user interface to add remote portlets to pages instead of using + <filename>pages.xml</filename>. + </para> + <note> + <para> + For remote portlets published by JBoss Portal Platform's WSRP producer, the portlet handles are, at + the time of this writing, following the + <literal>/<portlet application name>.<portlet name></literal> + format. + </para> + </note> + <section> + <title>Example</title> + <para> + In the following example, two portlets are defined for a page named + <literal>Test</literal> + in the + <filename>pages.xml</filename> + configuration. They are actually references to the same portlet, albeit one accessed locally and the + other + one accessing it via the + <literal>selfv2</literal> + consumer which consumes JBoss Portal Platform's WSRP producer. You can see that the first one is local (the + <code><portlet-application></code> + with the + '<literal>Added locally</literal>' + title) and follows the usual declaration. The second portlet (the one with the + '<literal>Added from selfv2 consumer</literal>' + title) comes from the + <literal>selfv2</literal> + consumer and uses the + <code><wsrp></code> + element instead of + <code><portlet></code> + element and follows the format for portlets coming from the JBoss Portal Platform's WSRP producer. + </para> + <example> + <title>Example</title> + <para> + <programlisting><![CDATA[ +<page> + <name>Test</name> + + ... + + <portlet-application> + <portlet> + <application-ref>richFacesPortlet</application-ref> + <portlet-ref>richFacesPortlet</portlet-ref> + </portlet> + <title>Added locally</title> + + ... + + </portlet-application> + + <portlet-application> + <wsrp>selfv2./richFacesPortlet.richFacesPortlet</wsrp> + <title>Added from selfv2 consumer</title> + + ... + + </portlet-application> +</page>]]></programlisting> + </para> + </example> + </section> + </section> + </chapter> + <chapter> + <title>Consumers maintenance</title> + <section> + <title>Modifying a currently held registration</title> + <section> + <title>Registration modification for service upgrade</title> + <para> + Producers often offer several levels of service depending on consumers' subscription levels (for + example). This is implemented at the WSRP level with the registration concept: producers can assert which + level of service to provide to consumers based on the values of given registration properties. + </para> + <para> + There might also be cases where you just want to update the registration information because it has + changed. For example, the producer required you to provide a valid email and the previously email + address is not valid anymore and needs to be updated. + </para> + <para> + It is therefore sometimes necessary to modify the registration that concretizes the service agreement + between a consumer and a producer. The following is an example of a producer requiring a valid email (via an + <literal>email</literal> + registration property) as part of its required information that consumers need to provide to be properly + registered. + </para> + <para> + Suppose now that you would like to update the email address that you provided to the remote producer when + you first registered. You will need to tell the producer that the registration data has been modified. + </para> + <para> + Select the consumer for the remote producer in the available consumers list to + display its configuration. Assuming you want to change the email you registered with to + <literal>foo(a)example.com</literal>, change its value in the field for the + <literal>email</literal> + registration property: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_start.png" format="PNG"/> + </imageobject> + </mediaobject> + Now click on "Update properties" to save the change. A "Modify registration" button should now appear to + let you send this new data to the remote producer: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_modify.png" format="PNG"/> + </imageobject> + </mediaobject> + Click on this new button and, if everything went well and your updated registration has been accepted by + the remote producer, you should see something similar to: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_end.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + </section> + <section id="reg_mod_error"> + <title>Registration modification on producer error</title> + <para> + It can also happen that a producer administrator decided to change its requirement for registered + consumers. JBoss Portal Platform will attempt to help you in this situation. This section will walk through an example using + the <literal>selfv2</literal> consumer (assuming that registration is requiring a valid value for an + <literal>email</literal> + registration property). If you go to the configuration screen for this consumer, you should see: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_self.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>Now suppose that the administrator of the producer now additionally requires a value to be provided for a + <literal>name</literal> + registration property. Steps on how to do perform this operation + in JBoss Portal Platform are outlined in the section on how to configure JBoss Portal Platform's producer + (<xref linkend="producer_config"/>). + Operations with this producer will now fail. If you suspect that a registration modification is required, + you should go to the configuration screen for this remote producer and refresh the information held by + the consumer by pressing "Refresh & Save": + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_self.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>As you can see, the configuration screen now shows the currently held registration information and + the expected information from the producer. Enter a value for the + <literal>name</literal> + property + and then click on "Modify registration". If all went well and the producer accepted your new registration + data, you should see something similar to: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_self_end.png" format="PNG"/> + </imageobject> + </mediaobject> + <note> + <title>Note</title> + <para>WSRP 1 makes it rather difficult to ascertain for sure what caused an + <exceptionname>OperationFailedFault</exceptionname> + as it is the generic exception returned by + producers if something did not quite happen as expected during a method invocation. This means that + <exceptionname>OperationFailedFault</exceptionname> + can be caused by several different reasons, one + of them being a request to modify the registration data. Please take a look at the log files to see + if you can gather more information as to what happened. WSRP 2 introduces an exception that is + specific to a request to modify registrations thus reducing the ambiguity that exists when using WSRP 1. + </para> + </note> + </section> + </section> + <section> + <title>Consumer operations</title> + <para> + Several operations are available from the consumer list view of the WSRP configuration portlet: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/consumer_operations.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + <para> + The available operations are: + </para> + <itemizedlist> + <listitem> + <para>Configure: displays the consumer details and allows user to edit them</para> + </listitem> + <listitem> + <para>Refresh: forces the consumer to retrieve the service description from the remote producer to + refresh + the local information (offered portlets, registration information, etc.) + </para> + </listitem> + <listitem> + <para>Activate/Deactivate: activates/deactivates a consumer, governing whether it will be available to + provide portlets and receive portlet invocations + </para> + </listitem> + <listitem> + <para>Register/Deregister: registers/deregisters a consumer based on whether registration is required + and/or acquired + </para> + </listitem> + <listitem> + <para>Delete: destroys the consumer, after deregistering it if it was registered</para> + </listitem> + <listitem> + <para>Export: exports some or all of the consumer's portlets to be able to later import them in a + different context + </para> + </listitem> + <listitem> + <para>Import: imports some or all of previously exported portlets</para> + </listitem> + </itemizedlist> + <note> + <title>Note</title> + <para> + Import/Export functionality is only available to WSRP 2 consumers of producers that support this optional + functionality. Import functionality is only available if portlets had previously been exported. + </para> + </note> + </section> + <section> + <title>Importing and exporting portlets</title> + <para>Import and export are new functionality added in WSRP 2. Exporting a portlet allows a consumer to get + an opaque representation of the portlet which can then be use by the corresponding import operation to + reconstitute it. It is mostly used in migration scenarios during batch operations. Since JBoss Portal Platform + does not currently support automated migration of portal data, the functionality that is provided as part of + WSRP 2 is necessarily less complete than it could be with full portal support. + </para> + <para>The import/export implementation in JBoss Portal Platform allows users to export portlets + from a given consumer. + These portlets can then be used to replace existing content on pages. This is accomplished by assigning + previously exported portlets to replace the content displayed by windows on the portal's pages. Below is an example to make things clearer. + </para> + <para>Clicking on the "Export" action for a given consumer will display the list of portlets currently made + available by this specific consumer. An example of such a list is shown below: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/export_portlet_list.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>Once portlets have been selected, they can be exported by clicking on the "Export" button thus making + them available for later import: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/export_done.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>You can re-import the portlets directly by pressing the "Use for import" button or, on the Consumers list + page, using the "Import" action for a given consumer. This assumes that you used that second option and that + you currently have several available sets of previously exported portlets to import from. After clicking the + action link, you should see a screen similar to the one below: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/export_list.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>As you can see this screen presents the list of available exports with available operations for each: + </para> + <itemizedlist> + <listitem> + <para>View: displays the export details as previously seen when the export was first performed</para> + </listitem> + <listitem> + <para>Delete: deletes the selected export, asking you for confirmation first</para> + </listitem> + <listitem> + <para>Use for import: selects the export to import portlets from</para> + </listitem> + </itemizedlist> + <para>Once you have selected an export to import from, you will see a screen similar to the one below:</para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/import_start.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>The screen displays the list of available exported portlets for the previously selected export. You can + select which portlet you want to import by checking the checkbox next to its name. Next, you need to select + the content of which window the imported portlet will replace. This process is done in three steps. This example + assumes that you have the following page called + <literal>page1</literal> + and containing two windows called + <literal>NetUnity WSRP 2 Interop - Cache Markup (remote)</literal> + and + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + as shown below: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/import_original_page.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>In this example, you want to replace the content of the + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + by the content of the + <literal>/ajaxPortlet.JSFAJAXPortlet</literal> + portlet that you previously exported. To do so, you will check the checkbox next to the + <literal>/ajaxPortlet.JSFAJAXPortlet</literal> + portlet name to indicate that you want to import its data and then select the + <literal>page1</literal> + in the list of available pages. The screen will then refresh to display the list of available windows on + that page, similar to the one seen below: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/import_selected_page.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>Note that, at this point, you still need to select the window which content you want to replace before + being able to complete the import operation. Select the + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + window, at which point the "Import" button will become enabled, indicating that you now have all the + necessary data to perform the import. If all goes well, pressing that button should result in a screen + similar to the one below: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/import_success.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>If you now take a look at the + <literal>page1</literal> + page, you should now see that the content + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + window has been replaced by the content of the + <literal>/ajaxPortlet.JSFAJAXPortlet</literal> + imported portlet and the window renamed appropriately: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/import_modified_page.png" format="PNG"/> + </imageobject> + </mediaobject> + </section> + <section> + <title>Erasing local registration data</title> + <para> + There are rare cases where it might be required to erase the local information without being able to + de-register first. This is the case when a consumer is registered with a producer that has been modified by + its administrator to not require registration anymore. If that ever was to happen (most likely, it will not), + you can erase the local registration information from the consumer so that it can resume interacting with + the remote producer. To do so, click on "Erase local registration" button next to the registration context + information on the consumer configuration screen: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/erase_registration.png" format="PNG"/> + </imageobject> + </mediaobject> + <warning> + <title>Warning:</title> + <para> + This operation is dangerous as it can result in inability to interact with the remote producer if invoked + when not required. A warning screen will be displayed to give you a chance to change your mind: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/erase_registration_warning.png" format="PNG"/> + </imageobject> + </mediaobject> + </warning> + </section> + </chapter> + <chapter> + <title>Working with WSRP Extensions</title> + <remark>Source https://docs.jboss.org/author/display/GTNPORTAL35/Working+with+WSRP+exten...</remark> + <section> + <title>Overview</title> + <para> + The WSRP specifications allows for implementations to extend the protocol using + <ulink url="http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec-os-01.html#_Extension">Extensions</ulink> + . JBoss Portal Platform, as of its WSRP implementation version 2.2.0, provides a way for client code (e.g. portlets) to interact with such extensions in the form of several classes and interfaces gathered within the + <ulink url="https://github.com/gatein/gatein-wsrp/tree/master/api/src/main/java/org/g..."><code>org.gatein.wsrp.api.extensions</code> package </ulink> + , the most important ones being + <code>InvocationHandlerDelegate</code> + , + <code>ConsumerExtensionAccessor</code> + and + <code>ProducerExtensionAccessor</code> + . + </para> + <para> + To be able to use this API, you will need to include the + <code>wsrp-integration-api-$WSRP_VERSION.jar</code> + file to your project, where + <code>$WSRP_VERSION</code> + is the version of the JBoss Portal Platform WSRP implementation you wish to use, 2.2.2.Final being the current one. This can be done by adding the following dependency to your maven project: + </para> + <informalexample> + <programlisting> +<dependency> + <groupId>org.gatein.wsrp</groupId> + <artifactId>wsrp-integration-api</artifactId> + <version>$WSRP_VERSION</version> +</dependency> +</programlisting> + </informalexample> + <section> + <title>InvocationHandlerDelegate infrastructure</title> + <para> + Using the + <code>InvocationHandlerDelegate</code> + infrastructure, custom behavior can now be inserted on either consumer or producer sides to enrich WSRP applications before and/or after portlet requests and/or responses. Please refer to the Javadoc for + <ulink url="https://github.com/gatein/gatein-wsrp/blob/master/api/src/main/java/org/g..."> + <code>org.gatein.wsrp.api.extensions.InvocationHandlerDelegate</code> + </ulink> + for more details on this interface and how to implement it. + </para> + <warning> + <para> + Since + <code>InvocationHandlerDelegate</code> + is a very generic interface, it could potentially be used for more than simply working with WSRP extensions. Moreover, since it has access to internal JBoss Portal Platform classes, it is important to be treat access to these internal classes as + <emphasis role="strong">read-only</emphasis> + to prevent any un-intentional side-effects. + </para> + </warning> + </section> + <section> + <title>Injecting InvocationHandlerDelegate implementations</title> + <para> + Implementations of + <code>InvocationHandlerDelegate</code> + <emphasis role="strong">must</emphasis> + follow the same constraints as + <code>RegistrationPolicy</code> + implementations as detailed in + <ulink url="https://docs.jboss.org/author/pages/viewpage.action?pageId=54264625_Confi...">Customization of Registration handling behavior</ulink> + section of the + <ulink url="https://docs.jboss.org/author/pages/viewpage.action?pageId=54264625">Configuring GateIn's WSRP Producer</ulink> + chapter, in essence, they + <emphasis role="strong">must</emphasis> + follow the Java + <ulink url="http://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html"> + <code>ServiceLoader</code> + </ulink> + architectural pattern and be deployed in the appropriate + <code>JPP_HOME/gatein/extensions</code> + directory. + </para> + <para> + You can specify only one + <code>InvocationHandlerDelegate</code> + implementation per side: one implementation for the consumer and another one for the producer. This is accomplished by passing the fully classified class name to the appropriate system property when the portal is started: + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>WSRP side</para> + </entry> + <entry> + <para>System property</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>consumer</para> + </entry> + <entry> + <para>org.gatein.wsrp.consumer.handlers.delegate</para> + </entry> + </row> + <row> + <entry> + <para>producer</para> + </entry> + <entry> + <para>org.gatein.wsrp.producer.handlers.delegate</para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <section> + <title>Example</title> + <informalexample> + <programlisting>./standalone.sh -Dorg.gatein.wsrp.consumer.handlers.delegate=com.example.FooInvocationHandlerDelegate</programlisting> + </informalexample> + <para> + will inject the + <code>com.example.FooInvocationHandlerDelegate</code> + class on the consumer side, assuming that class implements the + <code>org.gatein.wsrp.api.extensions.InvocationHandlerDelegate</code> + interface and is packaged and deployed appropriately as explained above. + </para> + </section> + </section> + <section> + <title>Accessing extensions from client code</title> + <para> + You can access extensions from client code using + <code>ConsumerExtensionAccessor</code> + and + <code>ProducerExtensionAccessor</code> + on the consumer and producer, respectively. Each interface provides several methods but you should only have to ever call two of them on each, as shown in the following table: + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>Interface</para> + </entry> + <entry> + <para>Relevant methods</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + <code>ConsumerExtensionAccessor</code> + </para> + </entry> + <entry> + <itemizedlist> + <listitem> + <para> + <code>public void addRequestExtension(Class targetClass, Object extension)</code> + </para> + </listitem> + <listitem> + <para> + <code>public List<UnmarshalledExtension> getResponseExtensionsFrom(Class responseClass)</code> + </para> + </listitem> + </itemizedlist> + </entry> + </row> + <row> + <entry> + <para> + <code>ProducerExtensionAccessor</code> + </para> + </entry> + <entry> + <itemizedlist> + <listitem> + <para> + <code>List<UnmarshalledExtension> getRequestExtensionsFor(Class targetClass)</code> + </para> + </listitem> + <listitem> + <para> + <code>void addResponseExtension(Class wsrpResponseClass, Object extension)</code> + </para> + </listitem> + </itemizedlist> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>Please refer to the Javadoc for these classes for more details.</para> + <note> + <para>We currently only support adding and accessing extensions from a core subset of WSRP classes pertaining to markup, interaction, resource or event requests and responses, as follows:</para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>Request classes</para> + </entry> + <entry> + <para>Response classes</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + <code>org.oasis.wsrp.v2.InteractionParams</code> + </para> + </entry> + <entry> + <para> + <code>org.oasis.wsrp.v2.MarkupResponse</code> + </para> + </entry> + </row> + <row> + <entry> + <para> + <code>org.oasis.wsrp.v2.EventParams</code> + </para> + </entry> + <entry> + <para> + <code>org.oasis.wsrp.v2.BlockingInteractionResponse</code> + </para> + </entry> + </row> + <row> + <entry> + <para> + <code>org.oasis.wsrp.v2.MarkupParams</code> + </para> + </entry> + <entry> + <para> + <code>org.oasis.wsrp.v2.HandleEventsResponse</code> + </para> + </entry> + </row> + <row> + <entry> + <para> + <code>org.oasis.wsrp.v2.ResourceParams</code> + </para> + </entry> + <entry> + <para> + <code>org.oasis.wsrp.v2.ResourceResponse</code> + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </note> + <note> + <para> + We + <emphasis role="strong">strongly</emphasis> + recommend that you use + <code>org.w3c.dom.Element</code> + values as extensions for interoperability purposes. + </para> + </note> + </section> + </section> + <section> + <title>Example implementation</title> + <para> + We also provide a complete, end-to-end example to get you started, which you can find at + <ulink url="https://github.com/gatein/gatein-wsrp/tree/master/examples/invocation-han..."/> + . This example shows how + <code>ExampleConsumerInvocationHandlerDelegate</code> + , a consumer-side + <code>InvocationHandlerDelegate</code> + implementation, can add information extracted from the consumer and pass it along to the producer, working in conjunction with + <code>ExampleProducerInvocationHandlerDelegate</code> + , the associated producer-side + <code>InvocationHandlerDelegate</code> + , to establish a round-trip communication channel outside of the standard WSRP protocol, implementing the following scenario: + </para> + <itemizedlist> + <listitem> + <para> + <code>ExampleConsumerInvocationHandlerDelegate</code> + attaches to the consumer to add the current session id as an extension to render requests sent to the producer. + </para> + </listitem> + <listitem> + <para> + <code>ExampleProducerInvocationHandlerDelegate</code> + provides the counterpart of + <code>ExampleConsumerInvocationHandlerDelegate</code> + on the producer. It checks incoming render requests for potential extensions matching what + <code>ExampleConsumerInvocationHandlerDelegate</code> + sends and adds an extension of its own to the render response so that the consumer-side delegate can know that the information it passed was properly processed. + </para> + </listitem> + </itemizedlist> + <sidebar> + <para>To activate the InvocationHandlerDelegates on both the consumer and producer, start your JBoss Portal Platform instance as follows:</para> + </sidebar> + </section> + </chapter> + <chapter id="producer_config"> + <title>Configuring JBoss Portal Platform's WSRP Producer</title> + <remark>Source content taken from https://docs.jboss.org/author/display/GTNPORTAL35/Configuring+GateIn%27s+... . Review this page for revision incorporation history.</remark> + <section> + <title>Overview</title> + <para> + The preferred way to configure the behavior of Portal's WSRP Producer is through the WSRP configuration portlet. + Alternatively, it is possible to add an XML file called + <filename>wsrp-producer-config.xml</filename> + in the + <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/wsrp</filename> + directory. + Several aspects can be modified with respect to whether registration is required for consumers to access + the Producer's services. + </para> + <note> + <title>Note</title> + <para>An XML Schema defining which elements are available to configure Consumers via XML can be found + in + <filename><replaceable>JPP_HOME</replaceable>/modules/org/gatein/wsrp/main/wsrp-integration-api-&WSRP_VERSION;.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename> + </para> + </note> + <important> + <title>Important</title> + <para> + It is important to note that once the XML configuration file for the producer has been read upon + the WSRP service first start, the associated information is put under control of the JCR (Java Content + Repository). Subsequent launches of the WSRP service will use the JCR-stored information and ignore + the content of the XML configuration file. + </para> + </important> + </section> + <section> + <title>Default configuration</title> + <para> + The default producer configuration requires that consumers register with it before providing access its + services, but does not require any specific registration properties (apart from what is mandated by the + WSRP standard). It does, however, require consumers to be registered before sending them a full service + description. This means that the WSRP producer will not provide the list of offered portlets and other + capabilities to unregistered consumers. </para> + <para>The producer also uses the default + <classname>RegistrationPolicy</classname> + paired with the default + <classname>RegistrationPropertyValidator</classname>. Property + validators will be discussed in greater detail later in <xref linkend="registration-configuration"/>. This allows users to customize how the Portal's WSRP Producer determines whether a given registration property + is valid or not. + </para> + <para> +JBoss Portal Platform provides a web interface to configure the producer's behavior. It is accessed by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. The image below is what you + should see with the default configuration: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_default.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>You can specify whether or not the producer will send the full service description to + unregistered consumers, and, if it requires registration, which + <classname>RegistrationPolicy</classname> + to use (and, if needed, which + <classname>RegistrationPropertyValidator</classname>), along with required + registration property description for which consumers must provide acceptable values to successfully + register.</para> + <para>The WSDL URLs to access the Portal's WSRP producer are displayed either in WSRP 1 + or WSRP 2 mode. + </para> + </section> + <section id="registration-configuration"> + <title>Registration configuration</title> + <para> + In order to require consumers to register with Portal's producer before interacting with it, you need to + configure Portal's behavior with respect to registration. Registration is optional, as are registration + properties. The producer can require registration without requiring consumers to pass any registration + properties as is the case in the default configuration. </para> + <para>To configure the producer starting with a blank + state: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_blank.png" format="PNG"/> + </imageobject> + </mediaobject> + <para> + You will allow unregistered consumers to see the list of offered portlets so you leave the first checkbox + ("Access to full service description requires consumers to be registered.") unchecked. You will, however, + specify that consumers will need to be registered to be able to interact with the producer. Check the second + checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer + registrations."). The screen should now refresh and display: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_registration.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>You can specify the fully-qualified name for your + <classname>RegistrationPolicy</classname> + and + <classname>RegistrationPropertyValidator</classname> + there. Keep the default value. See + <xref linkend="custom_registration"/> + for further information about other available values. </para> + <para>Add a registration property called + <literal>email</literal>. Click "Add property" and enter the appropriate information in the fields, + providing a description for the registration property that can be used by consumers to figure out its + purpose: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_email.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>Click "Save" to record the modifications. + </para> + <note> + <title>Note</title> + <para>At this time, only String (xsd:string) properties are supported. If your application requires more + complex properties, please supply feedback. + </para> + </note> + <note> + <title>Note</title> + <para>If consumers are already registered with the producer, modifying the configuration of required + registration + information will trigger the invalidation of held registrations, requiring consumers to modify their + registration before being able to access the producer again. You saw the consumer side of that process + in + <xref linkend="reg_mod_error"/>. + </para> + </note> + <section id="custom_registration"> + <title>Customization of Registration handling behavior</title> + <para> + Registration handling behavior can be customized by users to suit their Producer needs. This is + accomplished by providing an implementation of the + <classname>RegistrationPolicy</classname> + interface. This interface defines methods that are called by Portal's Registration service so that + decisions can be made appropriately. A default registration policy that provides basic + behavior is provided and should be enough for most user needs. + </para> + <para> + While the default registration policy provides default behavior for most registration-related aspects, + there is still one aspect that requires configuration: whether a given value for a registration property + is acceptable by the WSRP Producer. This is accomplished by plugging a + <classname>RegistrationPropertyValidator</classname> + in the default registration policy. This allows users to define their own validation mechanism for registration properties that are passed by a consumer to a producer. + </para> + <para> + Please refer to the + <trademark class="trade">Javadoc</trademark> + for + +<ulink url="https://github.com/gatein/gatein-wsrp/blob/master/producer/src/main/java/..."> + <classname>org.gatein.registration.RegistrationPolicy</classname> + </ulink> and + +<ulink url="https://github.com/gatein/gatein-wsrp/blob/master/producer/src/main/java/..."> + <classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname> + </ulink> for more + details on what is expected of each method. + </para> + <para>Defining a registration policy is required for the producer to be correctly configured. If you don't provide one, the <literal>DefaultRegistrationPolicy</literal> associated to the <literal>DefaultRegistrationPropertyBehavior</literal> is used. + </para> + <figure> + <title>DefaultRegistrationPolicy</title> + <mediaobject> + <imageobject> + <imagedata width="666" fileref="images/WSRP/producer_default.png"/> + </imageobject> + </mediaobject> + </figure> + <para>JBoss Portal Platform can automatically detect deployed implementations of <literal>RegistrationPolicy</literal> and <literal>RegistrationPropertyValidator</literal>, assuming they conform to the following rules:</para> + <itemizedlist> + <listitem> + <para>The implementations must follow the Java <ulink url=".oracle.com/javase/7/docs/api/java/util/ServiceLoader.html">ServiceLoader</ulink> architecture:</para> + <itemizedlist> + <listitem> + <para>They must be packaged as JARs</para> + </listitem> + <listitem> + <para>For <literal>RegistrationPolicy</literal> implementations, they must contain a special <filename>META-INF/services/org.gatein.registration.RegistrationPolicy</filename> file.</para> + </listitem> + <listitem> + <para>For <literal>RegistrationPropertyValidator</literal> implementations they must contain<filename>META-INF/services/org.gatein.registration.policies.RegistrationPropertyValidator</filename> and include a line with the fully qualified name of the implementation class.</para> + </listitem> + </itemizedlist> + <note> + <para>It is possible to package several implementations in the same JAR file, provided that each implementation class is referenced on its own line in the appropriate service definition file. To make things easier, we provide an example project of a RegistrationPolicy implementation and packaging at <ulink url="https://github.com/gatein/gatein-wsrp/tree/master/examples/policy"/>.</para> + </note> + </listitem> + <listitem> + <para>The implementation classes must provide a default, no-argument constructor for dynamic instantiation.</para> + </listitem> + <listitem> + <para>The implementation JARs must be deployed in <filename><replaceable>JPP_HOME</replaceable>/gatein/extensions</filename>.</para> + </listitem> + <listitem> + <para>The implementation JARs should use the <filename>.wsrp.jar</filename> extension. This is not mandatory but helps process the file faster by marking it as a WSRP extension.</para> + </listitem> + </itemizedlist> + <para>If you deployed the example <literal>RegistrationPolicy</literal> provided from the github repository (<filename>registration-policy-example.wsrp.jar</filename>) to the <filename>JPP_HOME/gatein/extensions</filename> directory, it will appear in the list of available policies in the producer configuration screen.</para> + </section> + </section> + <section> + <title>WSRP validation mode</title> + <para>The lack of conformance kit, and the wording of the WSRP specification leaves room for differing + interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when + using consumers from different vendors. </para> + <para>A way to relax + the validation that the WSRP producer performs on the data provided by consumers has been introduced to help with + interoperability by accepting data that would normally be invalid. Note that this validation + algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes. + </para> + <para> + By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, + you might want to try to relax the validation mode. This is accomplished by unchecking the "Use strict WSRP + compliance." checkbox on the Producer configuration screen. + </para> + </section> + </chapter> + </part> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/> </book> Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml 2013-05-16 04:35:34 UTC (rev 9280) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml 2013-05-22 05:52:42 UTC (rev 9281) @@ -8,6 +8,20 @@ <simpara> <revhistory> <revision> + <revnumber>6.1.0-4</revnumber> + <date>Friday May 17 2013</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Added WSRP part.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.1.0-3</revnumber> <date>Wed May 15 2013</date> <author> Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/WSRP.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/WSRP.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_create.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_create.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_end.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_end.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_init.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_init.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_missing.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_missing.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_refresh.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_refresh.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_self.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_self.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wsdl.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wsdl.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wss_selected.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wss_selected.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/consumer_operations.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/consumer_operations.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration_warning.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration_warning.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_done.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_done.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_list.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_list.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_portlet_list.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_portlet_list.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_modified_page.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_modified_page.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_original_page.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_original_page.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_selected_page.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_selected_page.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_start.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_start.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_success.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_success.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_end.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_end.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_modify.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_modify.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self_end.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self_end.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_start.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_start.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_blank.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_blank.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_default.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_default.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_email.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_email.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_registration.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_registration.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets_category.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets_category.png ___________________________________________________________________ Added: svn:mime-type + image/png Modified: epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/WSRP.xml 2013-05-16 04:35:34 UTC (rev 9280) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/WSRP.xml 2013-05-22 05:52:42 UTC (rev 9281) @@ -72,7 +72,7 @@ </note> </section> <section id="Deploying_JPP_WSRP_Services"> - <title><remark>BZ#839355</remark>Deploying JBoss Portal Platform's WSRP services</title> + <title>Deploying JBoss Portal Platform's WSRP services</title> <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Deploying+GateIn%27s+WS...</remark> <para> JBoss Portal Platform provides complete support for WSRP 1.0 and 2.0 standard interfaces, and offers both consumer and Modified: epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml 2013-05-16 04:35:34 UTC (rev 9280) +++ epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml 2013-05-22 05:52:42 UTC (rev 9281) @@ -17,7 +17,7 @@ </author> <revdescription> <simplelist> - <member>BZ#921356 - Removed all instances of "Refer to" in the guide.</member> + <member>BZ#921356 - Removed all instances of "Refer to" in the guide, and replaced with "See", according to new style guide rules for Enterprise docs.</member> </simplelist> </revdescription> </revision>

11 years, 7 months

1
0
0 / 0

gatein SVN: r9279 - in epp/docs/JPP/trunk/User_Guide/en-US: modules and 4 other directories.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-05-15 02:20:24 -0400 (Wed, 15 May 2013) New Revision: 9279 Modified: epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/Supported_Browsers.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/account/Sign_in_and_Sign_out.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Portals.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/User_Management.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/portletsUser/Dashboard_Portlet.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/portletsUser/Interface_Portlets.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/terms/Permission_levels.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/terms/Toolbar_concept.xml Log: BZ#921356 - Removed all instances of Refer to in the guide, and replaced with See instead. Modified: epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml 2013-05-15 02:20:21 UTC (rev 9278) +++ epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml 2013-05-15 06:20:24 UTC (rev 9279) @@ -8,6 +8,20 @@ <simpara> <revhistory> <revision> + <revnumber>6.1.0-3</revnumber> + <date>Wed May 15 2013</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>BZ#921356 - Removed all instances of "Refer to" in the guide.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.1.0-2</revnumber> <date>Tue Apr 30 2013</date> <author> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/Supported_Browsers.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/Supported_Browsers.xml 2013-05-15 02:20:21 UTC (rev 9278) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/Supported_Browsers.xml 2013-05-15 06:20:24 UTC (rev 9279) @@ -5,6 +5,6 @@ ]> <chapter> <title>Supported Browsers</title> - <para>For a list of supported browsers, refer to the Supported Configurations page on the Customer Portal, which is located at <ulink url="https://access.redhat.com/knowledge/articles/119833" type="http">https://access.redhat.com/knowledge/articles/119833</ulink>. + <para>For a list of supported browsers, see the Supported Configurations page on the Customer Portal, which is located at <ulink url="https://access.redhat.com/knowledge/articles/119833" type="http">https://access.redhat.com/knowledge/articles/119833</ulink>. </para> </chapter> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/account/Sign_in_and_Sign_out.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/account/Sign_in_and_Sign_out.xml 2013-05-15 02:20:21 UTC (rev 9278) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/account/Sign_in_and_Sign_out.xml 2013-05-15 06:20:24 UTC (rev 9279) @@ -60,7 +60,7 @@ </term> <listitem> <para> - To follow some steps to get the forgotten user name or password. Please refer to <xref linkend="sect-User_Guide-Account_and_Password_Retrieval"/> for more details. + To follow some steps to get the forgotten user name or password. Please see <xref linkend="sect-User_Guide-Account_and_Password_Retrieval"/> for more details. </para> </listitem> </varlistentry> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Portals.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Portals.xml 2013-05-15 02:20:21 UTC (rev 9278) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Portals.xml 2013-05-15 06:20:24 UTC (rev 9279) @@ -187,8 +187,7 @@ </para> <note> <title>Custom Portlets</title> - <para> - If you want to include a custom portlet or gadget on a page, you may wish to refer to the <emphasis>JBoss Portlet Tools User Guide</emphasis> in the JBoss Developer Studio documentation (<ulink url="http://docs.redhat.com/docs/en-US/JBoss_Developer_Studio/" type="http"/>) and/or the <emphasis role="bold">Portlet development</emphasis> section of the <emphasis>JBoss Portal Platform Reference Guide</emphasis> (<ulink url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/" type="http"/>) for more information about creating and deploying portlets. + <para>See the <emphasis>JBoss Portlet Tools User Guide</emphasis> in the JBoss Developer Studio documentation (<ulink url="http://docs.redhat.com/docs/en-US/JBoss_Developer_Studio/" type="http"/>) and/or the <emphasis role="bold">Portlet development</emphasis> section of the <emphasis>JBoss Portal Platform Reference Guide</emphasis> (<ulink url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/" type="http"/>) for more information about creating and deploying portlets. </para> </note> </section> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/User_Management.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/User_Management.xml 2013-05-15 02:20:21 UTC (rev 9278) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/User_Management.xml 2013-05-15 06:20:24 UTC (rev 9279) @@ -311,8 +311,7 @@ <para> Click on the magnify glass to open up the User selector. </para> - <para> - Refer to <xref linkend="sect-User_Guide-User_Management-Search_a_user"/> for instructions on how to locate a user. + <para>See <xref linkend="sect-User_Guide-User_Management-Search_a_user"/> for instructions on how to locate a user. </para> <para> Check the box next to the user name then click <emphasis role="bold">Add</emphasis> @@ -403,7 +402,7 @@ <guimenu>Organization</guimenu> <guimenu>Users and Groups Management</guimenu> </menuchoice> Membership Management window, with the Add/Edit Membership fields displayed. </phrase> - </textobject> + </textobject> </mediaobject> <section id="sect-User_Guide-User_Management-Add_a_new_membership_type"> <title>Add a new membership type</title> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/portletsUser/Dashboard_Portlet.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/portletsUser/Dashboard_Portlet.xml 2013-05-15 02:20:21 UTC (rev 9278) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/portletsUser/Dashboard_Portlet.xml 2013-05-15 06:20:24 UTC (rev 9279) @@ -143,7 +143,7 @@ Only gadgets that have been added to the whitelist by the administrator can be used. </para> <para> - For more information, refer to the <emphasis>Gadget Proxy Configuration</emphasis> Chapter of the JBoss Portal Platform Installation Guide available at <ulink url="http://docs.redhat.com" type="http"/>. + For more information, see the <emphasis>Gadget Proxy Configuration</emphasis> Chapter of the JBoss Portal Platform Installation Guide available at <ulink url="http://docs.redhat.com" type="http"/>. </para> </important> <para> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/portletsUser/Interface_Portlets.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/portletsUser/Interface_Portlets.xml 2013-05-15 02:20:21 UTC (rev 9278) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/portletsUser/Interface_Portlets.xml 2013-05-15 06:20:24 UTC (rev 9279) @@ -68,7 +68,7 @@ This portlet is used for hosting mini-applications known as gadgets. The dashboard uses a variety of graphical effects for displaying, opening, and using gadgets. </para> <para> - Refer to <xref linkend="sect-User_Guide-Dashboard_Portlet"/> or <xref linkend="chap-User_Guide-Gadgets_Administration"/> for more information. +see <xref linkend="sect-User_Guide-Dashboard_Portlet"/> or <xref linkend="chap-User_Guide-Gadgets_Administration"/> for more information. </para> </listitem> </varlistentry> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/terms/Permission_levels.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/terms/Permission_levels.xml 2013-05-15 02:20:21 UTC (rev 9278) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/terms/Permission_levels.xml 2013-05-15 06:20:24 UTC (rev 9279) @@ -1,70 +1,74 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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 "../../User_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-User_Guide-Permissions"> - <title>Permissions</title> - <para> - Permission settings control what users can and cannot do within the portal and are set by portal administrators. - </para> - <para> - Permission <emphasis role="bold">types</emphasis> dictate what a user can do within the portal. Two permission types are available as follows: - </para> - - <variablelist> - <varlistentry> - <term><emphasis role="bold">Access</emphasis></term> - <listitem> - <para> - This permission type allows users to utilize portal content, that is; sign in, rearrange portlets, etc. This permission can be set for multiple member groups. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis role="bold">Edit</emphasis></term> - <listitem> - <para> - This permission type allows users to change portal content. This includes actions such as changing page information, deleting pages etc. The <emphasis>edit</emphasis> permission is set for only one group at a time. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - Permission <emphasis role="bold"> levels</emphasis> dictate <emphasis>where</emphasis> in the portal the user's permission type applies. There are three permission levels: - </para> - - <variablelist> - <varlistentry> - <term><emphasis role="bold">Portal</emphasis></term> - <listitem> - <para> - The portal permission level includes all pages within the portal. Therefore, a user with the <emphasis role="bold">access</emphasis> permission type can view (but not edit) all the pages within the portal. A user with <emphasis role="bold">edit</emphasis> permission at the portal level, can change any page in the portal. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis role="bold">Page</emphasis></term> - <listitem> - <para> - The page permission level restricts the user to particular pages. Users are only able to see and/or edit (depending on their permission <emphasis role="bold">type</emphasis>) pages they have been given access to. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis role="bold">Portlet</emphasis></term> - <listitem> - <para> - The portlet permission level allows users to create a page by dragging and dropping portlets into a page. Some portlets are only used for administrators while some are used for individuals thus administrators have to set the appropriate access permissions. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - Permission <emphasis role="bold">types</emphasis> and <emphasis role="bold">levels</emphasis> can be used to effectively control who can do what within the portal. For more information on setting permissions refer to <xref linkend="sect-User_Guide-Manage_Permissions"/> - </para> + <title>Permissions</title> + <para> + Permission settings control what users can and cannot do within the portal and are set by portal administrators. + </para> + <para> + Permission <emphasis role="bold">types</emphasis> dictate what a user can do within the portal. Two permission types are available as follows: + </para> + <variablelist> + <varlistentry> + <term> + <emphasis role="bold">Access</emphasis> + </term> + <listitem> + <para> + This permission type allows users to utilize portal content, that is; sign in, rearrange portlets, etc. This permission can be set for multiple member groups. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis role="bold">Edit</emphasis> + </term> + <listitem> + <para> + This permission type allows users to change portal content. This includes actions such as changing page information, deleting pages etc. The <emphasis>edit</emphasis> permission is set for only one group at a time. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Permission <emphasis role="bold"> levels</emphasis> dictate <emphasis>where</emphasis> in the portal the user's permission type applies. There are three permission levels: + </para> + <variablelist> + <varlistentry> + <term> + <emphasis role="bold">Portal</emphasis> + </term> + <listitem> + <para> + The portal permission level includes all pages within the portal. Therefore, a user with the <emphasis role="bold">access</emphasis> permission type can view (but not edit) all the pages within the portal. A user with <emphasis role="bold">edit</emphasis> permission at the portal level, can change any page in the portal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis role="bold">Page</emphasis> + </term> + <listitem> + <para> + The page permission level restricts the user to particular pages. Users are only able to see and/or edit (depending on their permission <emphasis role="bold">type</emphasis>) pages they have been given access to. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis role="bold">Portlet</emphasis> + </term> + <listitem> + <para> + The portlet permission level allows users to create a page by dragging and dropping portlets into a page. Some portlets are only used for administrators while some are used for individuals thus administrators have to set the appropriate access permissions. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Permission <emphasis role="bold">types</emphasis> and <emphasis role="bold">levels</emphasis> can be used to effectively control who can do what within the portal. For more information on setting permissions see <xref linkend="sect-User_Guide-Manage_Permissions"/> + </para> </section> - - Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/terms/Toolbar_concept.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/terms/Toolbar_concept.xml 2013-05-15 02:20:21 UTC (rev 9278) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/terms/Toolbar_concept.xml 2013-05-15 06:20:24 UTC (rev 9279) @@ -1,29 +1,23 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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 "../../User_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-User_Guide-Toolbar-Concept"> - <title>Toolbar</title> - <para> - The Toolbar spans the top of the portal application and provides links to user and administrative actions. + <title>Toolbar</title> + <para> + The Toolbar spans the top of the portal application and provides links to user and administrative actions. </para> -  - <para> - This screenshot displays three Navigations referred to in <xref linkend="sect-User_Guide-Navigation" /> as well as the main Menu button (on the far left of the toolbar) and the name of the current user (on the far right). - </para> - <para> - In this example the current user is the site administrator, hence the extra "Site Editor" menu. - </para> + <imageobject role="html"> + <imagedata fileref="images/Toolbar.png" format="PNG" align="center" scale="110"/> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/Toolbar.png" format="PNG" align="center" scalefit="1" contentwidth="150mm"/> + </imageobject> + </mediaobject> + --> <para> +There are three Navigations referred to in <xref linkend="sect-User_Guide-Navigation"/> as well as the main Menu button (on the far left of the toolbar) and the name of the current user (on the far right). + </para> </section> - -

11 years, 7 months

1
0
0 / 0

gatein SVN: r9278 - in epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US: extras and 1 other directories.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-05-14 22:20:21 -0400 (Tue, 14 May 2013) New Revision: 9278 Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/extras/ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/extras/default151.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/LanguageChoice.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/cas.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/josso.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/loginScreen.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/openam.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/salesforce-idp.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/salesforce-sp.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/saml-sso.png Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/AuthenticationAuthorizationOverview.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/CoreOrganizationInitializer.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Default_Portal_Configuration.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Internationalization_Configuration.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Portal_Permission_Configuration.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/SAML2.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/SAML2_Salesforce_and_Google_Integration.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/SSO.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/chapter-3-Command_Line_Interface.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/chapter-5-Administration_and_Monitoring.xml Log: Added missing images, and ensured each image contained sufficient alt text to pass Section 508 requirements Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml 2013-05-14 06:10:36 UTC (rev 9277) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml 2013-05-15 02:20:21 UTC (rev 9278) @@ -24,9 +24,8 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PredefinedUserConfiguration.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AuthenticationTokenConfiguration.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="BackendConfiguration.xml"/> -  - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CoreOrganizationInitializer.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CoreOrganizationInitializer.xml" encoding="UTF-8"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="SSO.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="LDAP.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="SAML2.xml" encoding="UTF-8"/> Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/AuthenticationAuthorizationOverview.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/CoreOrganizationInitializer.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Default_Portal_Configuration.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Internationalization_Configuration.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Portal_Permission_Configuration.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml 2013-05-14 06:10:36 UTC (rev 9277) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml 2013-05-15 02:20:21 UTC (rev 9278) @@ -8,6 +8,20 @@ <simpara> <revhistory> <revision> + <revnumber>6.1.0-3</revnumber> + <date>Wed May 15 2013</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Corrected all images in the book to conform to Section 508 Guidelines.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.1.0-2</revnumber> <date>Fri Apr 05 2013</date> <author> Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/SAML2.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/SAML2_Salesforce_and_Google_Integration.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/SSO.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/chapter-3-Command_Line_Interface.xml =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/chapter-3-Command_Line_Interface.xml 2013-05-14 06:10:36 UTC (rev 9277) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/chapter-3-Command_Line_Interface.xml 2013-05-15 02:20:21 UTC (rev 9278) @@ -5,9 +5,8 @@ ]> <chapter id="sid-8094332_GateInManagement-CommandLineInterface"> <title>Command Line Interface</title> - <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL36/GateIn+Management - </remark> - <para>The command line interface (CLI) component provides an interactive shell using CRaSH to map commands to management requests. It connects over SSH, using the CRaSH SSH plugin.</para> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL36/GateIn+Management </remark> + <para>The command line interface (CLI) component provides an interactive shell using CRaSH to map commands to management requests. It connects over SSH, using the CRaSH SSH plug-in.</para> <note> <title>Note</title> <para> @@ -257,7 +256,7 @@ </para> <important> <title>Important</title> - <para>Since the CLI is connected to the portal server over SSH, the export command will write to the server's file system, not that of the client.</para> + <para>Since the CLI is connected to the portal server over SSH, the export command will write to the server's file system, not that of the client.</para> </important> <example> <title>export help</title> Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/chapter-5-Administration_and_Monitoring.xml =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/chapter-5-Administration_and_Monitoring.xml 2013-05-14 06:10:36 UTC (rev 9277) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/chapter-5-Administration_and_Monitoring.xml 2013-05-15 02:20:21 UTC (rev 9278) @@ -5,8 +5,7 @@ ]> <chapter id="Administration_and_Monitoring"> <title><remark>BZ#856436</remark>JBoss Operations Network GateIn JON Plug-in</title> - <remark>The content does not match with the latest content on Confluence at: https://docs.jboss.org/author/display/GTNPORTAL36/Administration+and+Moni... - </remark> + <remark>The content does not match with the latest content on Confluence at: https://docs.jboss.org/author/display/GTNPORTAL36/Administration+and+Moni... </remark> <para>JBoss Portal Platform provides a JBoss Operations Network plug-in (<firstterm>GateIn JON Plug-in</firstterm>) to assist with monitoring the platform.</para> <para>The plug-in captures application/portlet and site statistics. A different set of statistics are collected depending on the context of each portlet. <xref linkend="fig-GateIn_JON_Plug-in_Interface"/> shows the basic JON interface.</para> <para>Follow the download and installation instructions in the <citetitle>Installation Guide</citetitle> to activate administration and monitoring.</para> @@ -18,7 +17,7 @@ <imagedata contentwidth="660px" fileref="images/GateIn-RHQ-Plugin.png"/> </imageobject> <textobject> - <para>Screenshot of the JON console view, with the GateIn AS7 Plug-in highlighted.</para> + <phrase>Screen shot of the JON console view, with the GateIn AS7 Plug-in highlighted.</phrase> </textobject> </mediaobject> </figure> Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/extras/default151.xml =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/extras/default151.xml (rev 0) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/extras/default151.xml 2013-05-15 02:20:21 UTC (rev 9278) @@ -0,0 +1,36 @@ +<component> + <key>org.exoplatform.services.resources.ResourceBundleService</key> + <type>org.exoplatform.services.resources.impl.SimpleResourceBundleService</type> + <init-params> +  + <values-param> + <name>classpath.resources</name> + <description>The resources that start with the following package name should be load from file system</description> + <value>locale.portlet</value> + </values-param> +  + <values-param> + <name>init.resources</name> + <description>Initiate the following resources during the first launch</description> + <value>locale.portal.expression</value> + <value>locale.portal.services</value> + <value>locale.portal.webui</value> + <value>locale.portal.custom</value> + <value>locale.navigation.portal.classic</value> + <value>locale.navigation.group.platform.administrators</value> + <value>locale.navigation.group.platform.users</value> + <value>locale.navigation.group.platform.guests</value> + <value>locale.navigation.group.organization.management.executive-board</value> + </values-param> +  + <values-param> + <name>portal.resource.names</name> + <description>The properties files of the portal , those file will be merged + into one ResoruceBundle properties </description> + <value>locale.portal.expression</value> + <value>locale.portal.services</value> + <value>locale.portal.webui</value> + <value>locale.portal.custom</value> + </values-param> + </init-params> +</component> Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/LanguageChoice.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/LanguageChoice.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/cas.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/cas.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/josso.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/josso.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/loginScreen.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/loginScreen.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/openam.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/openam.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/salesforce-idp.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/salesforce-idp.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/salesforce-sp.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/salesforce-sp.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/saml-sso.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/saml-sso.png ___________________________________________________________________ Added: svn:mime-type + image/png

11 years, 7 months

1
0
0 / 0

gatein SVN: r9277 - epp/docs/JPP/trunk/Development_Guide/en-US.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-05-14 02:10:36 -0400 (Tue, 14 May 2013) New Revision: 9277 Modified: epp/docs/JPP/trunk/Development_Guide/en-US/AccessingUserProfile.xml epp/docs/JPP/trunk/Development_Guide/en-US/Architectural_Choices.xml epp/docs/JPP/trunk/Development_Guide/en-US/Data_Import_Strategy.xml epp/docs/JPP/trunk/Development_Guide/en-US/Design_Choices.xml epp/docs/JPP/trunk/Development_Guide/en-US/JavaScript_Modularity.xml epp/docs/JPP/trunk/Development_Guide/en-US/JavaScript_in_JBoss_Portal_Platform.xml epp/docs/JPP/trunk/Development_Guide/en-US/Module_Resources.xml epp/docs/JPP/trunk/Development_Guide/en-US/Navigation_Controller.xml epp/docs/JPP/trunk/Development_Guide/en-US/OrganizationAPI.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Extension.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Development.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Development_Resources.xml epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml epp/docs/JPP/trunk/Development_Guide/en-US/Skinning_The_Portal.xml epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml epp/docs/JPP/trunk/Development_Guide/en-US/eXo_JCR.xml Log: All images now have correct alt text as part of numerous BZ issues raised against the guide. Modified: epp/docs/JPP/trunk/Development_Guide/en-US/AccessingUserProfile.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Architectural_Choices.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Data_Import_Strategy.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Design_Choices.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/JavaScript_Modularity.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/JavaScript_in_JBoss_Portal_Platform.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Module_Resources.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Navigation_Controller.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/OrganizationAPI.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Extension.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Development.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Development_Resources.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml 2013-05-09 06:14:53 UTC (rev 9276) +++ epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml 2013-05-14 06:10:36 UTC (rev 9277) @@ -8,6 +8,20 @@ <simpara> <revhistory> <revision> + <revnumber>6.1.0-7</revnumber> + <date>Tue May 14 2013</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>All images in this guide are now compliant with Section 508 guidelines. Next task is to check figures, tables, and examples for IDREFs to the Reference Guide, and normalize these entries.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.1.0-6</revnumber> <date>Wed May 8 2013</date> <author> Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Skinning_The_Portal.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/eXo_JCR.xml =================================================================== (Binary files differ)

11 years, 7 months

1
0
0 / 0

gatein SVN: r9276 - in epp/docs/JPP/trunk: Reference_Guide/en-US and 1 other directories.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-05-09 02:14:53 -0400 (Thu, 09 May 2013) New Revision: 9276 Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml epp/docs/JPP/trunk/Development_Guide/en-US/appendix-Quickstarts.xml epp/docs/JPP/trunk/Development_Guide/en-US/eXo_JCR.xml epp/docs/JPP/trunk/Reference_Guide/en-US/Reference_Guide.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/eXoJCR.xml Log: Corrected IDREFS in the eXoJCR section to remove reference to the Reference Guide Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml 2013-05-08 07:02:26 UTC (rev 9275) +++ epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml 2013-05-09 06:14:53 UTC (rev 9276) @@ -8,6 +8,20 @@ <simpara> <revhistory> <revision> + <revnumber>6.1.0-6</revnumber> + <date>Wed May 8 2013</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>eXo JCR ID refs normalized to remove all reference to Reference Guide. Next task is to check figures, tables, and examples for links to Reference Guide, and normalize.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.1.0-5</revnumber> <date>Wed May 8 2013</date> <author> Modified: epp/docs/JPP/trunk/Development_Guide/en-US/appendix-Quickstarts.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/appendix-Quickstarts.xml 2013-05-08 07:02:26 UTC (rev 9275) +++ epp/docs/JPP/trunk/Development_Guide/en-US/appendix-Quickstarts.xml 2013-05-09 06:14:53 UTC (rev 9276) @@ -3,7 +3,7 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent"> %BOOK_ENTITIES; ]> -<appendix id="Appendix_-_Quickstarts"> +<appendix id="Quickstarts"> <title>Quickstarts</title> <para>JBoss Portal Platform Quickstarts provide small, specific, working examples that can be used as a reference for your own project.</para> <para>The Quickstarts can be obtained in one of the following ways:</para> Modified: epp/docs/JPP/trunk/Development_Guide/en-US/eXo_JCR.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/Reference_Guide.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/Reference_Guide.xml 2013-05-08 07:02:26 UTC (rev 9275) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/Reference_Guide.xml 2013-05-09 06:14:53 UTC (rev 9276) @@ -13,6 +13,5 @@ <title>Web Services for Remote Portlets (WSRP)</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/WSRP.xml"/> </part> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/eXoJCR.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/> </book> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/eXoJCR.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/eXoJCR.xml 2013-05-08 07:02:26 UTC (rev 9275) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/eXoJCR.xml 2013-05-09 06:14:53 UTC (rev 9276) @@ -132,7 +132,7 @@ Source License: http://www.day.com/specs/jcr/2.0/license.html] --> </section> </chapter> <chapter xmlns="" id="chap-Reference_Guide-Implementation"> - <title>Implementation</title> + <title>Implementation</title> <para> The relationships between the eXo Repository Service components are illustrated below: </para> @@ -1014,4620 +1014,24 @@ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_multilanguage-support/default58.xml" parse="text"/></programlisting> </section> </chapter> - <chapter xmlns="" id="chap-Reference_Guide-Search_Configuration"> - <title>Configuring Search</title> - <para> - The search function in JCR can be configured to perform in specific ways. This section will discuss configuring the search function to improve search performance and results. - </para> - <para> - Below is an example of the configuration file that governs search behaviors. Refer to <xref linkend="sect-Reference_Guide-Search_Configuration-Global_Search_Index"/> for how searching operates in JCR and information about customized searches. - </para> - <para> - The JCR index configuration file is located at <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. - </para> - <para> - A code example is included below with a list of the configuration parameters shown below that. - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default61.xml" parse="text"/></programlisting> - <para> - The table below outlines <emphasis role="bold">some</emphasis> of the Configuration Parameters available, their default setting, which version of eXo JCR they were implemented in and other useful information (further parameters are explained in <xref linkend="sect-Reference_Guide-JBoss_Cache_configuration-Indexer_lock_manager_and_data_container_configuration"/>): - </para> - <table id="tabl-Reference_Guide-Search_Configuration-Configuration_parameters"> - <title>Configuration parameters</title> - <tgroup cols="4"> - <colspec colname="1" colwidth="90pt"/> - <colspec colname="2" colwidth="90pt"/> - <colspec colname="3" colwidth="150pt"/> - <colspec colname="4" colwidth="50pt"/> - <thead> - <row> - <entry> - <para> - Parameter - </para> - </entry> - <entry> - <para> - Default - </para> - </entry> - <entry> - <para> - Description - </para> - </entry> - <entry> Implemented in Version </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para> - index-dir - </para> - </entry> - <entry> - <para> - none - </para> - </entry> - <entry> - <para> - The location of the index directory. This parameter is mandatory. It is called "<literal>indexDir</literal>" in versions prior to eXo JCR version 1.9. - </para> - </entry> - <entry> 1.0 </entry> - </row> - <row> - <entry> - <para> - use-compoundfile - </para> - </entry> - <entry> - <para> - true - </para> - </entry> - <entry> - <para> - Advises lucene to use compound files for the index files. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - min-merge-docs - </para> - </entry> - <entry> - <para> - 100 - </para> - </entry> - <entry> - <para> - The minimum number of nodes in an index until segments are merged. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - volatile-idle-time - </para> - </entry> - <entry> 3 </entry> - <entry> - <para> - Idle time in seconds until the volatile index part is moved to a persistent index even though <literal>minMergeDocs</literal> is not reached. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - max-merge-docs - </para> - </entry> - <entry> - <para> - Integer.MAX_VALUE - </para> - </entry> - <entry> - <para> - The maximum number of nodes in segments that will be merged. The default value changed to <literal>Integer.MAX_VALUE</literal> in eXo JCR version 1.9. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - merge-factor - </para> - </entry> - <entry> - <para> - 10 - </para> - </entry> - <entry> - <para> - Determines how often segment indices are merged. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - max-field-length - </para> - </entry> - <entry> - <para> - 10000 - </para> - </entry> - <entry> - <para> - The number of words that are full-text indexed at most per property. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - cache-size - </para> - </entry> - <entry> - <para> - 1000 - </para> - </entry> - <entry> - <para> - Size of the document number cache. This cache maps UUID to lucene document numbers - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - force-consistencycheck - </para> - </entry> - <entry> - <para> - false - </para> - </entry> - <entry> - <para> - Runs a consistency check on every start up. If false, a consistency check is only performed when the search index detects a prior forced shutdown. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - auto-repair - </para> - </entry> - <entry> - <para> - true - </para> - </entry> - <entry> - <para> - Errors detected by a consistency check are automatically repaired. If false, errors are only written to the log. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> query-class </entry> - <entry> QueryImpl </entry> - <entry> - <para> - Classname that implements the javax.jcr.query.Query interface. - </para> - <para> - This class must also extend from the class: <literal>org.exoplatform.services.jcr.impl.core. query.AbstractQueryImpl</literal>. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - document-order - </para> - </entry> - <entry> - <para> - true - </para> - </entry> - <entry> - <para> - If true and the query does not contain an 'order by' clause, result nodes will be in document order. For better performance set to 'false' when queries return many nodes. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - result-fetch-size - </para> - </entry> - <entry> - <para> - Integer.MAX_VALUE - </para> - </entry> - <entry> - <para> - The number of results when a query is executed. Default value: <literal>Integer.MAX_VALUE</literal>. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - excerptprovider-class - </para> - </entry> - <entry> - <para> - DefaultXMLExcerpt - </para> - </entry> - <entry> - <para> - The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.ExcerptProvider</literal>. - </para> - <para> - This should be used for the <literal>rep:excerpt()</literal> function in a query. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - support-highlighting - </para> - </entry> - <entry> - <para> - false - </para> - </entry> - <entry> - <para> - If set to true additional information is stored in the index to support highlighting using the <literal>rep:excerpt()</literal> function. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - synonymprovider-class - </para> - </entry> - <entry> - <para> - none - </para> - </entry> - <entry> - <para> - The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.SynonymProvider</literal>. - </para> - <para> - The default value is null. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - synonymprovider-config-path - </para> - </entry> - <entry> - <para> - none - </para> - </entry> - <entry> - <para> - The path to the synonym provider configuration file. This path is interpreted relative to the path parameter. If there is a path element inside the <literal>SearchIndex</literal> element, then this path is interpreted relative to the root path of the path. Whether this parameter is mandatory depends on the synonym provider implementation. The default value is null. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - indexing-configuration-path - </para> - </entry> - <entry> - <para> - none - </para> - </entry> - <entry> - <para> - The path to the indexing configuration file. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - indexing-configuration-class - </para> - </entry> - <entry> - <para> - IndexingConfigurationImpl - </para> - </entry> - <entry> - <para> - The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.IndexingConfiguration</literal>. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - force-consistencycheck - </para> - </entry> - <entry> - <para> - false - </para> - </entry> - <entry> - <para> - If set to true a consistency check is performed depending on the parameter <literal>forceConsistencyCheck</literal>. If set to false no consistency check is performed on start up, even if a redo log had been applied. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - spellchecker-class - </para> - </entry> - <entry> - <para> - none - </para> - </entry> - <entry> - <para> - The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.SpellChecker</literal>. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - errorlog-size - </para> - </entry> - <entry> - <para> - 50(KB) - </para> - </entry> - <entry> - <para> - The default size of error log file in KB. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - upgrade-index - </para> - </entry> - <entry> - <para> - false - </para> - </entry> - <entry> - <para> - Allows JCR to convert an existing index into the new format. It is also possible to set this property via system property. - </para> - <para> - Indexes prior to eXo JCR 1.12 will not run with eXo JCR 1.12. You must run an automatic migration. - </para> - <para> - Start eXo JCR with: - </para> - <programlisting><command> -Dupgrade-index=true</command></programlisting> - <para> - The old index format is then converted in the new index format. After the conversion the new format is used. - </para> - <para> - On subsequent starts this option is no longer needed. The old index is replaced and a back conversion is not possible - </para> - <para> - It is recommended that a backup of the index be made before conversion. (Only for migrations from JCR 1.9 and later.) - </para> - </entry> - <entry> 1.12 </entry> - </row> - <row> - <entry> - <para> - analyzer - </para> - </entry> - <entry> - <para> - org.apache.lucene.analysis. standard.StandardAnalyzer - </para> - </entry> - <entry> - <para> - Class name of a lucene analyzer to use for full-text indexing of text. - </para> - </entry> - <entry> 1.12 </entry> - </row> - </tbody> - </tgroup> - </table> - <section id="sect-Reference_Guide-Search_Configuration-Global_Search_Index"> - <title>Global Search Index</title> - <para> - By default eXo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content - </para> - <example> - <title>Standard Analyzed Filters</title> - <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default62.java" parse="text"/></programlisting> - <para> - Comment #1: The first filter (StandardFilter) removes possessive apostrophes (<emphasis role="bold">'s</emphasis>) from the end of words and removes periods (<emphasis role="bold">.</emphasis>) from acronyms. - </para> - <para> - Comment #2: The second filter (LowerCaseFilter) normalizes token text to lower case. - </para> - <para> - Comment #3: The last filter (StopFilter) removes stop words from a token stream. The stop set is defined in the analyzer. - </para> - </example> - <para> - The global search index is configured in the <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the "query-handler" tag. - </para> - <programlisting language="XML" role="XML"><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> -</programlisting> - <para> - The same analyzer should always be used for indexing and for querying in lucene otherwise results may be unpredictable. eXo JCR does this automatically. The StandardAnalyzer (configured by default) can, however, be replaced with another. - </para> - <para> - A customized QueryHandler can also be easily created. - </para> - <formalpara id="form-Reference_Guide-Global_Search_Index-Customized_Search_Indexes_and_Analyzers"> - <title>Customized Search Indexes and Analyzers</title> - <para> - By default Exo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content: - </para> - </formalpara> - <programlisting language="Java" role="Java">public TokenStream tokenStream(String fieldName, Reader reader) { - StandardTokenizer tokenStream = new StandardTokenizer(reader, replaceInvalidAcronym); - tokenStream.setMaxTokenLength(maxTokenLength); - TokenStream result = new StandardFilter(tokenStream); - result = new LowerCaseFilter(result); - result = new StopFilter(result, stopSet); - return result; - }</programlisting> - <itemizedlist> - <listitem> - <para> - The first one (StandardFilter) removes 's (as 's in "Peter's") from the end of words and removes dots from acronyms. - </para> - </listitem> - <listitem> - <para> - The second one (LowerCaseFilter) normalizes token text to lower case. - </para> - </listitem> - <listitem> - <para> - The last one (StopFilter) removes stop words from a token stream. The stop set is defined in the analyzer. - </para> - </listitem> - </itemizedlist> - <para> - Additional filters can be used in specific cases. The <phrase>ISOLatin1AccentFilter</phrase> filter, for example, which replaces accented characters in the ISO Latin 1 character set (ISO-8859-1) by their unaccented equivalents. - </para> - <para> - The <phrase>ISOLatin1AccentFilter</phrase> is not present in the current lucene version used by eXo. - </para> - <para> - In order to use a different filter, a new analyzer must be created, as well as new search index to use the analyzer. These are packaged into a jar file, which is then deployed with the application. - </para> - <procedure id="proc-Reference_Guide-Global_Search_Index-Create_a_new_filter_analyzer_and_search_index"> - <title>Create a new filter, analyzer and search index</title> - <step> - <para> - Create a new filter with the method: - </para> - <programlisting language="Java" role="JAVA">public final Token next(final Token reusableToken) throws java.io.IOException -</programlisting> - <para> - This defines how characters are read and used by the filter. - </para> - </step> - <step> - <para> - Create the analyzer. - </para> - <para> - The analyzer must extend <literal>org.apache.lucene.analysis.standard.StandardAnalyzer</literal> and overload the method. - </para> - <para> - Use the following to use new filters. - </para> - <programlisting language="Java" role="JAVA">public TokenStream tokenStream(String fieldName, Reader reader) -</programlisting> - </step> - <step> - <para> - To create the new search index, extend <literal>org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex</literal> and write the constructor to set the correct analyzer. - </para> - <para> - Use the method below to return your analyzer: - </para> - <programlisting language="Java" role="JAVA">public Analyzer getAnalyzer() { -return MyAnalyzer; -} -</programlisting> - </step> - </procedure> - <note> - <para> - In eXo JCR version 1.12 (and later) the analyzer can be directly set in the configuration. For users with this version the creation of a new SearchIndex for new analyzers is redundant. - </para> - </note> - <para> - To configure an application to use a new <literal>SearchIndex</literal>, replace the following code: - </para> - <programlisting language="XML" role="XML"><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - -</programlisting> - <para> - in <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> with the new class: - </para> - <programlisting language="XML" role="XML"><query-handler class="mypackage.indexation.MySearchIndex> - -</programlisting> - <para> - To configure an application to use a new analyzer, add the <parameter>analyzer</parameter> parameter to each query-handler configuration in <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default69.xml" parse="text"/></programlisting> - <para> - The new <literal>SearchIndex</literal> will start to index contents with the specified filters when the JCR is next started. - </para> - </section> - <section id="sect-Reference_Guide-Search_Configuration-IndexingConfiguration"> - <title>IndexingConfiguration</title> - <para> - From version 1.9, the default search index implementation in JCR allows user control over which properties of a node are indexed. Different analyzers can also be set for different nodes. - </para> - <para> - The configuration parameter is called <literal>indexingConfiguration</literal> and is not set by default. This means all properties of a node are indexed. - </para> - <para> - To configure the indexing behavior add a parameter to the query-handler element in your configuration file. - </para> - <programlisting language="XML" role="XML"><param name="indexing-configuration-path" value="/indexing_configuration.xml"/> - -</programlisting> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Node_Scope_Limit"> - <title>Node Scope Limit</title> - <para> - The node scope can be limited so that only certain properties of a node type are indexed. This can optimize the index size. - </para> - </formalpara> - <para> - With the configuration below only properties named <parameter>Text</parameter> are indexed for <parameter>nt:unstructured</parameter> node types. This configuration also applies to all nodes whose type extends from <parameter>nt:unstructured</parameter>. - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default71.xml" parse="text"/></programlisting> - <note> - <title>Namespace Prefixes</title> - <para> - The <phrase>namespace prefixes</phrase> must be declared throughout the XML file in the configuration element that is being used. - </para> - </note> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Indexing_Boost_Value"> - <title>Indexing Boost Value</title> - <para> - It is also possible to configure a <phrase>boost value</phrase> for the nodes that match the index rule. The default boost value is 1.0. Higher boost values (a reasonable range is 1.0 - 5.0) will yield a higher score value and appear as more relevant. - </para> - </formalpara> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default72.xml" parse="text"/></programlisting> - <para> - If you do not wish to boost the complete node, but only certain properties, you can also provide a boost value for the listed properties: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default73.xml" parse="text"/></programlisting> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Conditional_Index_Rules"> - <title>Conditional Index Rules</title> - <para> - You may also add a <phrase>condition</phrase> to the index rule and have multiple rules with the same nodeType. The first index rule that matches will apply and all remaining ones are ignored: - </para> - </formalpara> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default74.xml" parse="text"/></programlisting> - <para> - In the above example the first rule only applies if the <parameter>nt:unstructured</parameter> node has a priority property with a value <parameter>high</parameter>. The condition syntax only supports the equals operator and a string literal. - </para> - <para> - Properties may also be referenced on the condition that are not on the current node: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default75.xml" parse="text"/></programlisting> - <para> - The indexing configuration allows the type of a node in the condition to be specified. Please note however that the type match must be exact. It does not consider sub types of the specified node type. - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default76.xml" parse="text"/></programlisting> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Exclusion_from_the_Node_Scope_Index"> - <title>Exclusion from the Node Scope Index</title> - <para> - All configured properties are full-text indexed by default (if they are of type STRING and included in the node scope index). - </para> - </formalpara> - <para> - A node scope search normally finds all nodes of an index. That is to say; <literal>jcr:contains(., 'foo')</literal> returns all nodes that have a string property containing the word '<replaceable>foo</replaceable>'. - </para> - <para> - Properties can be explicitly excluded from the node scope index with: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default77.xml" parse="text"/></programlisting> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Index_Aggregates"> - <title>Index Aggregates</title> - <para> - Sometimes it is useful to include the contents of descendant nodes into a single node to more easily search on content that is scattered across multiple nodes. - </para> - </formalpara> - <para> - JCR allows the definition of index aggregates based on relative path patterns and primary node types. - </para> - <para> - The following example creates an index aggregate on <literal>nt:file</literal> that includes the content of the jcr:content node: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default78.xml" parse="text"/></programlisting> - <para> - Included nodes can also be restricted to a certain type: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default79.xml" parse="text"/></programlisting> - <para> - The <emphasis role="bold">*</emphasis> wild-card can be used to match all child nodes: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default80.xml" parse="text"/></programlisting> - <para> - Nodes to a certain depth below the current node can be included by adding multiple include elements. The <parameter>nt:file</parameter> node may contain a complete XML document under jcr:content for example: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default81.xml" parse="text"/></programlisting> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Property_Level_Analyzers"> - <title>Property-Level Analyzers</title> - <para> - How a property has to be analyzed can be defined in the following configuration section. If there is an analyzer configuration for a property, this analyzer is used for indexing and searching of this property. For example: - </para> - </formalpara> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default82.xml" parse="text"/></programlisting> - <para> - The configuration above sets lucene <emphasis role="bold">KeywordAnalyzer</emphasis> to index and search the property "<replaceable>mytext</replaceable>" across the entire workspace while the "<replaceable>mytext2</replaceable>" property is searched with the <emphasis role="bold">WhitespaceAnalyzer</emphasis>. - </para> - <para> - The <emphasis role="bold">WhitespaceAnalyzer</emphasis> tokenizes a property, the <emphasis role="bold">KeywordAnalyzer</emphasis> takes the property as a whole. - </para> - <para> - Using different analyzers for different languages can be particularly useful. - </para> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Characteristics_of_Node_Scope_Searches"> - <title>Characteristics of Node Scope Searches</title> - <para> - Unexpected behavior may be encountered when using analyzers to search within a <emphasis>property</emphasis> compared to searching within a <emphasis>node scope</emphasis>. This is because the node scope always uses the global analyzer. - </para> - </formalpara> - <para> - For example: the property "<parameter>mytext</parameter>" contains the text; "<emphasis>testing my analyzers</emphasis>" but no analyzers have been configured for this property (and the default analyzer in SearchIndex has not been changed). - </para> - <para> - If the query is: - </para> - <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(mytext,'analyzer')]" -</programlisting> - <para> - The <literal>xpath</literal> does not return a result in the node with the property above and default analyzers. - </para> - <para> - Also, if a search is done on the node scope as follows: - </para> - <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(.,'analyzer')]" -</programlisting> - <para> - No result will be returned. - </para> - <para> - Only specific analyzers can be set on a node property, and the node scope indexing and analyzing is always done with the globally defined analyzer in the SearchIndex element. - </para> - <para> - If the analyzer used to index the "mytext" property above is changed to: - </para> - <programlisting language="XML" role="XML"><analyzer class="org.apache.lucene.analysis.Analyzer.GermanAnalyzer"> -<property>mytext</property> -</analyzer> -</programlisting> - <para> - The search below would return a result because of the word stemming (analyzers - analyzer). - </para> - <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(mytext,'analyzer')]" -</programlisting> - <para> - The second search in the example: - </para> - <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(.,'analyzer')]" -</programlisting> - <para> - Would still not give a result, since the node scope is indexed with the global analyzer, which in this case does not take into account any word stemming. - </para> - <para> - Be aware that when using analyzers for specific properties, a result may be found in a property for certain search text, but the same search text in the node scope of the property may not find a result. - </para> - <note> - <para> - Both index rules and index aggregates influence how content is indexed in JCR. If the configuration is changed, the existing content is not automatically re-indexed according to the new rules. - </para> - <para> - Content must be manually re-indexed when the configuration is changed. - </para> - </note> - </section> - <section id="sect-Reference_Guide-Search_Configuration-Advanced_features"> - <title>Advanced features</title> - <para> - eXo JCR supports some advanced features, which are not specified in JSR 170: - </para> - <itemizedlist> - <listitem> - <para> - Get a text excerpt with <emphasis role="bold">highlighted words</emphasis> that matches the query: <xref linkend="sect-Reference_Guide-Highlighting-DefaultXMLExcerpt"/>>. - </para> - </listitem> - <listitem> - <para> - Search a term and its <emphasis role="bold">synonyms</emphasis>: <xref linkend="sect-Reference_Guide-Searching_Repository_Content-SynonymSearch"/>. - </para> - </listitem> - <listitem> - <para> - Search <emphasis role="bold">similar</emphasis> nodes: <xref linkend="sect-Reference_Guide-Searching_Repository_Content-Similarity"/>. - </para> - </listitem> - <listitem> - <para> - Check <emphasis role="bold">spelling</emphasis> of a full text query statement: <xref linkend="sect-Reference_Guide-Searching_Repository_Content-SpellChecker"/>. - </para> - </listitem> - <listitem> - <para> - Define index <emphasis role="bold">aggregates and rules</emphasis>: IndexingConfiguration. - </para> - </listitem> - </itemizedlist> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-JDBC_Data_Container_Config"> - <title>Configuring the JDBC Data Container</title> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Introduction"> - <title>Introduction</title> - <para> - eXo JCR persistent data container can work in two configuration modes: - </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> - <para> - Currently the data container is tested with the following RDBMS: - </para> - <table id="tabl-Reference_Guide-Introduction-Supported-databases"> - <title>Supported databases</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Database </entry> - <entry> Driver Version </entry> - </row> - </thead> - <tbody> - <row> - <entry> IBM DB2 9.7 (FP5) </entry> - <entry> IBM DB2 JDBC Universal Driver Architecture 4.13.80 </entry> - </row> - <row> - <entry> Oracle 11g R1 (11.1.0.7.0) </entry> - <entry> Oracle JDBC Driver 11.1.0.7 </entry> - </row> - <row> - <entry> Oracle 11g R1 RAC (11.1.0.7.0) </entry> - <entry> Oracle JDBC Driver 11.1.0.7 </entry> - </row> - <row> - <entry> Oracle 11g R2 (11.2.0.3.0) </entry> - <entry> Oracle JDBC Driver v11.2.0.3.0 </entry> - </row> - <row> - <entry> Oracle 11g R2 RAC (11.2.0.3.0) </entry> - <entry> Oracle JDBC Driver v11.2.0.3.0 </entry> - </row> - <row> - <entry> MySQL 5.1 </entry> - <entry> MySQL Connector/J 5.1.21 </entry> - </row> - <row> - <entry> MySQL 5.5 </entry> - <entry> MySQL Connector/J 5.1.21 </entry> - </row> - <row> - <entry> Microsoft SQL Server 2008 </entry> - <entry> Microsoft SQL Server JDBC Driver 3.0.1301.101, Microsoft SQL Server JDBC Driver 4.0.2206.100 </entry> - </row> - <row> - <entry> Microsoft SQL Server 2008 R2 </entry> - <entry> Microsoft SQL Server JDBC Driver 3.0.1301.101, Microsoft SQL Server JDBC Driver 4.0.2206.100 </entry> - </row> - <row> - <entry> PostgreSQL 8.4.8 </entry> - <entry> JDBC4 Postgresql Driver, Version 8.4-703 </entry> - </row> - <row> - <entry> PostgreSQL 9.1.0 </entry> - <entry> JDBC4 Postgresql Driver, Version 9.1-903 </entry> - </row> - <row> - <entry> Sybase ASE 15.7 </entry> - <entry> Sybase jConnect JDBC driver v7 </entry> - </row> - </tbody> - </tgroup> - </table> - <note> - <title>Isolation Levels</title> - <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">here.</ulink> - </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> - <remark>NEEDINFO - FILE PATHS - The path needs to be updated with the equivalent path for JBoss Portal Platform instead of gatein, please see below para. New info required?</remark> - <para> - You can find SQL-scripts in <filename>conf/storage/</filename> directory of the <filename><replaceable>JPP_HOME</replaceable>/modules/org/gatein/lib/main/exo.jcr.component.core-&JCR_VERSION;.jar</filename> file . - </para> - <para> - The following tables show the correspondence between the scripts and databases: - </para> - <table id="tabl-Reference_Guide-Introduction-Single_database"> - <title>Single-database</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Database </entry> - <entry> Script </entry> - </row> - </thead> - <tbody> - <row> - <entry> MySQL DB </entry> - <entry> - <filename>jcr-sjdbc.mysql.sql</filename> - </entry> - </row> - <row> - <entry> MySQL DB with utf-8 </entry> - <entry> - <filename>jcr-sjdbc.mysql-utf8.sql</filename> - </entry> - </row> - <row> - <entry> PostgresSQL </entry> - <entry> - <filename>jcr-sjdbc.pqsql.sql</filename> - </entry> - </row> - <row> - <entry> Oracle DB </entry> - <entry> - <filename>jcr-sjdbc.ora.sql</filename> - </entry> - </row> - <row> - <entry> DB2 9.7 </entry> - <entry> - <filename>jcr-sjdbc.db2.sql</filename> - </entry> - </row> - <row> - <entry> MS SQL Server </entry> - <entry> - <filename>jcr-sjdbc.mssql.sql</filename> - </entry> - </row> - <row> - <entry> Sybase </entry> - <entry> - <filename>jcr-sjdbc.sybase.sql</filename> - </entry> - </row> - <row> - <entry> HSQLDB </entry> - <entry> - <filename>jcr-sjdbc.sql</filename> - </entry> - </row> - </tbody> - </tgroup> - </table> - <table id="tabl-Reference_Guide-Introduction-Multi_database"> - <title>Multi-database</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Database </entry> - <entry> Script </entry> - </row> - </thead> - <tbody> - <row> - <entry> MySQL DB </entry> - <entry> - <filename>jcr-mjdbc.mysql.sql</filename> - </entry> - </row> - <row> - <entry> MySQL DB with utf-8 </entry> - <entry> - <filename>jcr-mjdbc.mysql-utf8.sql</filename> - </entry> - </row> - <row> - <entry> PostgresSQL </entry> - <entry> - <filename>jcr-mjdbc.pqsql.sql</filename> - </entry> - </row> - <row> - <entry> Oracle DB </entry> - <entry> - <filename>jcr-mjdbc.ora.sql</filename> - </entry> - </row> - <row> - <entry> DB2 9.7 </entry> - <entry> - <filename>jcr-mjdbc.db2.sql</filename> - </entry> - </row> - <row> - <entry> MS SQL Server </entry> - <entry> - <filename>jcr-mjdbc.mssql.sql</filename> - </entry> - </row> - <row> - <entry> Sybase </entry> - <entry> - <filename>jcr-mjdbc.sybase.sql</filename> - </entry> - </row> - <row> - <entry> HSQLDB </entry> - <entry> - <filename>jcr-mjdbc.sql</filename> - </entry> - </row> - </tbody> - </tgroup> - </table> - <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-&JCR_VERSION;.jar</package> or source-distribution of eXo JCR implementation. - </para> - <example id="exam-Reference_Guide-Introduction-Example_Parameter"> - <title>Example Parameter</title> - <programlisting><code>jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8</code></programlisting> - </example> - <para> - The configuration files are located in service jars <filename>/conf/portal/configuration.xml</filename> (eXo services including JCR Repository Service) and <filename>exo-jcr-config.xml</filename> (repositories configuration) by default. In JBoss Portal Platform, the JCR is configured in portal web application <filename>portal/WEB-INF/conf/jcr/jcr-configuration.xml</filename> (JCR Repository Service and related services) and <filename>repository-configuration.xml</filename> (repositories configuration). - </para> - <para> - Read more about <xref linkend="chap-Reference_Guide-JCR_configuration"/>. - </para> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Multi_database_Configuration"> - <title>Multi-database Configuration</title> - <para> - You need to configure each workspace in a repository as part of multi-database configuration. Databases may reside on remote servers as required. - </para> - <procedure> - <title/> - <step> - <para> - Configure the data containers in the <literal>org.exoplatform.services.naming.InitialContextInitializer</literal> service. It's the JNDI context initializer which registers (binds) naming resources (DataSources) for data containers. - </para> - <para> - For example (two data containers <parameter>jdbcjcr</parameter> - local HSQLDB, <parameter>jdbcjcr1</parameter> - remote MySQL): - </para> - <programlisting language="XML" role="XML"> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/example-1.xml" parse="text"/></programlisting> - <substeps> - <step> - <para> - Configure the database connection parameters: - </para> - <itemizedlist> - <listitem> - <para> - <parameter>driverClassName</parameter>, e.g. "org.hsqldb.jdbcDriver", "com.mysql.jdbc.Driver", "org.postgresql.Driver" - </para> - </listitem> - <listitem> - <para> - <parameter>url</parameter>, e.g. "jdbc:hsqldb:file:target/temp/data/portal", "jdbc:mysql://exoua.dnsalias.net/jcr" - </para> - </listitem> - <listitem> - <para> - <parameter>username</parameter>, e.g. "sa", "exoadmin" - </para> - </listitem> - <listitem> - <para> - <parameter>password</parameter>, e.g. "", "exo12321" - </para> - </listitem> - </itemizedlist> - </step> - </substeps> - <para> - There can be connection pool configuration parameters (org.apache.commons.dbcp.BasicDataSourceFactory): - </para> - <itemizedlist> - <listitem> - <para> - <parameter>maxActive</parameter>, e.g. 50 - </para> - </listitem> - <listitem> - <para> - <parameter>maxIdle</parameter>, e.g. 5 - </para> - </listitem> - <listitem> - <para> - <parameter>initialSize</parameter>, e.g. 5 - </para> - </listitem> - <listitem> - <para> - and other according to <ulink url="http://jakarta.apache.org/commons/dbcp/configuration.html">Apache DBCP configuration</ulink> - </para> - </listitem> - </itemizedlist> - </step> - <step> - <para> - Configure the repository service. Each workspace will be configured for its own data container. - </para> - <para> - For example (two workspaces <parameter>ws</parameter> - jdbcjcr, <parameter>ws1</parameter> - jdbcjcr1): - </para> - <programlisting language="XML" role="XML"> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/example-2.xml" parse="text"/></programlisting> - <itemizedlist> - <listitem> - <para> - <parameter>source-name</parameter>: A javax.sql.DataSource name configured in InitialContextInitializer component (was <parameter>sourceName</parameter> prior JCR 1.9); - </para> - </listitem> - <listitem> - <para> - <parameter>dialect</parameter>: A database dialect, one of <literal>hsqldb</literal>, <literal>mysql</literal>, <literal>mysql-utf8</literal>, <literal>pgsql</literal>, <literal>oracle</literal>, <literal>oracle-oci</literal>, <literal>mssql</literal>, <literal>sybase</literal>, <literal>derby</literal>, <literal>db2</literal>, <literal>db2v8</literal> or <literal>auto</literal> for dialect autodetection; - </para> - </listitem> - <listitem> - <para> - <parameter>multi-db</parameter>: Enable multi-database container with this parameter (set value "true"); - </para> - </listitem> - <listitem> - <para> - <parameter>max-buffer-size: A</parameter> a threshold (in bytes) after which a <literal>javax.jcr.Value</literal> content will be swapped to a file in a temporary storage. A swap for pending changes, for example. - </para> - </listitem> - <listitem> - <para> - <parameter>swap-directory</parameter>: A path in the file system used to swap the pending changes. - </para> - </listitem> - </itemizedlist> - </step> - </procedure> - <para> - This procedure configures two workspace which will be persistent in two different databases (<emphasis>ws</emphasis> in HSQLDB and <emphasis>ws1</emphasis> in MySQL). - </para> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Single_database_Configuration"> - <title>Single-database Configuration</title> - <para> - Configuring a single-database data container is easier than configuring a multi-database data container as only one naming resource must be configured. - </para> - <example id="exam-Reference_Guide-Single_database_Configuration-jdbcjcr_Data_Container"> - <title><parameter>jdbcjcr</parameter> Data Container</title> - <programlisting language="XML" role="XML"> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/example-3.xml" parse="text"/></programlisting> - </example> - <para> - Configure repository workspaces with this one database. The <parameter>multi-db</parameter> parameter must be set as <literal>false</literal>. - </para> - <para> - For example (two workspaces <parameter>ws</parameter> - <literal>jdbcjcr</literal>, <parameter>ws1</parameter> - <literal>jdbcjcr</literal>): - </para> - <example id="exam-Reference_Guide-Single_database_Configuration-Example"> - <title>Example</title> - <programlisting language="XML" role="XML"> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/example-4.xml" parse="text"/></programlisting> - </example> - <para> - This configures two persistent workspaces in one database (PostgreSQL). - </para> - <section id="sect-Reference_Guide-Single_database_Configuration-Configuration_without_DataSource"> - <title>Configuration without DataSource</title> - <para> - It is possible to configure the repository without binding <literal>javax.sql.DataSource</literal> in the JNDI service if you have a dedicated JDBC driver implementation with special features like XA transactions, statements/connections pooling etc: - </para> - <procedure> - <title/> - <step> - <para> - Remove the configuration in <literal>InitialContextInitializer</literal> for your database and configure a new one directly in the workspace container. - </para> - </step> - <step> - <para> - Remove parameter <parameter>source-name</parameter> and add next lines instead. Describe your values for a JDBC driver, database URL and username. - </para> - </step> - </procedure> - <warning> - <title>Connection Pooling</title> - <para> - Ensure the JDBC driver provides connection pooling. Connection pooling is strongly recommended for use with the JCR to prevent a database overload. - </para> - </warning> - <programlisting language="XML" role="XML"><workspace name="ws" auto-init-root-nodetype="nt:unstructured"> - <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> - <properties> - <property name="dialect" value="hsqldb"/> - <property name="driverliteral" value="org.hsqldb.jdbcDriver"/> - <property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/> - <property name="username" value="su"/> - <property name="password" value=""/> - ......</programlisting> - </section> - <section id="sect-Reference_Guide-Single_database_Configuration-Dynamic_Workspace_Creation"> - <title>Dynamic Workspace Creation</title> - <para> - Workspaces can be added dynamically during runtime. - </para> - <para> - This can be performed in two steps: - </para> - <procedure> - <title/> - <step> - <para> - <literal>ManageableRepository.configWorkspace(WorkspaceEntry wsConfig)</literal>: Register a new configuration in RepositoryContainer and create a WorkspaceContainer. - </para> - </step> - <step> - <para> - <literal>ManageableRepository.createWorkspace(String workspaceName)</literal>: Creation a new workspace. - </para> - </step> - </procedure> - </section> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Simple_and_Complex_queries"> - <title>Simple and Complex queries</title> - <para> - eXo JCR provides two ways to interact with the database; - </para> - <variablelist> - <title/> - <varlistentry> - <term> - <literal>JDBCStorageConnection</literal> - </term> - <listitem> - <para> - Which uses simple queries. Simple queries do not use sub queries, left or right joins. They are implemented in such a way as to support as many database dialects as possible. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>CQJDBCStorageConection</literal> - </term> - <listitem> - <para> - Which uses complex queries. Complex queries are optimized to reduce the number of database calls. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Simple queries will be used if you chose <literal>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</literal>: - </para> - <programlisting language="XML" role="XML"><workspaces> - <workspace name="ws" auto-init-root-nodetype="nt:unstructured"> - <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> - ... - </workspace> -</worksapces> -</programlisting> - <para> - Complex queries will be used if you chose <literal>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</literal>: - </para> - <programlisting language="XML" role="XML"><workspaces> - <workspace name="ws" auto-init-root-nodetype="nt:unstructured"> - <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"> - ... - </workspace> -</worksapces></programlisting> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Force_Query_Hints"> - <title>Force Query Hints</title> - <para> - Some databases, such as Oracle and MySQL, support hints to increase query performance. The eXo JCR has separate Complex Query implementations for the Orcale database dialect, which uses query hints to increase performance for few important queries. - </para> - <para> - To enable this option, use the following configuration property: - </para> - <programlisting language="XML" role="XML"><workspace name="ws" auto-init-root-nodetype="nt:unstructured"> - <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> - <properties> - <property name="dialect" value="oracle"/> - <property name="force.query.hints" value="true" /> - ......</programlisting> - <para> - Query hints are only used for Complex Queries with the Oracle dialect. For all other dialects this parameter is ignored. - </para> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Notes_for_Microsoft_Windows_users"> - <title>Notes for Microsoft Windows users</title> - <para> - The current configuration of eXo JCR uses <ulink url="http://commons.apache.org/dbcp/">Apache DBCP</ulink> connection pool (<literal>org.apache.commons.dbcp.BasicDataSourceFactory</literal>). - </para> - <para> - It is possible to set a high value for the <parameter>maxActive</parameter> parameter in the <filename>configuration.xml</filename> file. This creates a high use of TCP/IP ports from a client machine inside the pool (the JDBC driver, for example). As a result, the data container can throw exceptions like "<emphasis>Address already in use</emphasis>". - </para> - <para> - To solve this problem, you must configure the client's machine networking software to use shorter timeouts for open TCP/IP ports. - </para> - <para> - This is done by editing two registry keys within the <parameter>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters</parameter> node. Both of these keys are unset by default. To set the keys as required: - </para> - <procedure> - <title/> - <step> - <para> - Set the <parameter>MaxUserPort</parameter> registry key to <parameter>=dword:00001b58</parameter>. This sets the maximum of open ports to 7000 or higher (the default is 5000). - </para> - </step> - <step> - <para> - Set <parameter>TcpTimedWaitDelay</parameter> to <parameter>=dword:0000001e</parameter>. This sets <parameter>TIME_WAIT</parameter> parameter to 30 seconds (the default is 240). - </para> - </step> - </procedure> - <example id="exam-Reference_Guide-Notes_for_Microsoft_Windows_users-Sample_Registry_File"> - <title>Sample Registry File</title> - <programlisting>Windows Registry Editor Version 5.00 - -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters] -"MaxUserPort"=dword:00001b58 -"TcpTimedWaitDelay"=dword:0000001e</programlisting> - </example> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-External_Value_Storages"> - <title>External Value Storages</title> - <section id="sect-Reference_Guide-External_Value_Storages-Introduction"> - <title>Introduction</title> - <para> - JCR values are stored in the Workspace Data container by default. 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> - Tree-based storage is recommended in most cases. - </para> - </section> - <section id="sect-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage"> - <title>Tree File Value Storage</title> - <para> - Tree File Value Storage holds values in tree-like file system files. <property>Path</property> property points to the root directory to store the files. - </para> - <para> - This is a recommended type of external storage because it can contain large amount of files limited only by disk/volume free space. - </para> - <para> - However, using Tree File Value Storage can result in a higher time on value deletion, due to the removal of unused tree-nodes. - </para> - <example> - <title>Tree File Value Storage Configuration</title> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_external-value-storages/default25.xml" parse="text"/></programlisting> - <para> - Comment #1: The <emphasis role="bold">id</emphasis> is the value storage unique identifier, used for linking with properties stored in a workspace container. - </para> - <para> - Comment #2: the <emphasis role="bold">path</emphasis> is a location where value files will be stored. - </para> - </example> - <para> - Each file value storage can have the <function>filters</function> for incoming values. A filter can match values by <property>property-type</property>, <property>property-name</property>, <property>ancestor-path</property>. It can also match the size of values stored (<property>min-value-size</property>) in bytes. - </para> - <para> - In the previous example a filter with <property>property-type</property> and <property>min-value-size</property> has been used. This results in storage for binary values with size greater of 1MB. - </para> - <para> - It is recommended that properties with large values are stored in file value storage only. - </para> - <para> - The example below shows a value storage with different locations for large files (<property>min-value-size</property> a 20Mb-sized filter). - </para> - <para> - A value storage uses ORed logic in the process of filter selection. This means the first filter in the list will be called first and if it is not matched the next will be called, and so on. - </para> - <para> - In this example a value matches the 20MB filter <property>min-value-size</property> and will be stored in the path "<literal>data/20Mvalues</literal>". All other filters will be stored in "<literal>data/values</literal>". - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_external-value-storages/default26.xml" parse="text"/></programlisting> - </section> - <section id="sect-Reference_Guide-External_Value_Storages-Disabling_value_storage"> - <title>Disabling value storage</title> - <para> - The JCR allows you to disable value storage by adding the following property into its configuration. - </para> - <programlisting language="XML"><property name="enabled" value="false" /></programlisting> - <warning> - <title>Warning</title> - <para> - It is recommended that this functionality be used for internal and testing purpose only, and with caution, as all stored values will be inaccessible. - </para> - </warning> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-Workspace_Data_Container"> - <title>Workspace Data Container</title> - <para> - Each Workspace of the JCR has its own persistent storage to hold that workspace's items data. The eXo JCR can be configured so that it can use one or more workspaces that are logical units of the repository content. - </para> - <para> - The physical data storage mechanism is configured using mandatory element <emphasis role="bold">container</emphasis>. The type of container is described in the attribute <parameter>class = <replaceable>fully_qualified_name_of_org.exoplatform.services.jcr.storage.WorkspaceDataContainer_subclass</replaceable></parameter>. - </para> - <example> - <title>Physical Data Storage Configuration</title> - <programlisting language="XML" role="XML"><container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> - <properties> - <property name="source-name" value="jdbcjcr1"/> - <property name="dialect" value="hsqldb"/> - <property name="multi-db" value="true"/> - <property name="max-buffer-size" value="200K"/> - <property name="swap-directory" value="target/temp/swap/ws"/> - <property name="lazy-node-iterator-page-size" value="50"/> - <property name="acl-bloomfilter-false-positive-probability" value="0.1d"/> - <property name="acl-bloomfilter-elements-number" value="1000000"/> - </properties></programlisting> - <para> - <literal>source-name</literal>: The JDBC data source name which is registered in JDNI by InitialContextInitializer. This was known as <literal>sourceName</literal> in versions prior to 1.9. - </para> - <para> - <literal>dialect</literal>: The database dialect. Must be one of the following: <literal>hsqldb</literal>, <literal>mysql</literal>, <literal>mysql-utf8</literal>, <literal>pgsql</literal>, <literal>oracle</literal>, <literal>oracle-oci</literal>, <literal>mssql</literal>, <literal>sybase</literal>, <literal>derby</literal>, <literal>db2</literal> or <literal>db2v8</literal>). - </para> - <para> - <literal>multi-db</literal>: This parameter, if <literal>true</literal>, enables multi-database container. - </para> - <para> - <literal>max-buffer-size</literal>: A threshold in bytes. If a value size is greater than this setting, then it will be spooled to a temporary file. - </para> - <para> - <literal>swap-directory</literal>: A location where the value will be spooled if no value storage is configured but a <literal>max-buffer-size</literal> is exceeded. - </para> - <para> - <literal>lazy-node-iterator-page-size</literal>: "Lazy" child nodes iterator settings. Defines size of page, the number of nodes that are retrieved from persistent storage at once. - </para> - <para> - <literal>acl-bloomfilter-false-positive-probability</literal>: ACL Bloom-filter settings. ACL Bloom-filter desired false positive probability. Range [0..1]. Default value 0.1d. - </para> - <para> - <literal>acl-bloomfilter-elements-number</literal>: ACL Bloom-filter settings. Expected number of ACL-elements in the Bloom-filter. Default value 1000000. - </para> - </example> - <note> - <para> - Bloom filters are not supported by all the cache implementations so far only the inplementation for infinispan supports it. - </para> - <para> - Bloom-filter used to avoid read nodes that definitely do not have ACL. <emphasis role="bold">acl-bloomfilter-false-positive-probability</emphasis> and <emphasis role="bold">acl-bloomfilter-elements-number</emphasis> used to configure such filters. Bloom filters are not supported by all the cache implementations so far only the inplementation for infinispan supports it. - </para> - <para> - More about Bloom filters you can read here <ulink url="http://en.wikipedia.org/wiki/Bloom_filter">http://en.wikipedia.org/wiki/Bloom_filter</ulink>. - </para> - </note> - <para> - The eXo JCR has a JDBC-based, relational database, production ready <emphasis role="bold">Workspace Data Container</emphasis>. - </para> - <para> - Workspace Data Container <emphasis>may</emphasis> support external storages for <literal>javax.jcr.Value</literal> (which can be the case for BLOB values for example) using the optional element <literal>value-storages</literal>. - </para> - <para> - The Data Container will try to read or write a Value using the underlying value storage plug-in if the filter criteria (see below) match the current property. - </para> - <example> - <title>External Value Storage Configuration</title> - <programlisting language="XML" role="XML"><value-storages> - <value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> - <properties> - <property name="path" value="data/values"/> - </properties> - <filters> - <filter property-type="Binary" min-value-size="1M"/> - </filters> -......... -</value-storages></programlisting> - <para> - <literal>value-storage</literal> is the subclass of <literal>org.exoplatform.services.jcr.storage.value.ValueStoragePlugin</literal> and <literal>properties</literal> are optional plug-in specific parameters. - </para> - <para> - <literal>filters</literal>: Each file value storage can have the filter(s) for incoming values. If there are several filter criteria, they all have to match (AND-Condition). - </para> - </example> - <para> - A filter can match values by property type (property-type), property name (property-name), ancestor path (ancestor-path) and/or the size of values stored (min-value-size, e.g. 1M, 4.2G, 100 (bytes)). - </para> - <para> - In a code sample, we use a filter with property-type and min-value-size only. That means that the storage is only for binary values whose size is greater than 1Mbyte. - </para> - <para> - It is recommended that you store properties with large values in a file value storage only. - </para> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-Cluster_Configuration"> - <title>Configuring Cluster</title> - <section id="sect-Reference_Guide-Cluster_Configuration-Launching_Cluster"> - <title>Launching Cluster</title> - <section id="sect-Reference_Guide-Launching_Cluster-Configuring_JCR_to_use_external_configuration"> - <title>Configuring JCR to use external configuration</title> - <itemizedlist> - <listitem> - <para> - To manually configure a repository, create a new configuration file (<filename>exo-jcr-configuration.xml</filename> for example). For details, see <xref linkend="chap-Reference_Guide-JCR_configuration"/>. - </para> - <para> - The configuration file must be formatted as follows: - </para> - <example> - <title>External Configuration</title> - <programlisting language="XML" role="XML"><repository-service default-repository="repository1"> - <repositories> - <repository name="repository1" system-workspace="ws1" default-workspace="ws1"> - <security-domain>exo-domain</security-domain> - <access-control>optional</access-control> - <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy> - <workspaces> - <workspace name="ws1"> - <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"> - <properties> - <property name="source-name" value="jdbcjcr" /> - <property name="dialect" value="oracle" /> - <property name="multi-db" value="false" /> - <property name="update-storage" value="false" /> - <property name="max-buffer-size" value="200k" /> - <property name="swap-directory" value="../temp/swap/production" /> - </properties> - <value-storages> - <![CDATA[]]> - </value-storages> - </container> - <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"> - <properties> - <property name="root-nodetype" value="nt:unstructured" /> - </properties> - </initializer> - <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"> - <![CDATA[]]> - </cache> - <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - <![CDATA[]]> - </query-handler> - <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"> - <![CDATA[]]> - </lock-manager> - </workspace> - <workspace name="ws2"> - ... - </workspace> - <workspace name="wsN"> - ... - </workspace> - </workspaces> - </repository> - </repositories> -</repository-service></programlisting> - <para> - Comment #1: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Value_Storage_configuration"/>. - </para> - <para> - Comment #2: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Cache_configuration"/>. - </para> - <para> - Comment #3: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Indexer_configuration"/>. - </para> - <para> - Comment #4: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Lock_Manager_configuration"/>. - </para> - </example> - </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"><component> - <key>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</key> - <type>org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl</type> - <init-params> - <value-param> - <name>conf-path</name> - <description>JCR configuration file</description> - <value>exo-jcr-configuration.xml</value> - </value-param> - </init-params> -</component></programlisting> - </listitem> - </itemizedlist> - </section> - </section> - <section id="sect-Reference_Guide-Cluster_Configuration-Requirements"> - <title>Requirements</title> - <section id="sect-Reference_Guide-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-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> - </itemizedlist> - </section> - <section id="sect-Reference_Guide-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-Configuration_requirements-Value_Storage_configuration"> - <title>Value Storage configuration</title> - <programlisting language="XML" role="XML"><value-storages> - <value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> - <properties> - <property name="path" value="/mnt/tornado/temp/values/production" />  - </properties> - <filters> - <filter property-type="Binary" /> - </filters> - </value-storage> -</value-storages></programlisting> - </example> - <example id="exam-Reference_Guide-Configuration_requirements-Cache_configuration"> - <title>Cache configuration</title> - <programlisting language="XML" role="XML"><cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"> - <properties> - <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-data.xml" />  - <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />  - <property name="jbosscache-cluster-name" value="JCR_Cluster_cache_production" />  - <property name="jgroups-multiplexer-stack" value="true" /> - </properties> -</cache></programlisting> - </example> - <example id="exam-Reference_Guide-Configuration_requirements-Indexer_configuration"> - <title>Indexer configuration</title> - <programlisting language="XML" role="XML"><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - <properties> - <property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /> - <property name="index-dir" value="/mnt/tornado/temp/jcrlucenedb/production" />  - <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-indexer.xml" />  - <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />  - <property name="jbosscache-cluster-name" value="JCR_Cluster_indexer_production" />  - <property name="jgroups-multiplexer-stack" value="true" /> - </properties> -</query-handler></programlisting> - </example> - <example id="exam-Reference_Guide-Configuration_requirements-Lock_Manager_configuration"> - <title>Lock Manager configuration</title> - <programlisting language="XML" role="XML"><lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"> - <properties> - <property name="time-out" value="15m" /> - <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-lock.xml" />  - <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />  - <property name="jgroups-multiplexer-stack" value="true" /> - <property name="jbosscache-cluster-name" value="JCR_Cluster_lock_production" />  - - <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_production"/>  - <property name="jbosscache-cl-cache.jdbc.table.create" value="true"/> - <property name="jbosscache-cl-cache.jdbc.table.drop" value="false"/> - <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_production_pk"/> - <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn"/> - <property name="jbosscache-cl-cache.jdbc.node.column" value="node"/> - <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent"/> - <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr"/> - </properties> -</lock-manager></programlisting> - </example> - </section> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-JBoss_Cache_configuration"> - <title>Configuring JBoss Cache</title> - <section id="sect-Reference_Guide-JBoss_Cache_configuration-Indexer_lock_manager_and_data_container_configuration"> - <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"><property name="jbosscache-configuration" value="conf/standalone - /test-jbosscache-lock-db1-ws1.xml" /></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-<parameter name>} 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">... -<clustering mode="replication" clusterName="${jbosscache-cluster-name}"> - <stateRetrieval timeout="20000" fetchInMemoryState="false" /> -...</programlisting> - <para> - and JCR configuration file: - </para> - <programlisting language="XML" role="XML">... -<property name="jbosscache-configuration" value="jar:/conf/portal/jbosscache-lock.xml" /> -<property name="jbosscache-cluster-name" value="JCR-cluster-locks-db1-ws" /> -...</programlisting> - </section> - <section id="sect-Reference_Guide-JBoss_Cache_configuration-JGroups_configuration"> - <title>JGroups configuration</title> - <para> - JGroups is used by JBoss Cache for network communications and transport in 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"><property name="jgroups-configuration" value="your/path/to/modified-udp.xml" /></programlisting> - <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"><property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> -<property name="jgroups-multiplexer-stack" value="true" /></programlisting> - </section> - <section id="sect-Reference_Guide-JBoss_Cache_configuration-Sharing_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"><property name="jbosscache-shareable" value="true" /></programlisting> - <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><PARAM_NAME></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-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 <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/jbosscache</filename> directory, inside either the <filename>cluster</filename> or <filename>local</filename> directory. - </para> - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Data_container_template"> - <title>Data container template</title> - <para> - The data container template is <filename>config.xml</filename>: - </para> - <programlisting language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?> -<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"> - - <locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" - lockAcquisitionTimeout="20000" /> - - <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> - <stateRetrieval timeout="20000" fetchInMemoryState="false" /> - <jgroupsConfig multiplexerStack="jcr.stack" /> - <sync /> - </clustering> - -  - <eviction wakeUpInterval="5000"> - <default algorithmClass="org.jboss.cache.eviction.LRUAlgorithm" - actionPolicyClass="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.ParentNodeEvictionActionPolicy" - eventQueueSize="1000000"> - <property name="maxNodes" value="1000000" /> - <property name="timeToLive" value="120000" /> - </default> - </eviction> -</jbosscache></programlisting> - </section> - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template"> - <title>Lock manager template</title> - <para> - The lock manager template is <filename>lock-config.xml</filename>: - </para> - <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../extras/Advanced_Development_JCR_lock-manager-config/lock-config.xml_code"/></programlisting> - </section> - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Query_handler_indexer_template"> - <title>Query handler (indexer) template</title> - <para> - The query handler template is called <filename>indexer-config.xml</filename>: - </para> - <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../extras/Advanced_Development_JCR_cluster-config/indexer-config.xml_code"/></programlisting> - </section> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-LockManager"> - <title>LockManager</title> - <para> - The LockManager stores lock objects. It can lock or release objects as required. It is also responsible for removing stale locks. - </para> - <para> - The LockManager in JBoss Portal Platform is implemented with <classname>org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl</classname>. - </para> - <para> - It is enabled by adding <literal>lock-manager-configuration</literal> to <literal>workspace-configuration</literal>. - </para> - <para> - For example: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../extras/default47.xml" parse="text"/></programlisting> - <section id="sect-Reference_Guide-LockManager-CacheableLockManagerImpl"> - <title>CacheableLockManagerImpl</title> - <para> - <classname>CacheableLockManagerImpl</classname> stores lock objects in JBoss-cache (which implements JDBCCacheLoader to store locks in a database). This means its locks are replicable and can affect an entire cluster rather than just a single node. - </para> - <para> - The length of time LockManager allows a lock to remain in place can be configured with the "<literal>time-out</literal>" property. - </para> - <para> - The LockRemover thread periodically polls LockManager for locks that have passed the time-out limit and must be removed. - </para> - <para> - The time-out for LockRemover is set as follows (the default value is 30m): - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default48.xml" parse="text"/></programlisting> - <para> - There are a number of ways to configure <classname>CacheableLockManagerImpl</classname>. Each involves configuring JBoss Cache and JDBCCacheLoader. - </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"/> - </para> - </listitem> - </itemizedlist> - <para> - Refer to <ulink url="http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader">http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader</ulink> for more information about JBoss Cache and JDBCCacheLoader. - </para> - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration"> - <title>Simple JBoss Cache Configuration</title> - <para> - One method to configure the LockManager is to put a JBoss Cache configuration file path into <classname>CacheableLockManagerImpl</classname>. - </para> - <note> - <para> - This is not the most efficient method for configuring the LockManager as it requires a JBoss Cache configuration file for each LockManager configuration in each workspace of each repository. The configuration set up can subsequently become quite difficult to manage. - </para> - <para> - This method is useful, however, if a single, specially configured LockManager is required. - </para> - </note> - <para> - The required configuration is shown in the example below: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default49.xml" parse="text"/></programlisting> - <para> - Sample content of the <replaceable>jbosscache-lock-config.xml</replaceable> file specified in the <replaceable>jbosscache-configuration</replaceable> property is shown in the code example below. - </para> - <example> - <title>Sample Content of the jbosscache-lock-config.xml File</title> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default50.xml" parse="text"/></programlisting> - <para> - Comment #1: The cluster name at <parameter>clustering mode="replication" clusterName="JBoss-Cache-Lock-Cluster_Name"</parameter> must be unique; - </para> - <para> - Comment #2: The <parameter>cache.jdbc.table.name</parameter> must be unique per datasource. - </para> - <para> - Comment #3: The <parameter>cache.jdbc.node.type</parameter> and <parameter>cache.jdbc.fqn.type</parameter> parameters must be configured according to the database in use. Refer to the table below for information about data types. - </para> - </example> - <table id="tabl-Reference_Guide-Simple_JBoss_Cache_Configuration-Data_Types_in_Different_Databases"> - <title>Data Types in Different Databases</title> - <tgroup cols="3"> - <thead> - <row> - <entry> DataBase name </entry> - <entry> Node data type </entry> - <entry> FQN data type </entry> - </row> - </thead> - <tbody> - <row> - <entry> default </entry> - <entry> BLOB </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> HSSQL </entry> - <entry> OBJECT </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> MySQL </entry> - <entry> LONGBLOB </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> ORACLE </entry> - <entry> BLOB </entry> - <entry> VARCHAR2(512) </entry> - </row> - <row> - <entry> PostgreSQL </entry> - <entry> bytea </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> MSSQL </entry> - <entry> VARBINARY(MAX) </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> DB2 </entry> - <entry> BLOB </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> Sybase </entry> - <entry> IMAGE </entry> - <entry> VARCHAR(512) </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"> - <title>Template JBoss Cache Configuration</title> - <para> - Another method to configure LockManager is to use a JBoss Cache configuration template for all LockManagers. - </para> - <para> - Below is an example <filename>test-jbosscache-lock.xml</filename> template file: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/you.xml" parse="text"/></programlisting> - <para> - The parameters that will populate the above file are shown below: - </para> - <example> - <title>JBoss Cache Configuration Parameters</title> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default51.xml" parse="text"/></programlisting> - <para> - Comment #1: The <literal>jgroups-configuration</literal> has been moved to a separate configuration file (<filename>udp-mux.xml</filename>, shown below). In this case the <filename>udp-mux.xml</filename> is a common configuration for all JGroup components (QueryHandler, cache, LockManager), but this is not a requirement of the configuration method. - </para> - <para> - Comment #2: The <parameter>jbosscache-cl-cache.jdbc.fqn.column</parameter> and <parameter>jbosscache-cl-cache.jdbc.node.type</parameter> parameters are not explicitly defined as <parameter>cache.jdbc.fqn.type</parameter> and <parameter>cache.jdbc.node.type</parameter> are defined in the JBoss Cache configuration. - </para> - </example> - <para> - Refer to <xref linkend="tabl-Reference_Guide-Simple_JBoss_Cache_Configuration-Data_Types_in_Different_Databases"/> for information about setting these parameters or set them as <parameter>AUTO</parameter> and the data type will by detected automatically. - </para> - <para> - <filename>udp-mux.xml</filename>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default52.xml" parse="text"/></programlisting> - </section> - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Lock_migration_from_1.12.x"> - <title>Lock Migration</title> - <para> - There are three options available: - </para> - <variablelist id="vari-Reference_Guide-Lock_migration_from_1.12.x-Lock_Migration_Options"> - <title>Lock Migration Options</title> - <varlistentry> - <term>When new Shareable Cache feature is not going to be used and all locks should be kept after migration.</term> - <listitem> - <procedure> - <title/> - <step> - <para> - Ensure that the same lock tables are used in configuration - </para> - </step> - <step> - <para> - Start the server - </para> - </step> - </procedure> - </listitem> - </varlistentry> - <varlistentry> - <term>When new Shareable Cache feature is not going to be used and all locks should be removed after migration.</term> - <listitem> - <procedure> - <title/> - <step> - <para> - Ensure that the same lock tables used in configuration - </para> - </step> - <step> - <para> - Start the sever WITH system property: - </para> - <programlisting>-Dorg.exoplatform.jcr.locks.force.remove=true -</programlisting> - </step> - <step> - <para> - Stop the server - </para> - </step> - <step> - <para> - Start the server WITHOUT system property: - </para> - <programlisting>-Dorg.exoplatform.jcr.locks.force.remove -</programlisting> - </step> - </procedure> - </listitem> - </varlistentry> - <varlistentry> - <term>When new Shareable Cache feature will be used (in this case all locks are removed after migration).</term> - <listitem> - <procedure> - <title/> - <step> - <para> - Start the sever WITH system property: - </para> - <programlisting>-Dorg.exoplatform.jcr.locks.force.remove=true -</programlisting> - </step> - <step> - <para> - Stop the server. - </para> - </step> - <step> - <para> - Start the server WITHOUT system property: - </para> - <programlisting>-Dorg.exoplatform.jcr.locks.force.remove -</programlisting> - </step> - <step> - <title>Optional:</title> - <para> - Manually remove old tables for lock. - </para> - </step> - </procedure> - </listitem> - </varlistentry> - </variablelist> - </section> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-QueryHandler_configuration"> - <title>Configuring QueryHandler</title> - <section id="sect-Reference_Guide-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> - <figure> - <title id="diagramlocalindez">Local Index Diagram</title> - <mediaobject> - <imageobject> - <imagedata width="444" align="center" fileref="images/eXoJCR/diagram-local-index.png"/> - </imageobject> - </mediaobject> - </figure> - <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 scenarios. 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> - <figure> - <title id="diagramsharedindex">Shared Index Diagram</title> - <mediaobject> - <imageobject> - <imagedata width="444" align="center" fileref="images/eXoJCR/diagram-shared-index.png"/> - </imageobject> - </mediaobject> - </figure> - <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="chap-Reference_Guide-Search_Configuration"/> . - </para> - </section> - <section id="sect-Reference_Guide-QueryHandler_configuration-Configuration"> - <title>Configuration</title> - <section id="sect-Reference_Guide-Configuration-Query_handler_configuration_overview"> - <title>Query-handler configuration overview</title> - <para> - Configuration example: - </para> - <programlisting language="XML" role="XML"><workspace name="ws"> - <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - <properties> - <property name="index-dir" value="shareddir/index/db1/ws" /> - <property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /> - <property name="jbosscache-configuration" value="jbosscache-indexer.xml" /> - <property name="jgroups-configuration" value="udp-mux.xml" /> - <property name="jgroups-multiplexer-stack" value="true" /> - <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /> - <property name="max-volatile-time" value="60" /> - <property name="rdbms-reindexing" value="true" /> - <property name="reindexing-page-size" value="1000" /> - <property name="index-recovery-mode" value="from-coordinator" /> - <property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /> - </properties> - </query-handler> -</workspace> -</programlisting> - <table id="tabl-Reference_Guide-Query_handler_configuration_overview-Configuration_properties"> - <title>Configuration properties</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Property name </entry> - <entry> Description </entry> - </row> - </thead> - <tbody> - <row> - <entry> index-dir </entry> - <entry> path to index </entry> - </row> - <row> - <entry> 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> jgroups-configuration </entry> - <entry> jgroups-configuration is template configuration for all components (search, cache, locks) [Add link to document describing template configurations] </entry> - </row> - <row> - <entry> jgroups-multiplexer-stack </entry> - <entry> [TODO about jgroups-multiplexer-stack - add link to JBoss doc] </entry> - </row> - <row> - <entry> jbosscache-cluster-name </entry> - <entry> cluster name (must be unique) </entry> - </row> - <row> - <entry> max-volatile-time </entry> - <entry> max time to live for Volatile Index </entry> - </row> - <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> 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-filter </entry> - <entry> Defines implementation class or classes of RecoveryFilters, the mechanism of index synchronization for Local Index strategy. </entry> - </row> - <row> - <entry> async-reindexing </entry> - <entry> Controls the process of re-indexing on JCR's startup. If this flag is set, indexing will be launched asynchronously, without blocking the JCR. Default is "<literal>false</literal>". </entry> - </row> - </tbody> - </tgroup> - </table> - <formalpara id="form-Reference_Guide-Query_handler_configuration_overview-Improving_Query_Performance_With_postgreSQL_and_rdbms_reindexing"> - <title>Improving Query Performance With <literal>postgreSQL</literal> and <parameter>rdbms-reindexing</parameter></title> - <para> - If you use <literal>postgreSQL</literal> and <parameter>rdbms-reindexing</parameter> is set to <literal>true</literal>, the performance of the queries used while indexing can be improved by: - </para> - </formalpara> - <procedure> - <title/> - <step> - <para> - Set the parameter "<parameter>enable_seqscan</parameter>" to "<literal>off</literal>" - </para> - <para> - <emphasis role="bold">OR</emphasis> - </para> - <para> - Set "<parameter>default_statistics_target</parameter>" to at least "<literal>50</literal>". - </para> - </step> - <step> - <para> - Restart DB server and make analyze of the JCR_SVALUE (or JCR_MVALUE) table. - </para> - </step> - </procedure> - <formalpara id="form-Reference_Guide-Query_handler_configuration_overview-Improving_Query_Performance_With_DB2_and_rdbms_reindexing"> - <title>Improving Query Performance With <literal>DB2</literal> and <parameter>rdbms-reindexing</parameter></title> - <para> - If you use <literal>DB2</literal> and <parameter>rdbms-reindexing</parameter> is set to <literal>true</literal>, the performance of the queries used while indexing can be improved by: - </para> - </formalpara> - <procedure> - <title/> - <step> - <para> - Make statistics on tables by running the following for <literal>JCR_SITEM</literal> (or <literal>JCR_MITEM</literal>) and <literal>JCR_SVALUE</literal> (or <literal>JCR_MVALUE</literal>) tables: - </para> - <programlisting><code>RUNSTATS ON TABLE <scheme>.<table> WITH DISTRIBUTION AND INDEXES ALL</code></programlisting> - </step> - </procedure> - </section> - <section id="sect-Reference_Guide-Configuration-Cluster_ready_indexing"> - <title>Cluster-ready indexing</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"><workspace name="ws"> - <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - <properties> - <property name="index-dir" value="/mnt/nfs_drive/index/db1/ws" /> - <property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /> - <property name="jbosscache-configuration" value="jbosscache-indexer.xml" /> - <property name="jgroups-configuration" value="udp-mux.xml" /> - <property name="jgroups-multiplexer-stack" value="true" /> - <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /> - <property name="max-volatile-time" value="60" /> - <property name="rdbms-reindexing" value="true" /> - <property name="reindexing-page-size" value="1000" /> - <property name="index-recovery-mode" value="from-coordinator" /> - </properties> - </query-handler> -</workspace></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> - <programlisting language="XML" role="XML"><workspace name="ws"> - <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - <properties> - <property name="index-dir" value="/mnt/nfs_drive/index/db1/ws" /> - <property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter" /> - <property name="jbosscache-configuration" value="jbosscache-indexer.xml" /> - <property name="jgroups-configuration" value="udp-mux.xml" /> - <property name="jgroups-multiplexer-stack" value="true" /> - <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /> - <property name="max-volatile-time" value="60" /> - <property name="rdbms-reindexing" value="true" /> - <property name="reindexing-page-size" value="1000" /> - <property name="index-recovery-mode" value="from-coordinator" /> - </properties> - </query-handler> -</workspace> -</programlisting> - </section> - <section id="sect-Reference_Guide-Configuration-Local_Index_Recovery_Filters"> - <title>Local Index Recovery Filters</title> - <para> - A common usecase for all cluster-ready applications is a hot joining and leaving of processing units. All nodes that are joining a cluster for the first time or nodes joining after some downtime, must be in a synchronized state. - </para> - <para> - When using shared value storages, databases and indexes, cluster nodes are synchronized at any given time. But is not the case when a local index strategy is used. - </para> - <para> - If a new node joins a cluster, without an index it is retrieved or recreated. Nodes can be also be restarted and thus the index is not empty. By default, even though the existing index is thought to be up to date, it can be outdated. - </para> - <para> - The JBoss Portal Platform JCR offers a mechanism called <literal>RecoveryFilters</literal> that will automatically retrieve index for the joining node on start up. This feature is a set of filters that can be defined via <literal>QueryHandler</literal> configuration: - </para> - <programlisting language="XML"><property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /></programlisting> - <para> - Filter numbers are not limited so they can be combined: - </para> - <programlisting language="XML"><property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /> - <property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.SystemPropertyRecoveryFilter" /> -</programlisting> - <para> - If any one returns fires, the index is re-synchronized. This feature uses standard index recovery mode defined by previously described parameter (can be "from-indexing" (default) or "from-coordinator") - </para> - <programlisting language="XML"><property name="index-recovery-mode" value="from-coordinator" /> -</programlisting> - <para> - There are multiple filter implementations: - </para> - <variablelist id="vari-Reference_Guide-Local_Index_Recovery_Filters-org.exoplatform.services.jcr.impl.core.query.lucene.DummyRecoveryFilter"> - <title>org.exoplatform.services.jcr.impl.core.query.lucene.DummyRecoveryFilter</title> - <varlistentry> - <term/> - <listitem> - <para> - Always returns true, for cases when index must be force resynchronized (recovered) each time. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.exoplatform.services.jcr.impl.core.query.lucene.SystemPropertyRecoveryFilter</term> - <listitem> - <para> - Returns value of system property "<literal>org.exoplatform.jcr.recoveryfilter.forcereindexing</literal>". So index recovery can be controlled from the top without changing documentation using system properties. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.exoplatform.services.jcr.impl.core.query.lucene.ConfigurationPropertyRecoveryFilter</term> - <listitem> - <para> - Returns value of <literal>QueryHandler</literal> configuration property "<literal>index-recovery-filter-forcereindexing</literal>". So index recovery can be controlled from configuration separately for each workspace. For example: - </para> - <programlisting language="XML"><property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.ConfigurationPropertyRecoveryFilter" /> - <property name="index-recovery-filter-forcereindexing" value="true" /> -</programlisting> - </listitem> - </varlistentry> - <varlistentry> - <term>org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter</term> - <listitem> - <para> - Checks the number of documents in index on coordinator side and self-side. It returns <literal>true</literal> if the count differs. - </para> - <para> - The advantage of this filter compared to others, is that it will skip reindexing for workspaces where the index was not modified. - </para> - <para> - For example; if there is ten repositories with three workspaces in each and only one is heavily used in the cluster, this filter will only reindex those workspaces that have been changed, without affecting other indexes. - </para> - <para> - This greatly reduces start up time. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sect-Reference_Guide-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 id="exam-Reference_Guide-JBoss_Cache_template_configuration-jbosscache_indexer.xml"> - <title>jbosscache-indexer.xml</title> - <programlisting language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?> -<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"> - <locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" - lockAcquisitionTimeout="20000" /> -  - <transaction transactionManagerLookupClass="org.jboss.cache.transaction.JBossStandalone - JTAManagerLookup" /> - <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> - <stateRetrieval timeout="20000" fetchInMemoryState="false" /> - <jgroupsConfig multiplexerStack="jcr.stack" /> - <sync /> - </clustering> -  - <eviction wakeUpInterval="5000"> - <default algorithmClass="org.jboss.cache.eviction.FIFOAlgorithm" eventQueueSize="1000000"> - <property name="maxNodes" value="10000" /> - <property name="minTimeToLive" value="60000" /> - </default> - </eviction> -</jbosscache></programlisting> - </example> - <para> - Read more about template configurations <xref linkend="chap-Reference_Guide-JBoss_Cache_configuration"/>. - </para> - </section> - </section> - <section id="sect-Reference_Guide-QueryHandler_configuration-Asynchronous_Reindexing"> - <title>Asynchronous Re-indexing</title> - <para> - Managing a large data set using a JCR in a production environment at times requires special operations with Indexes, stored on File System. One of those maintenance operations is a recreation of it. Also called "re-indexing". There are various usecases when it's important to do. They include hardware faults, hard restarts, data-corruption, migrations and JCR updates that brings new features related to index. Usually index re-creation requested on server's startup or in runtime. - </para> - <section id="sect-Reference_Guide-Asynchronous_Reindexing-On_startup_indexing"> - <title>On startup indexing</title> - <para> - A common usecase for updating and re-creating the index is to stop the server and manually remove indexes for workspaces requiring it. When the server is re-started, the missing indexes are automatically recovered by re-indexing. - </para> - <para> - The eXo JCR Supports direct RDBMS re-indexing, which can be faster than ordinary and can be configured via <literal>QueryHandler</literal> parameter <parameter>rdbms-reindexing</parameter> set to <literal>true</literal>. - </para> - <para> - A new feature is asynchronous indexing on startup. Usually startup is blocked until the indexing process is finished. This block can take any period of time, depending on amount of data persisted in repositories. But this can be resolved by using an asynchronous approaches of startup indexation. - </para> - <para> - Essentially, all indexing operations are performed in the background without blocking the repository. This is controlled by the value of the <parameter>async-reindexing</parameter> parameter in <literal>QueryHandler</literal> configuration. - </para> - <para> - With asynchronous indexation active, the JCR starts with no active indexes present. Queries on JCR still can be executed without exceptions, but no results will be returned until index creation completed. - </para> - <para> - The index state check is accomplished via <literal>QueryManagerImpl</literal>: - </para> - <para> - -<programlisting lang="java">boolean online = ((QueryManagerImpl)Workspace.getQueryManager()).getQueryHandeler().isOnline();</programlisting> - - </para> - <para> - The <emphasis role="bold">OFFLINE</emphasis> state means that the index is currently re-creating. When the state is changed, a corresponding log event is printed. When the background index task starts the index is switched to <emphasis role="bold">OFFLINE</emphasis>, with following log event : - </para> - <programlisting>[INFO] Setting index OFFLINE (repository/production[system]).</programlisting> - <para> - When the indexing process is finished, the following two events are logged : - </para> - <programlisting>[INFO] Created initial index for 143018 nodes (repository/production[system]). -[INFO] Setting index ONLINE (repository/production[system]).</programlisting> - <para> - Those two log lines indicates the end of process for workspace given in brackets. Calling isOnline() as mentioned above, will also return true. - </para> - </section> - <section id="sect-Reference_Guide-Asynchronous_Reindexing-Hot_Asynchronous_Workspace_Reindexing_via_JMX"> - <title>Hot Asynchronous Workspace Re-indexing using JMX</title> - <para> - Some hard system faults, errors during upgrades, migration issues and some other factors may corrupt the index. Current versions of JCR supports <emphasis role="bold">Hot Asynchronous Workspace Reindexing</emphasis> feature. It allows Service Administrators to launch the process in background without stopping or blocking the whole application by using any JMX-compatible console. - </para> - <figure> - <title id="jmx-jconsole">JMX Jconsole</title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/eXoJCR/jmx-jconsole.png"/> - </imageobject> - </mediaobject> - </figure> - <para> - The server can continue working as expected while the index is recreated. - </para> - <para> - This depends on the flag <parameter>allow queries</parameter> being passed via JMX interface to the reindex operation invocation. If the flag is set, the application continues working. - </para> - <para> - However, there is one critical limitation users must be aware of; <emphasis>the index is frozen while the background task is running</emphasis>. - </para> - <para> - This means that queries are performed on a version of the index present at the moment the indexing task is started, and that data written into the repository after startup will not be available through the search until process completes. - </para> - <para> - Data added during re-indexation is also indexed, but will be available only when reindexing is complete. The JCR makes a snapshot of indexes at the invocation of the asynchronous indexing task and uses that snapshot for searches. - </para> - <para> - When the operation is finished, the stale index is replaced by the newly created index, which included any newly added data. - </para> - <para> - If the <parameter>allow queries</parameter> flag is set to <literal>false</literal>, then all queries will throw an exception while task is running. The current state can be acquired using the following JMX operation: - </para> - <itemizedlist> - <listitem> - <para> - getHotReindexingState() - returns information about latest invocation: start time, if in progress or finish time if done. - </para> - </listitem> - </itemizedlist> - </section> - <section id="sect-Reference_Guide-Asynchronous_Reindexing-Notices"> - <title>Notices</title> - <para> - Hot re-indexing via JMX cannot be launched if the index is already in offline mode. This means that the index is currently involved in some other operations, such as re-indexing at startup, copying in cluster to another node or whatever. - </para> - <para> - Also; <emphasis>Hot Asynchronous Reindexing via JMX</emphasis> and <literal>on startup</literal> reindexing are different features. So you can't get the state of startup reindexing using command <code>getHotReindexingState</code> in JMX interface, but there are some common JMX operations: - </para> - <itemizedlist> - <listitem> - <para> - getIOMode - returns current index IO mode (READ_ONLY / READ_WRITE), belongs to clustered configuration states; - </para> - </listitem> - <listitem> - <para> - getState - returns current state: ONLINE / OFFLINE. - </para> - </listitem> - </itemizedlist> - </section> - </section> - <section id="sect-Reference_Guide-QueryHandler_configuration-Advanced_tuning"> - <title>Advanced tuning</title> - <section id="sect-Reference_Guide-Advanced_tuning-Lucene_tuning"> - <title>Lucene tuning</title> - <para> - As mentioned, JCR Indexing is based on the Lucene indexing library as the underlying search engine. It uses Directories to store index and manages access to index by Lock Factories. - </para> - <para> - By default, the JCR implementation uses optimal combination of Directory implementation and Lock Factory implementation. - </para> - <para> - The <literal>SimpleFSDirectory</literal> is used in Windows environments and the <literal>NIOFSDirectory</literal> implementation is used in non-Windows systems. - </para> - <para> - <literal>NativeFSLockFactory</literal> is an optimal solution for a wide variety of cases including clustered environment with NFS shared resources. - </para> - <para> - But those defaults can be overridden in the system properties. - </para> - <para> - Two properties: <literal>org.exoplatform.jcr.lucene.store.FSDirectoryLockFactoryClass</literal> and <literal>org.exoplatform.jcr.lucene.FSDirectory.class</literal> control (and change) the default behavior. - </para> - <para> - The first defines the implementation of abstract Lucene <literal>LockFactory</literal> class and the second sets implementation class for <literal>FSDirectory</literal> instances. - </para> - <para> - For more information, refer to the Lucene documentation. But be careful, for while the JCR allows users to change implementation classes of Lucene internals, it does not guarantee the stability and functionality of those changes. - </para> - </section> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-JBossTransactionsService"> - <title>JBossTransactionsService</title> - <section id="sect-Reference_Guide-JBossTransactionsService-Introduction"> - <title>Introduction</title> - <para> - JBossTransactionsService implements eXo TransactionService and provides access to <ulink url="http://www.jboss.org/jbosstm/">JBoss Transaction Service (JBossTS)</ulink> JTA implementation via eXo container dependency. - </para> - <para> - TransactionService used in JCR cache <emphasis>org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache</emphasis> implementation. - </para> - </section> - <section id="sect-Reference_Guide-JBossTransactionsService-Configuration"> - <title>Configuration</title> - <para> - Example configuration: - </para> - <programlisting language="XML" role="XML"> <component> - <key>org.exoplatform.services.transaction.TransactionService</key> - <type>org.exoplatform.services.transaction.jbosscache.JBossTransactionsService</type> - <init-params> - <value-param> - <name>timeout</name> - <value>3000</value> - </value-param> - </init-params> - </component></programlisting> - <para> - timeout - XA transaction timeout in seconds - </para> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-JCR_Query_Usecases"> - <title>JCR Query Use-cases</title> - <section id="sect-Reference_Guide-JCR_Query_Usecases-Introduction"> - <title>Introduction</title> - <para> - The JCR supports two query languages; JCR and XPath. A query, whether XPath or SQL, specifies a subset of nodes within a workspace, called the result set. The result set constitutes all the nodes in the workspace that meet the constraints stated in the query. - </para> - </section> - <section id="sect-Reference_Guide-JCR_Query_Usecases-Query_Lifecycle"> - <title>Query Lifecycle</title> - <section id="sect-Reference_Guide-Query_Lifecycle-Query_Creation_and_Execution"> - <title>Query Creation and Execution</title> - <example id="exam-Reference_Guide-Query_Lifecycle-Query_Creation_and_Execution-SQL"> - <title>SQL</title> - <programlisting language="Java" role="Java">// get QueryManager -QueryManager queryManager = workspace.getQueryManager();  -// make SQL query -Query query = queryManager.createQuery("SELECT * FROM nt:base ", Query.SQL); -// execute query -QueryResult result = query.execute();</programlisting> - </example> - <example id="exam-Reference_Guide-Query_Lifecycle-Query_Creation_and_Execution-XPath"> - <title>XPath</title> - <programlisting language="Java" role="Java">// get QueryManager -QueryManager queryManager = workspace.getQueryManager(); -// make XPath query -Query query = queryManager.createQuery("//element(*,nt:base)", Query.XPATH); -// execute query -QueryResult result = query.execute();</programlisting> - </example> - </section> - <section id="sect-Reference_Guide-Query_Lifecycle-Query_Result_Processing"> - <title>Query Result Processing</title> - <programlisting language="Java" role="Java">// fetch query result -QueryResult result = query.execute();</programlisting> - <para> - To fetch the nodes: - </para> - <programlisting language="Java" role="Java">NodeIterator it = result.getNodes();</programlisting> - <para> - The results can be formatted in a table: - </para> - <programlisting language="Java" role="Java">// get column names -String[] columnNames = result.getColumnNames(); -// get column rows -RowIterator rowIterator = result.getRows(); -while(rowIterator.hasNext()){ - // get next row - Row row = rowIterator.nextRow(); - // get all values of row - Value[] values = row.getValues(); -}</programlisting> - </section> - <section id="sect-Reference_Guide-Query_Lifecycle-Scoring"> - <title>Scoring</title> - <para> - The result returns a score for each row in the result set. The score contains a value that indicates a rating of how well the result node matches the query. A high value means a better matching than a low value. This score can be used for ordering the result. - </para> - <para> - eXo JCR Scoring is a mapping of Lucene scoring. For a more in-depth understanding, please study <ulink url="http://lucene.apache.org/java/2_4_1/scoring.html">Lucene documentation</ulink>. - </para> - <para> - The <literal>jcr:score</literal> is calculated as; <literal>(lucene score)*1000f</literal>. - </para> - </section> - </section> - <section id="sect-Reference_Guide-JCR_Query_Usecases-Tips_and_tricks"> - <title>Tips and tricks</title> - <section xmlns="" id="sect-Reference_Guide-XPath_queries_containing_node_names_starting_with_a_number"> - <title>XPath queries containing node names starting with a number</title> - <para> - If you execute an XPath request like this... - </para> - <programlisting language="Java" role="Java">// get QueryManager -QueryManager queryManager = workspace.getQueryManager(); -// make XPath query -Query query = queryManager.createQuery("/jcr:root/Documents/Publie/2010//element(*, exo:article)", Query.XPATH);</programlisting> - <para> - ...you will receive an <code>Invalid request</code> error. This is because XML (and thus XPath) does not allow names starting with a number. - </para> - <para> - Therefore, XPath requests using a node name that starts with a number are invalid. - </para> - <para> - Some possible alternatives are: - </para> - <itemizedlist> - <listitem> - <para> - Use an SQL request. - </para> - </listitem> - <listitem> - <para> - Use escaping: - </para> - <programlisting language="Java" role="Java">// get QueryManager -QueryManager queryManager = workspace.getQueryManager(); -// make XPath query -Query query = queryManager.createQuery("/jcr:root/Documents/Publie/_x0032_010//element(*, exo:article)", Query.XPATH);</programlisting> - </listitem> - </itemizedlist> - </section> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-Searching_Repository_Content"> - <title>Searching Repository Content</title> - <section id="sect-Reference_Guide-Searching_Repository_Content-Introduction"> - <title>Introduction</title> - <para> - You can find the JCR configuration file here: <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. - </para> - <para> - Please refer to <xref linkend="chap-Reference_Guide-Search_Configuration"/> for more information about index configuration. - </para> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-Bi_directional_RangeIterator"> - <title>Bi-directional RangeIterator</title> - <para> - <literal>QueryResult.getNodes()</literal> will return bi-directional <literal>NodeIterator</literal> implementation. - </para> - <note> - <para> - Bi-directional NodeIterator is <emphasis role="bold">not supported</emphasis> in two cases: - </para> - <orderedlist> - <listitem> - <para> - SQL query: select * from nt:base - </para> - </listitem> - <listitem> - <para> - XPath query: //* . - </para> - </listitem> - </orderedlist> - </note> - <para> - <literal>TwoWayRangeIterator</literal> interface: - </para> - <programlisting language="Java" role="Java">/** - * Skip a number of elements in the iterator. - * - * @param skipNum the non-negative number of elements to skip - * @throws java.util.NoSuchElementException if skipped past the first element - * in the iterator. - */ -public void skipBack(long skipNum);</programlisting> - <para> - Usage: - </para> - <programlisting language="Java" role="Java">NodeIterator iter = queryResult.getNodes(); -while (iter.hasNext()) { - if (skipForward) { - iter.skip(10); // Skip 10 nodes in forward direction - } else if (skipBack) { - TwoWayRangeIterator backIter = (TwoWayRangeIterator) iter; - backIter.skipBack(10); // Skip 10 nodes back - } - ....... -}</programlisting> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-Fuzzy_Searches"> - <title>Fuzzy Searches</title> - <para> - The JBoss Portal Platform JCR supports features such as Lucene Fuzzy Searches. To perform a fuzzy search, form your query like the one below: - </para> - <programlisting language="Java" role="Java">QueryManager qman = session.getWorkspace().getQueryManager(); -Query q = qman.createQuery("select * from nt:base where contains(field, 'ccccc~')", Query.SQL); -QueryResult res = q.execute();</programlisting> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-SynonymSearch"> - <title>SynonymSearch</title> - <para> - Searching with synonyms is integrated in the <literal>jcr:contains()</literal> function and uses the same syntax as synonym searches in web search engines (Google, for example). If a search term is prefixed by a tilde symbol ( ~ ), synonyms of the search term are taken into consideration. For example: - </para> - <programlisting>SQL: select * from nt:resource where contains(., '~parameter') - -XPath: //element(*, nt:resource)[jcr:contains(., '~parameter')</programlisting> - <para> - This feature is disabled by default and you need to add a configuration parameter to the query-handler element in your JCR configuration file to enable it. - </para> - <programlisting language="XML" role="XML"><param name="synonymprovider-config-path" value="..you path to configuration file....."/> -<param name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider"/></programlisting> - <programlisting language="XML" role="XML">/** - * <code>SynonymProvider</code> defines an interface for a component that - * returns synonyms for a given term. - */ -public interface SynonymProvider { - - /** - * Initializes the synonym provider and passes the file system resource to - * the synonym provider configuration defined by the configuration value of - * the <code>synonymProviderConfigPath</code> parameter. The resource may be - * <code>null</code> if the configuration parameter is not set. - * - * @param fsr the file system resource to the synonym provider - * configuration. - * @throws IOException if an error occurs while initializing the synonym - * provider. - */ - public void initialize(InputStream fsr) throws IOException; - - /** - * Returns an array of terms that are considered synonyms for the given - * <code>term</code>. - * - * @param term a search term. - * @return an array of synonyms for the given <code>term</code> or an empty - * array if no synonyms are known. - */ - public String[] getSynonyms(String term); -}</programlisting> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-Highlighting"> - <title>Highlighting</title> - <para> - An <literal>ExcerptProvider</literal> retrieves text excerpts for a node in the query result and marks up the words in the text that match the query terms. - </para> - <para> - By default, match highlighting is disabled because as it requires that additional information is written to the search index. - </para> - <para> - To enable this feature, you need to add a configuration parameter to the <parameter>query-handler</parameter> element in your JCR configuration file: - </para> - <programlisting language="XML" role="XML"><param name="support-highlighting" value="true"/></programlisting> - <para> - Additionally, there is a parameter that controls the format of the excerpt created. In JCR 1.9, the default is set to <literal>org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt</literal>. The configuration parameter for this setting is: - </para> - <programlisting language="XML" role="XML"><param name="excerptprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.DefaultXMLExcerpt"/></programlisting> - <section id="sect-Reference_Guide-Highlighting-DefaultXMLExcerpt"> - <title>DefaultXMLExcerpt</title> - <para> - This excerpt provider creates an XML fragment of the following form: - </para> - <programlisting language="XML" role="XML"><excerpt> - <fragment> - <highlight>exoplatform</highlight> implements both the mandatory - XPath and optional SQL <highlight>query</highlight> syntax. - </fragment> - <fragment> - Before parsing the XPath <highlight>query</highlight> in - <highlight>exoplatform</highlight>, the statement is surrounded - </fragment> -</excerpt></programlisting> - </section> - <section id="sect-Reference_Guide-Highlighting-DefaultHTMLExcerpt"> - <title>DefaultHTMLExcerpt</title> - <para> - This excerpt provider creates an HTML fragment of the following form: - </para> - <programlisting language="HTML" role="HTML"><div> - <span> - <strong>exoplatform</strong> implements both the mandatory XPath - and optional SQL <strong>query</strong> syntax. - </span> - <span> - Before parsing the XPath <strong>query</strong> in - <strong>exoplatform</strong>, the statement is surrounded - </span> -</div></programlisting> - </section> - <section id="sect-Reference_Guide-Highlighting-Usage"> - <title>Usage</title> - <para> - If you are using XPath, you must use the <code>rep:excerpt()</code> function in the last location step, just like you would select properties: - </para> - <programlisting language="Java" role="Java">QueryManager qm = session.getWorkspace().getQueryManager(); -Query q = qm.createQuery("//*[jcr:contains(., 'exoplatform')]/(@Title|rep:excerpt(.))", Query.XPATH); -QueryResult result = q.execute(); -for (RowIterator it = result.getRows(); it.hasNext(); ) { - Row r = it.nextRow(); - Value title = r.getValue("Title"); - Value excerpt = r.getValue("rep:excerpt(.)"); -}</programlisting> - <para> - The above code searches for nodes that contain the word <emphasis>exoplatform</emphasis> and then gets the value of the <parameter>Title</parameter> property and an excerpt for each resultant node. - </para> - <para> - It is also possible to use a relative path in the call <code>Row.getValue()</code> while the query statement still remains the same. Also, you may use a relative path to a string property. The returned value will then be an excerpt based on string value of the property. - </para> - <para> - Both available excerpt providers will create fragments of about 150 characters and up to three fragments. - </para> - <para> - In SQL, the function is called <code>excerpt()</code> without the rep prefix, but the column in the <literal>RowIterator</literal> will nonetheless be labelled <code>rep:excerpt(.)</code>. - </para> - <programlisting language="Java" role="Java">QueryManager qm = session.getWorkspace().getQueryManager(); -Query q = qm.createQuery("select excerpt(.) from nt:resource where contains(., 'exoplatform')", Query.SQL); -QueryResult result = q.execute(); -for (RowIterator it = result.getRows(); it.hasNext(); ) { - Row r = it.nextRow(); - Value excerpt = r.getValue("rep:excerpt(.)"); -}</programlisting> - </section> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-SpellChecker"> - <title>SpellChecker</title> - <para> - The lucene based query handler implementation supports a pluggable spell-checker mechanism. By default, spell checking is not available, it must be configured first. - </para> - <para> - Information about the <parameter>spellCheckerClass</parameter> parameter is available in <xref linkend="chap-Reference_Guide-Search_Configuration"/>. - </para> - <para> - The JCR currently provides an implementation class which uses the <ulink url="http://wiki.apache.org/jakarta-lucene/SpellChecker">lucene-spellchecker</ulink>. - </para> - <para> - The dictionary is derived from the fulltext, indexed content of the workspace and updated periodically. You can configure the refresh interval by picking one of the available inner classes of <literal>org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker</literal>: - </para> - <itemizedlist> - <listitem> - <para> - <literal>OneMinuteRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>FiveMinutesRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>ThirtyMinutesRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>OneHourRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>SixHoursRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>TwelveHoursRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>OneDayRefreshInterval</literal> - </para> - </listitem> - </itemizedlist> - <para> - For example, if you want a refresh interval of six hours, the class name would be; <literal>org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$SixHoursRefreshInterval</literal>. - </para> - <para> - If you use <literal>org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker</literal>, the refresh interval will be one hour. - </para> - <para> - The spell checker dictionary is stored as a lucene index under <filename><index-dir>/spellchecker</filename>. If this index does not exist, a background thread will create it on start up. Similarly, the dictionary refresh is also done in a background thread so as not to block regular queries. - </para> - <section id="sect-Reference_Guide-SpellChecker-Usage"> - <title>Usage</title> - <para> - You can spell check a fulltext statement either with an XPath or a SQL query: - </para> - <programlisting language="Java" role="Java">// rep:spellcheck('explatform') will always evaluate to true -Query query = qm.createQuery("/jcr:root[rep:spellcheck('explatform')]/(rep:spellcheck())", Query.XPATH); -RowIterator rows = query.execute().getRows(); -// the above query will always return the root node no matter what string we check -Row r = rows.nextRow(); -// get the result of the spell checking -Value v = r.getValue("rep:spellcheck()"); -if (v == null) { - // no suggestion returned, the spelling is correct or the spell checker - // does not know how to correct it. -} else { - String suggestion = v.getString(); -}</programlisting> - <para> - And the same using SQL: - </para> - <programlisting language="Java" role="Java">// SPELLCHECK('exoplatform') will always evaluate to true -Query query = qm.createQuery("SELECT rep:spellcheck() FROM nt:base WHERE jcr:path = '/' AND SPELLCHECK('explatform')", Query.SQL); -RowIterator rows = query.execute().getRows(); -// the above query will always return the root node no matter what string we check -Row r = rows.nextRow(); -// get the result of the spell checking -Value v = r.getValue("rep:spellcheck()"); -if (v == null) { - // no suggestion returned, the spelling is correct or the spell checker - // does not know how to correct it. -} else { - String suggestion = v.getString(); -}</programlisting> - </section> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-Similarity"> - <title>Similarity</title> - <para> - Starting with version, 1.12 JCR allows you to search for nodes that are similar to an existing node. - </para> - <para> - Similarity is determined by looking up terms that are common to nodes. There are some conditions that must be met for a term to be considered. This is required to limit the number possibly relevant terms. - </para> - <para> - To be considered, terms must: - </para> - <itemizedlist> - <listitem> - <para> - Be at least four characters long. - </para> - </listitem> - <listitem> - <para> - Occur at least twice in the source node. - </para> - </listitem> - <listitem> - <para> - Occur in at least five other nodes. - </para> - </listitem> - </itemizedlist> - <note> - <title>Note</title> - <para> - The similarity function requires that the support Hightlighting is enabled. Please make sure that you have the following parameter set for the query handler in your <filename>workspace.xml</filename>. - </para> - <programlisting language="XML" role="XML"><param name="support-highlighting" value="true"/></programlisting> - </note> - <para> - The functions (<code>rep:similar()</code> in XPath and <code>similar()</code> in SQL) have two arguments: - </para> - <variablelist> - <title/> - <varlistentry> - <term>relativePath</term> - <listitem> - <para> - A relative path to a descendant node or a period (<literal>.</literal>) for the current node. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>absoluteStringPath</term> - <listitem> - <para> - A string literal that contains the path to the node for which to find similar nodes. - </para> - </listitem> - </varlistentry> - </variablelist> - <warning> - <title>Warning</title> - <para> - Relative path is not supported yet. - </para> - </warning> - <example id="exam-Reference_Guide-Similarity-Example"> - <title>Example</title> - <programlisting>//element(*, nt:resource)[rep:similar(., '/parentnode/node.txt/jcr:content')]</programlisting> - <para> - Finds <literal>nt:resource</literal> nodes, which are similar to node by path <filename>/parentnode/node.txt/jcr:content</filename>. - </para> - </example> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-Fulltext_Search_And_Affecting_Settings"> - <title>Full Text Search And Affecting Settings</title> - <formalpara id="form-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Property_content_indexing"> - <title>Property content indexing</title> - <para> - Each property of a node (if it is indexable) is processed with the Lucene analyzer and stored in the Lucene index. This is called indexing of a property. It allows fulltext searching of these indexed properties. - </para> - </formalpara> - <section id="sect-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Lucene_Analyzers"> - <title>Lucene Analyzers</title> - <para> - The purpose of analyzers is to transform all strings stored in the index into a well-defined condition. The same analyzer(s) is/are used when searching in order to adapt the query string to the index reality. - </para> - <para> - Therefore, performing the same query using different analyzers can return different results. - </para> - <para> - The example below illustrates how the same string is transformed by different analyzers. - </para> - <table id="tabl-Reference_Guide-Lucene_Analyzers-The_quick_brown_fox_jumped_over_the_lazy_dogs"> - <title>"The quick brown fox jumped over the lazy dogs"</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Analyzer </entry> - <entry> Parsed </entry> - </row> - </thead> - <tbody> - <row> - <entry> org.apache.lucene.analysis.WhitespaceAnalyzer </entry> - <entry> [The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.SimpleAnalyzer </entry> - <entry> [the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.StopAnalyzer </entry> - <entry> [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.standard.StandardAnalyzer </entry> - <entry> [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.snowball.SnowballAnalyzer </entry> - <entry> [quick] [brown] [fox] [jump] [over] [lazi] [dog] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.standard.StandardAnalyzer (configured without stop word - jcr default analyzer) </entry> - <entry> [the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] </entry> - </row> - </tbody> - </tgroup> - </table> - <table id="tabl-Reference_Guide-Lucene_Analyzers-XYampZ_Corporation_xyzexample.com"> - <title>"XY&Z Corporation - xyz(a)example.com"</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Analyzer </entry> - <entry> Parsed </entry> - </row> - </thead> - <tbody> - <row> - <entry> org.apache.lucene.analysis.WhitespaceAnalyzer </entry> - <entry> [XY&Z] [Corporation] [-] [xyz(a)example.com] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.SimpleAnalyzer </entry> - <entry> [xy] [z] [corporation] [xyz] [example] [com] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.StopAnalyzer </entry> - <entry> [xy] [z] [corporation] [xyz] [example] [com] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.standard.StandardAnalyzer </entry> - <entry> [xy&z] [corporation] [xyz@example] [com] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.snowball.SnowballAnalyzer </entry> - <entry> [xy&z] [corpor] [xyz@exampl] [com] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.standard.StandardAnalyzer (configured without stop word - jcr default analyzer) </entry> - <entry> [xy&z] [corporation] [xyz@example] [com] </entry> - </row> - </tbody> - </tgroup> - </table> - <note> - <para> - <literal>StandardAnalyzer</literal> is the default analyzer in the JBoss Portal Platform JCR search engine. But it does not use stop words. - </para> - </note> - <para> - You can assign your analyzer as described in <xref linkend="chap-Reference_Guide-Search_Configuration"/>. - </para> - </section> - <section id="sect-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Property_Indexing"> - <title>Property Indexing</title> - <para> - Different properties are indexed in different ways and this affects whether it can be searched via fulltext by property or not. - </para> - <para> - Only two property types are indexed as fulltext searcheable: <parameter>STRING</parameter> and <parameter>BINARY</parameter>. - </para> - <table id="tabl-Reference_Guide-Property_Indexing-Fulltext_search_by_different_properties"> - <title>Fulltext search by different properties</title> - <tgroup cols="3"> - <thead> - <row> - <entry> Property Type </entry> - <entry> Fulltext search by all properties </entry> - <entry> Fulltext search by exact property </entry> - </row> - </thead> - <tbody> - <row> - <entry> STRING </entry> - <entry> YES </entry> - <entry> YES </entry> - </row> - <row> - <entry> BINARY </entry> - <entry> YES </entry> - <entry> NO </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - For example, the <literal>jcr:data</literal> property (which is <parameter>BINARY</parameter>) will not be found with a query structured as: - </para> - <programlisting>SELECT * FROM nt:resource WHERE CONTAINS(jcr:data, 'some string')</programlisting> - <para> - This is because, <parameter>BINARY</parameter> is not searchable by fulltext search by exact property. - </para> - <para> - However, the following query <emphasis>will</emphasis> return some results (provided, of course they node contains the targeted data): - </para> - <programlisting>SELECT * FROM nt:resource WHERE CONTAINS( * , 'some string')</programlisting> - </section> - <section id="sect-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Different_Analyzers"> - <title>Different Analyzers</title> - <para> - First of all, we will fill repository by nodes with mixin type 'mix:title' and different values of 'jcr:description' property. - </para> - <programlisting>root - ├── document1 (mix:title) jcr:description = "The quick brown fox jumped over the lazy dogs" - ├── document2 (mix:title) jcr:description = "Brown fox live in forest." - └── document3 (mix:title) jcr:description = "Fox is a nice animal." -</programlisting> - <para> - The example below shows different Analyzers in action. The first instance uses base JCR settings, so the string; "<emphasis>The quick brown fox jumped over the lazy dogs</emphasis>" will be transformed to the set; <emphasis role="bold">{[the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] }</emphasis>. - </para> - <programlisting language="Java" role="Java">// make SQL query -QueryManager queryManager = workspace.getQueryManager(); -String sqlStatement = "SELECT * FROM mix:title WHERE CONTAINS(jcr:description, 'the')"; -// create query -Query query = queryManager.createQuery(sqlStatement, Query.SQL); -// execute query and fetch result -QueryResult result = query.execute();</programlisting> - <para> - The <literal>NodeIterator</literal> will return <emphasis>document1</emphasis>. - </para> - <para> - However, if the default analyzer is changed to <literal>org.apache.lucene.analysis.StopAnalyzer</literal>, the repository populated again (the new Analyzer must process node properties) and the same query run, it will return nothing, because stop words like "<emphasis>the</emphasis>" will be excluded from parsed string set. - </para> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-WebDAV"> - <title>WebDAV</title> - <section id="sect-Reference_Guide-WebDAV-Introduction"> - <title>Introduction</title> - <para> - The <application>WebDAV</application> protocol enables you to use third party tools to communicate with hierarchical content servers via the HTTP protocol. It is possible to add and remove documents or a set of documents from a path on the server. - </para> - <para> - <application>DeltaV</application> is an extension of the WebDav protocol that allows managing document versioning. The <emphasis>Locking</emphasis> feature guarantees protection against multiple access when writing resources. The ordering support allows changing the position of the resource in the list and sort the directory to make the directory tree viewed conveniently. The full-text search makes it easy to find the necessary documents. You can search by using two languages: SQL and XPATH. - </para> - <para> - In the eXo JCR, the WebDAV layer (based on the code taken from the extension modules of the reference implementation) is plugged in on top of our JCR implementation. This makes it possible to browse a workspace using the third party tools regardless of operating system environments. You can use a Java WebDAV client, such as <application>DAVExplorer</application> or <application>Internet Explorer</application> using <menuchoice> - <guimenu>File</guimenu> - <guimenuitem>Open as a Web Folder</guimenuitem> - </menuchoice>. - </para> - <para> - WebDav is an extension of the REST service. To get the WebDav server ready, you must deploy the REST application. Then, you can access any workspaces of your repository by using the following URL: - </para> - <para> - <ulink url="http://host:port/portal/rest/private/jcr/{RepositoryName}/{WorkspaceName}..." type="http"/> - </para> - <para> - When accessing the WebDAV server via <ulink url="http://localhost:8080/rest/jcr/repository/production" type="http"/>, you can substitute <ulink url="http://localhost:8080/rest/jcr/repository/production" type="http">production</ulink> with <ulink url="http://localhost:8080/rest/jcr/repository/collaboration" type="http">collaboration</ulink>. - </para> - <para> - You will be asked to enter your login credentials. These will then be checked by using the organization service that can be implemented thanks to an InMemory (dummy) module or a DB module or an LDAP one and the JCR user session will be created with the correct JCR Credentials. - </para> - <note> - <title>Note:</title> - <para> - If you try the "in ECM" option, add "@ecm" to the user's password. Alternatively, you may modify jaas.conf by adding the <emphasis role="bold">domain=ecm</emphasis> option as follows: - </para> - <programlisting>exo-domain { - org.exoplatform.services.security.jaas.BasicLoginModule required domain=ecm; -};</programlisting> - </note> - </section> - <section id="sect-Reference_Guide-WebDAV-WebDAV_Configuration"> - <title>WebDAV Configuration</title> - <para> - The WebDAV configuration file: - </para> - <programlisting language="XML" role="XML"><component> - <key>org.exoplatform.services.webdav.WebDavServiceImpl</key> - <type>org.exoplatform.services.webdav.WebDavServiceImpl</type> - <init-params> - -  -  - -  - <value-param> - <name>auth-header</name> - <value>Basic realm="eXo-Platform Webdav Server 1.6.1"</value> - </value-param> - -  - <value-param> - <name>def-folder-node-type</name> - <value>nt:folder</value> - </value-param> - -  - <value-param> - <name>def-file-node-type</name> - <value>nt:file</value> - </value-param> - -  - <value-param> - <name>def-file-mimetype</name> - <value>application/octet-stream</value> - </value-param> - -  - - <value-param> - <name>update-policy</name> - <value>create-version</value> -  -  - </value-param> - -  - <value-param> - <name>auto-version</name> - <value>checkout-checkin</value> -  - </value-param> - -  - <value-param> - <name>cache-control</name> - <value>text/xml,text/html:max-age=3600;image/png,image/jpg:max-age=1800;*/*:no-cache;</value> - </value-param> - -  - <value-param> - <name>folder-icon-path</name> - <value>/absolute/path/to/file</value> - </value-param> - - </init-params> -</component></programlisting> - </section> - <section id="sect-Reference_Guide-WebDAV-Corresponding_WebDav_and_JCR_actions"> - <title>Corresponding WebDAV and JCR actions</title> - <table> - <title/> - <tgroup cols="2"> - <thead> - <row> - <entry> WebDav </entry> - <entry> JCR </entry> - </row> - </thead> - <tbody> - <row> - <entry> COPY </entry> - <entry> Workspace.copy(...) </entry> - </row> - <row> - <entry> DELETE </entry> - <entry> Node.remove() </entry> - </row> - <row> - <entry> GET </entry> - <entry> Node.getProperty(...); Property.getValue() </entry> - </row> - <row> - <entry> HEAD </entry> - <entry> Node.getProperty(...); Property.getLength() </entry> - </row> - <row> - <entry> MKCOL </entry> - <entry> Node.addNode(...) </entry> - </row> - <row> - <entry> MOVE </entry> - <entry> Session.move(...) or Workspace.move(...) </entry> - </row> - <row> - <entry> PROPFIND </entry> - <entry> Session.getNode(...); Node.getNode(...); Node.getNodes(...); Node.getProperties() </entry> - </row> - <row> - <entry> PROPPATCH </entry> - <entry> Node.setProperty(...); Node.getProperty(...).remove() </entry> - </row> - <row> - <entry> PUT </entry> - <entry> Node.addNode("node","nt:file"); Node.setProperty("jcr:data", "data") </entry> - </row> - <row> - <entry> CHECKIN </entry> - <entry> Node.checkin() </entry> - </row> - <row> - <entry> CHECKOUT </entry> - <entry> Node.checkout() </entry> - </row> - <row> - <entry> REPORT </entry> - <entry> Node.getVersionHistory(); VersionHistory.getAllVersions(); Version.getProperties() </entry> - </row> - <row> - <entry> RESTORE </entry> - <entry> Node.restore(...) </entry> - </row> - <row> - <entry> UNCHECKOUT </entry> - <entry> Node.restore(...) </entry> - </row> - <row> - <entry> VERSION-CONTROL </entry> - <entry> Node.addMixin("mix:versionable") </entry> - </row> - <row> - <entry> LOCK </entry> - <entry> Node.lock(...) </entry> - </row> - <row> - <entry> UNLOCK </entry> - <entry> Node.unlock() </entry> - </row> - <row> - <entry> ORDERPATCH </entry> - <entry> Node.orderBefore(...) </entry> - </row> - <row> - <entry> SEARCH </entry> - <entry> Workspace.getQueryManager(); QueryManager.createQuery(); Query.execute() </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section id="sect-Reference_Guide-WebDAV-WebDAV_Considerations"> - <title>WebDAV Considerations</title> - <para> - There are some restrictions for WebDAV in different operating systems. - </para> - <formalpara id="form-Reference_Guide-WebDAV_Considerations-Windows_7"> - <title>Windows 7</title> - <para> - When attempting to set up a web folder through <guilabel>Add a Network Location</guilabel> or <guilabel>Map a Network Drive</guilabel> through <guilabel>My Computer</guilabel>, an error message stating <guilabel>The folder you entered does not appear to be valid. Please choose another</guilabel> or <guilabel>Windows cannot access … Check the spelling of the name. Otherwise, there might be …</guilabel> may be encountered. These errors may appear when you are using SSL or non-SSL. - </para> - </formalpara> - <para> - To fix this, do as follows: - </para> - <procedure> - <step> - <para> - Go to Windows Registry Editor. - </para> - </step> - <step> - <para> - Find a key: \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlset\services\WebClient\Parameters\BasicAuthLevel . - </para> - </step> - <step> - <para> - Change the value to 2. - </para> - </step> - </procedure> - <formalpara id="form-Reference_Guide-WebDAV_Considerations-Microsoft_Office_2010"> - <title>Microsoft Office 2010</title> - <para> - If you have: - </para> - </formalpara> - <itemizedlist> - <listitem> - <para> - Microsoft Office 2007/2010 applications installed on a client computer AND... - </para> - </listitem> - <listitem> - <para> - The client computer is connected to a web server configured for Basic authentication VIA... - </para> - </listitem> - <listitem> - <para> - A connection that does not use Secure Sockets Layer (SSL) AND... - </para> - </listitem> - <listitem> - <para> - You try to access an Office file that is stored on the remote server... - </para> - </listitem> - <listitem> - <para> - You might experience the following symptoms when you try to open or to download the file: - </para> - <itemizedlist> - <listitem> - <para> - The Office file does not open or download. - </para> - </listitem> - <listitem> - <para> - You do not receive a Basic authentication password prompt when you try to open or to download the file. - </para> - </listitem> - <listitem> - <para> - You do not receive an error message when you try to open the file. The associated Office application starts. However, the selected file does not open. - </para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - <para> - These outcomes can be circumvented by enabling Basic authentication on the client machine. - </para> - <para> - To enable Basic authentication on the client computer, follow these steps: - </para> - <procedure> - <step> - <para> - Click Start, type <literal>regedit</literal> in the Start Search box, and then press Enter. - </para> - </step> - <step> - <para> - Locate and then click the following registry subkey: - </para> - <para> - <envar>HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Common\Internet</envar> - </para> - </step> - <step> - <para> - On the <guilabel>Edit</guilabel> menu, point to <guilabel>New</guilabel>, and then click <guilabel>DWORD Value</guilabel>. - </para> - </step> - <step> - <para> - Type <literal>BasicAuthLevel</literal>, and then press <keycap>Enter</keycap>. - </para> - </step> - <step> - <para> - Right-click <literal>BasicAuthLevel</literal>, and then click <guilabel>Modify</guilabel>. - </para> - </step> - <step> - <para> - In the Value data box, type <literal>2</literal>, and then click <guilabel>OK</guilabel>. - </para> - </step> - </procedure> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-FTP"> - <title>FTP</title> - <section id="sect-Reference_Guide-FTP-Introduction"> - <title>Introduction</title> - <para> - The JCR-FTP Server operates as an FTP server with access to a content stored in JCR repositories in the form of <literal>nt:file/nt:folder</literal> nodes or their successors. The client of an executed Server can be any FTP client. The FTP server is supported by a standard configuration which can be changed as required. - </para> - </section> - <section id="sect-Reference_Guide-FTP-Configuration_Parameters"> - <title>Configuration Parameters</title> - <variablelist id="vari-Reference_Guide-Configuration_Parameters-Parameters"> - <title>Parameters</title> - <varlistentry> - <term>command-port:</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>command-port</name> - <value>21</value> -</value-param></programlisting> - <para> - The value of the command channel port. The value '<literal>21</literal>' is default. - </para> - <para> - If you have already other FTP server installed in your system, this parameter needs to be changed (to <literal>2121</literal>, for example) to avoid conflicts or if the port is protected. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>data-min-port and data-max-port</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>data-min-port</name> - <value>52000</value> -</value-param></programlisting> - <programlisting language="XML" role="XML"><value-param> - <name>data-max-port</name> - <value>53000</value> -</value-param></programlisting> - <para> - These two parameters indicate the minimum and maximum values of the range of ports, used by the server. The usage of the additional data channel is required by the FTP protocol, which is used to transfer the contents of files and the listing of catalogues. This range of ports should be free from listening by other server-programs. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>system</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>system</name> - - <value>Windows_NT</value> - or - <value>UNIX Type: L8</value> -</value-param></programlisting> - <para> - Types of formats of listing of catalogues which are supported. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>client-side-encoding</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>client-side-encoding</name> - - <value>windows-1251</value> - or - <value>KOI8-R</value> - -</value-param></programlisting> - <para> - This parameter specifies the coding which is used for dialogue with the client. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>def-folder-node-type</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>def-folder-node-type</name> - <value>nt:folder</value> -</value-param></programlisting> - <para> - This parameter specifies the type of a node, when an FTP-folder is created. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>def-file-node-type</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>def-file-node-type</name> - <value>nt:file</value> -</value-param></programlisting> - <para> - This parameter specifies the type of a node, when an FTP-file is created. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>def-file-mime-type</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>def-file-mime-type</name> - <value>application/zip</value> -</value-param></programlisting> - <para> - The mime type of a created file is chosen by using its file extension. In case, a server cannot find the corresponding mime type, this value is used. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>cache-folder-name</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>cache-folder-name</name> - <value>../temp/ftp_cache</value> -</value-param></programlisting> - <para> - The Path of the cache folder. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>upload-speed-limit</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>upload-speed-limit</name> - <value>20480</value> -</value-param></programlisting> - <para> - Restriction of the upload speed. It is measured in bytes. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>download-speed-limit</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>download-speed-limit</name> - <value>20480</value> -</value-param></programlisting> - <para> - Restriction of the download speed. It is measured in bytes. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>timeout</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>timeout</name> - <value>60</value> -</value-param></programlisting> - <para> - Defines the value of a timeout. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-Use_External_Backup_Tool"> - <title>Use External Backup Tool</title> - <section id="sect-Reference_Guide-Use_External_Backup_Tool-Repository_Suspending"> - <title>Repository Suspending</title> - <para> - To have the repository content consistent with the search index and value storage, the repository should be suspended. This means all working threads are suspended until a resume operation is performed. The index will be flushed. - </para> - <para> - JCR provides ability to suspend repository via JMX. - </para> - <figure> - <title id="repositorysuspendcontroller">Repository Suspend Controller</title> - <mediaobject> - <imageobject> - <imagedata width="444" fileref="images/eXoJCR/repository-suspend-controller.png"/> - </imageobject> - </mediaobject> - </figure> - <para> - To suspend repository you need to invoke the <literal>suspend()</literal> operation. The returned result will be "<emphasis>suspended</emphasis>" if everything passed successfully. - </para> - <figure> - <title id="repository-suspend-controller-suspended.">Repository Suspend Controller Suspended</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/repository-suspend-controller-suspended.png"/> - </imageobject> - </mediaobject> - </figure> - <para> - An "<emphasis>undefined</emphasis>" result means not all components were successfully suspended. Check the console to review the stack traces. - </para> - </section> - <section id="sect-Reference_Guide-Use_External_Backup_Tool-Backup"> - <title>Backup</title> - <para> - You can backup your content manually or by using third part software. You should back up: - </para> - <itemizedlist> - <listitem> - <para> - Database. - </para> - </listitem> - <listitem> - <para> - Lucene index. - </para> - </listitem> - <listitem> - <para> - Value storage (if configured). - </para> - </listitem> - </itemizedlist> - </section> - <section id="sect-Reference_Guide-Use_External_Backup_Tool-Repository_Resuming"> - <title>Repository Resuming</title> - <para> - Once a backup is done you need to invoke the <literal>resume()</literal> operation to switch the repository back to on-line. The returned result will be "<emphasis>on-line</emphasis>". - </para> - <figure> - <title id="repository-suspend-controller-online.">Repository Suspend Controller Online</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/repository-suspend-controller-online.png"/> - </imageobject> - </mediaobject> - </figure> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-eXo_JCR_statistics"> - <title>eXo JCR statistics</title> - <section id="sect-Reference_Guide-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 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 the method has been called. - </para> - </listitem> - </itemizedlist> - <para> - Those figures are also available globally 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-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> 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> 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> 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> 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> 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> 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> 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> 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> close </entry> - <entry> This is the alias for the method <emphasis>close().</emphasis></entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section id="sect-Reference_Guide-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 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="https://repository.jboss.org/nexus/content/groups/public/org/exoplatform/...">https://repository.jboss.org/nexus/content/groups/public/org/exoplatform/...</ulink>. - </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"> - <uri>http://repo2.maven.org/maven2/org/aspectj/aspectjrt</uri> - </ulink>. - </para> - </listitem> - </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">http://repo2.maven.org/maven2/org/aspectj/aspectjweaver</ulink>. - </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-configuration.html">http://www.eclipse.org/aspectj/doc/released/devguide/ltw-configuration.html</ulink>. - </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"><configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"> - - <component> - <type>org.exoplatform.services.jcr.statistics.JCRAPIAspectConfig</type> - <init-params> - <values-param> - <name>targetInterfaces</name> - <value>org.exoplatform.services.jcr.core.ExtendedSession</value> - <value>org.exoplatform.services.jcr.core.ExtendedNode</value> - <value>javax.jcr.Property</value> - </values-param> - </init-params> - </component> -</configuration></programlisting> - <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"><aspectj> - <aspects> - <concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect"> - <pointcut name="JCRAPIPointcut" - expression="(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) && call(public * *(..))" /> - </concrete-aspect> - </aspects> - <weaver options="-XnoInline"> - <include within="org.exoplatform..*" /> - </weaver> -</aspectj></programlisting> - <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_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-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> 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> Times </entry> - <entry> The total amount of times the method has been called. </entry> - </row> - </tbody> - </tgroup> - </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-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 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 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 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> - </tbody> - </tgroup> - </table> - The full name of the related MBean is <literal>xo:service=statistic, view=jcr</literal>. - </para> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-Checking_repository_integrity_and_consistency"> - <title>Checking repository integrity and consistency</title> - <section id="sect-Reference_Guide-Checking_repository_integrity_and_consistency-JMX_based_consistency_tool"> - <title>JMX-based consistency tool</title> - <para> - It is important to check the integrity and consistency of system regularly, especially if there is no, or stale, backups. The JBoss Portal Platform JCR implementation offers an innovative JMX-based complex checking tool. - </para> - <para> - During an inspection, the tool checks every major JCR component, such as persistent data layer and the index. The persistent layer includes JDBC Data Container and Value-Storages if they are configured. - </para> - <para> - The database is verified using the set of complex specialized domain-specific queries. The Value Storage tool checks the existence of, and access to, each file. - </para> - <para> - Access to the check tool is exposed via the JMX interface, with the following operations available: - </para> - <table id="tabl-Reference_Guide-JMX_based_consistency_tool-Available_methods"> - <title>Available methods</title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - <code>checkRepositoryDataConsistency()</code> - </entry> - <entry> Inspect full repository data (db, value storage and search index) </entry> - </row> - <row> - <entry> - <code>checkRepositoryDataBaseConsistency()</code> - </entry> - <entry> Inspect only DB </entry> - </row> - <row> - <entry> - <code>checkRepositoryValueStorageConsistency()</code> - </entry> - <entry> Inspect only ValueStorage </entry> - </row> - <row> - <entry> - <code>checkRepositorySearchIndexConsistency()</code> - </entry> - <entry> Inspect only SearchIndex </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - All inspection activities and corrupted data details are stored in a file in the <filename>app</filename> directory and named as per the following convention: <code> report-<replaceable><repository name></replaceable>-<replaceable>dd-MMM-yy-HH-mm</replaceable>.txt </code>. - </para> - <para> - The path to the file will be returned in result message also at the end of the inspection. - </para> - <note> - <para> - There are three types of inconsistency (Warning, Error and Index) and two of them are critical (Errors and Index): - </para> - <itemizedlist> - <listitem> - <para> - Index faults are marked as "Reindex" and can be fixed by re-indexing the workspace. - </para> - </listitem> - <listitem> - <para> - Errors can only be fixed manually. - </para> - </listitem> - <listitem> - <para> - Warnings can be a normal situation in some cases and usually production system will still remain fully functional. - </para> - </listitem> - </itemizedlist> - </note> - </section> - </chapter> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/search-configuration.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/jdbc-data-container-config.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/external-value-storages.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/workspace-persistence-storage.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/cluster-config.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/jbosscache-configuration-templates.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/lock-manager-config.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/query-handler-config.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/jbossts-transaction-service.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/searching/jcr-query-usecases.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/searching/searching-repository-content.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/searching/fulltext-search-and-settings.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/protocols/webdav.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/protocols/ftp.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/backup/use-external-backup-tool.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/statistics.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/repository-check-controller.xml"/>  <chapter xmlns="" id="chap-Reference_Guide-JCR_Performance_Tuning_Guide"> - <title>JCR Performance Tuning Guide</title> - <section id="sect-Reference_Guide-JCR_Performance_Tuning_Guide-Introduction"> - <title>Introduction</title> - <para> - This section will show you various ways of improving JCR performance. - </para> - <para> - It is intended for Administrators and others who want to use the JCR features more efficiently. - </para> - </section> - <section id="sect-Reference_Guide-JCR_Performance_Tuning_Guide-JCR_Performance_and_Scalability"> - <title>JCR Performance and Scalability</title> - <section id="sect-Reference_Guide-JCR_Performance_and_Scalability-Cluster_configuration"> - <title>Cluster configuration</title> - <para> - The table below contains details about the configuration of the cluster used in benchmark testing: - </para> - <table id="tabl-Reference_Guide-Cluster_configuration-EC2_network_1Gbit"> - <title>EC2 network: 1Gbit</title> - <tgroup cols="2"> - <colspec colname="1"/> - <colspec colname="2"/> - <spanspec namest="1" nameend="2" spanname="hspan"/> - <thead> - <row> - <entry> Servers hardware </entry> - <entry> Specification </entry> - </row> - </thead> - <tbody> - <row> - <entry> RAM </entry> - <entry> 7.5 GB </entry> - </row> - <row> - <entry> Processors </entry> - <entry> 4 EC2 Compute Units (2 virtual cores with 2 EC2 Compute Units each) </entry> - </row> - <row> - <entry> Storage </entry> - <entry> 850 GB (2×420 GB plus 10 GB root partition) </entry> - </row> - <row> - <entry> Architecture </entry> - <entry> 64-bit </entry> - </row> - <row> - <entry> I/O Performance </entry> - <entry> High </entry> - </row> - <row> - <entry> API name </entry> - <entry> - <literal>m1.large</literal> - </entry> - </row> - <row> - <entry spanname="hspan"> - <emphasis role="bold">Note:</emphasis> - </entry> - </row> - <row> - <entry spanname="hspan"> NFS and statistics (cacti snmp) server were located on one physical server. </entry> - </row> - <row> - <entry spanname="hspan"> - <emphasis role="bold">JBoss Enterprise Application Platform 6 configuration:</emphasis> - </entry> - </row> - <row> - <entry spanname="hspan"> - <code>JAVA_OPTS: -Dprogram.name=run.sh -server -Xms4g -Xmx4g -XX:MaxPermSize=512m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -XX:+UseParallelGC -Djava.net.preferIPv4Stack=true</code> - </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section id="sect-Reference_Guide-JCR_Performance_and_Scalability-JCR_Clustered_Performance"> - <title>JCR Clustered Performance</title> - <para> - Benchmark test using WebDAV (Complex read/write load test (benchmark)) with 20K same file. To obtain per-operation results we have used custom output from the test case threads to CSV file. - </para> - <para> - <citetitle>Read operation</citetitle>: - <simplelist> - <member>Warm-up iterations: 100</member> - <member>Run iterations: 2000</member> - <member>Background writing threads: 25</member> - <member>Reading threads: 225</member> - </simplelist> - - </para> - <figure> - <title id="perf_EC2_result">EC2 Performance Results</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/perf_EC2_results.jpg"/> - </imageobject> - </mediaobject> - </figure> - <table> - <title/> - <tgroup cols="4"> - <thead> - <row> - <entry> Nodes count </entry> - <entry> tps </entry> - <entry> Responses >2s </entry> - <entry> Responses >4s </entry> - </row> - </thead> - <tbody> - <row> - <entry> 1 </entry> - <entry> 523 </entry> - <entry> 6.87% </entry> - <entry> 1.27% </entry> - </row> - <row> - <entry> 2 </entry> - <entry> 1754 </entry> - <entry> 0.64% </entry> - <entry> 0.08% </entry> - </row> - <row> - <entry> 3 </entry> - <entry> 2388 </entry> - <entry> 0.49% </entry> - <entry> 0.09% </entry> - </row> - <row> - <entry> 4 </entry> - <entry> 2706 </entry> - <entry> 0.46% </entry> - <entry> 0.1% </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - <citetitle>Read operation with more threads</citetitle>: - </para> - <simplelist> - <member>Warm-up iterations: 100</member> - <member>Run iterations: 2000</member> - <member>Background writing threads: 50</member> - <member>Reading threads: 450</member> - </simplelist> - <figure> - <title id="perf_EC2_result2">EC2 Performance Results 2</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/perf_EC2_results_2.jpg"/> - </imageobject> - </mediaobject> - </figure> - <table> - <title/> - <tgroup cols="4"> - <thead> - <row> - <entry> Nodes count </entry> - <entry> tps </entry> - <entry> Responses >2s </entry> - <entry> Responses >4s </entry> - </row> - </thead> - <tbody> - <row> - <entry> 1 </entry> - <entry> 116 </entry> - <entry> ? </entry> - <entry> ? </entry> - </row> - <row> - <entry> 2 </entry> - <entry> 1558 </entry> - <entry> 6.1% </entry> - <entry> 0.6% </entry> - </row> - <row> - <entry> 3 </entry> - <entry> 2242 </entry> - <entry> 3.1% </entry> - <entry> 0.38% </entry> - </row> - <row> - <entry> 4 </entry> - <entry> 2756 </entry> - <entry> 2.2% </entry> - <entry> 0.41% </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - </section> - <section id="sect-Reference_Guide-JCR_Performance_Tuning_Guide-Performance_Tuning_Guide"> - <title>Performance Tuning Guide</title> - <section id="sect-Reference_Guide-Performance_Tuning_Guide-JBoss_AS_Tuning"> - <title>JBoss Enterprise Application Platform 6 Tuning</title> - <para> - You can use <parameter>maxThreads</parameter> parameter to increase maximum amount of threads that can be launched in AS instance. This can improve performance if you need a high level of concurrency. also you can use <code>-XX:+UseParallelGC</code> java directory to use parallel garbage collector. - </para> - <note> - <title>Note</title> - <para> - Beware of setting <parameter>maxThreads</parameter> too big, this can cause <exceptionname>OutOfMemoryError</exceptionname>. We've got it with <code>maxThreads=1250</code> on such machine: - </para> - <simplelist> - <member>7.5 GB memory</member> - <member>4 EC2 Compute Units (2 virtual cores with 2 EC2 Compute Units each)</member> - <member>850 GB instance storage (2×420 GB plus 10 GB root partition)</member> - <member>64-bit platform</member> - <member>I/O Performance: High</member> - <member>API name: m1.large</member> - <member>java -Xmx 4g</member> - </simplelist> - </note> - </section> - <section id="sect-Reference_Guide-Performance_Tuning_Guide-JCR_Cache_Tuning"> - <title>JCR Cache Tuning</title> - <para> - <citetitle>Cache size</citetitle> - </para> - <para> - JCR-cluster implementation is built using JBoss Cache as distributed, replicated cache. But there is one particularity related to remove action in it. Speed of this operation depends on the actual size of cache. As many nodes are currently in cache as much time is needed to remove one particular node (subtree) from it. - </para> - <para> - <citetitle>Eviction</citetitle> - </para> - <para> - Manipulations with eviction <parameter>wakeUpInterval</parameter> value does not affect on performance. Performance results with values from 500 up to 3000 are approximately equal. - </para> - <para> - <citetitle>Transaction Timeout</citetitle> - </para> - <para> - Using short timeout for long transactions such as Export/Import, removing huge subtree defined timeout may cause <exceptionname>TransactionTimeoutException</exceptionname>. - </para> - </section> - <section id="sect-Reference_Guide-Performance_Tuning_Guide-Clustering"> - <title>Clustering</title> - <para> - For performance it is better to have a load-balancer, DB server and shared NFS on different computers. If in some reasons you see that one node gets more load than others you can decrease this load using load value in load balancer. - </para> - <para> - <citetitle>JGroups configuration</citetitle> - </para> - <para> - It's recommended to use "multiplexer stack" feature present in JGroups. It is set by default in eXo JCR and offers higher performance in cluster, using less network connections also. If there are two or more clusters in your network, please check that they use different ports and different cluster names. - </para> - <para> - <citetitle>Write performance in cluster</citetitle> - </para> - <para> - Exo JCR implementation uses Lucene indexing engine to provide search capabilities. But Lucene brings some limitations for write operations: it can perform indexing only in one thread. That is why write performance in cluster is not higher than in singleton environment. Data is indexed on coordinator node, so increasing write-load on cluster may lead to ReplicationTimeout exception. It occurs because writing threads queue in the indexer and under high load timeout for replication to coordinator will be exceeded. - </para> - <para> - Taking in consideration this fact, it is recommended to exceed <parameter>replTimeout</parameter> value in cache configurations in case of high write-load. - </para> - <para> - <citetitle>Replication timeout</citetitle> - </para> - <para> - Some operations may take too much time. So if you get <exceptionname>ReplicationTimeoutException</exceptionname> try increasing replication timeout: - </para> - <programlisting language="XML" role="XML"> <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> - ... - <sync replTimeout="60000" /> - </clustering> -</programlisting> - <para> - value is set in milliseconds. - </para> - </section> - </section> - </chapter> - <chapter xmlns="" id="chap-Reference_Guide-eXo_JCR_with_GateIn"> - <title>eXo JCR with JBoss Portal Platform</title> - <section xmlns="" id="sect-Reference_Guide-How_to_use_AS_Managed_DataSource_under_JBoss_AS"> - <title>How to use a Managed DataSource under JBoss Enterprise Application Platform 6</title> - <section id="sect-Reference_Guide-How_to_use_AS_Managed_DataSource_under_JBoss_AS-Configurations_Steps"> - <title>Configurations Steps</title> - <section id="sect-Reference_Guide-Configurations_Steps-Declaring_the_datasources_in_the_AS"> - <title>Declaring the Datasources in the AS</title> - <remark>NEEDINFO - FILE PATHS - I know this isn't right. Where do these get deployed again?</remark> - <para> - To declare the datasources using a JBoss application server, deploy a <literal>ds</literal> file (<filename><replaceable>XXX</replaceable>-ds.xml</filename>) into the <emphasis>deploy</emphasis> directory of the appropriate server profile (<filename>/server/<replaceable>PROFILE</replaceable>/deploy</filename>, for example). - </para> - <para> - This file configures all datasources which JBoss Portal Platform will need (there should be four specifically named: <emphasis>jdbcjcr_portal</emphasis>, <emphasis>jdbcjcr_portal-sample</emphasis>, <emphasis>jdbcidm_portal</emphasis> and <emphasis>jdbcidm_sample-portal</emphasis>). - </para> - <para> - For example: - </para> - <programlisting language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?> -<datasources> - <no-tx-datasource> - <jndi-name>jdbcjcr_portal</jndi-name> - <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcjcr_portal</connection-url> - <driver-class>org.hsqldb.jdbcDriver</driver-class> - <user-name>sa</user-name> - <password></password> - </no-tx-datasource> - - <no-tx-datasource> - <jndi-name>jdbcjcr_sample-portal</jndi-name> - <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcjcr_sample-portal</connection-url> - <driver-class>org.hsqldb.jdbcDriver</driver-class> - <user-name>sa</user-name> - <password></password> - </no-tx-datasource> - - <no-tx-datasource> - <jndi-name>jdbcidm_portal</jndi-name> - <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcidm_portal</connection-url> - <driver-class>org.hsqldb.jdbcDriver</driver-class> - <user-name>sa</user-name> - <password></password> - </no-tx-datasource> - - <no-tx-datasource> - <jndi-name>jdbcidm_sample-portal</jndi-name> - <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcidm_sample-portal</connection-url> - <driver-class>org.hsqldb.jdbcDriver</driver-class> - <user-name>sa</user-name> - <password></password> - </no-tx-datasource> -</datasources></programlisting> - <para> - The properties can be set for datasource can be found here: <ulink url="http://docs.jboss.org/jbossas/docs/Server_Configuration_Guide/4/html/Conn...">Configuring JDBC DataSources - The non transactional DataSource configuration schema</ulink> - </para> - </section> - <section id="sect-Reference_Guide-Configurations_Steps-Do_not_bind_datasources_explicitly"> - <title>Do not bind datasources explicitly</title> - <para> - Do not let the portal explicitly bind datasources. </para> - <remark>NEEDINFO - FILE PATHS - I think some of the values have changed in the referenced file when I look at the new file below. New info required?</remark> - <para>Edit the <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/configuration.properties</filename> and comment out the following rows in the JCR section: - </para> - <programlisting>#gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver -#gatein.jcr.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr_${name} -#gatein.jcr.datasource.username=sa -#gatein.jcr.datasource.password=</programlisting> - <para> - Comment out the following lines in the IDM section: - </para> - <programlisting>#gatein.idm.datasource.driver=org.hsqldb.jdbcDriver -#gatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name} -#gatein.idm.datasource.username=sa -#gatein.idm.datasource.password=</programlisting> - <para> - Open the <filename>jcr-configuration.xml</filename> and <filename>idm-configuration.xml</filename> files and comment out references to the plug-in <literal>InitialContextInitializer</literal>. - </para> - <programlisting language="XML" role="XML"> -</programlisting> - </section> - </section> - </section> - </chapter> + DOC NOTE: Could possibly be moved to a specific Tuning Guide later --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/performance-tuning-guide.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr-with-gatein.xml"/> </part>

11 years, 7 months

1
0
0 / 0

gatein SVN: r9275 - epp/docs/JPP/trunk/Development_Guide/en-US.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-05-08 03:02:26 -0400 (Wed, 08 May 2013) New Revision: 9275 Added: epp/docs/JPP/trunk/Development_Guide/en-US/eXo_JCR.xml Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.ent epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.xml epp/docs/JPP/trunk/Development_Guide/en-US/Load_Groups.xml epp/docs/JPP/trunk/Development_Guide/en-US/Localization.xml epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml Log: Minor changes to ensure the book would build in Brew Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.ent =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.ent 2013-05-08 05:35:47 UTC (rev 9274) +++ epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.ent 2013-05-08 07:02:26 UTC (rev 9275) @@ -17,3 +17,4 @@ <!ENTITY VX "6"> <!ENTITY VY "6.1"> <!ENTITY VZ "6.1.0"> +<!ENTITY JCR_VERSION "1.15.3"> Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.xml 2013-05-08 05:35:47 UTC (rev 9274) +++ epp/docs/JPP/trunk/Development_Guide/en-US/Development_Guide.xml 2013-05-08 07:02:26 UTC (rev 9275) @@ -62,5638 +62,9 @@ <part> <title>Advanced Development Concepts</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="The_eXo_Kernel.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXo_JCR.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appendix-Quickstarts.xml"/> </part> - <appendix> - <title>eXo JCR</title> - <section xmlns="" id="chap-Reference_Guide-eXoJCR-Introduction"> - <title>Introduction and Scope</title> - <warning> - <title>eXo JCR usage</title> - <para> - The JBoss Portal Platform is using a JCR API to store its information for internal usage. We do not support usage of the JCR to store application information. - </para> - <para> - The information below is intended to assist users to understand particular low level details on how the JBoss Portal Platform works and how it can be fine-tuned. - </para> - </warning> - <para> - The term <emphasis role="bold">JCR</emphasis> refers to the Java Content Repository. The JCR is the data store of JBoss Portal Platform. All content is stored and managed via the JCR. - </para> - <para> - The eXo JCR included with JBoss Portal Platform &VY; is a (<ulink url="http://www.jcp.org/en/jsr/detail?id=170" type="http">JSR-170</ulink>) compliant implementation of the JCR 1.0 specification. The JCR provides versioning, textual search, access control, content event monitoring, and is used to storing text and binary data for the portal internal usage. The back-end storage of the JCR is configurable and can be a file system or a database. - </para> - <section id="sect-Reference_Guide-Introduction-Concepts"> - <title>Concepts</title> - <variablelist> - <varlistentry> - <term>Repository</term> - <listitem> - <para> - A repository is a form of data storage device. A 'repository' differs from a 'database' in the nature of the information contained. While a database holds hard data in rigid tables, a repository may access the data on a database by using less rigid <emphasis>meta</emphasis>-data. In this sense a repository operates as an 'interpreter' between the database(s) and the user. - </para> - <note> - <para> - The data model for the interface (the repository) is rarely the same as the data model used by the repository's underlying storage subsystems (such as a database), however the repository is able to make persistent data changes in the storage subsystem. - </para> - </note> - </listitem> - </varlistentry> - <varlistentry> - <term>Workspace</term> - <listitem> - <para> - The eXo JCR uses 'workspaces' as the main data abstraction in its data model. The content is stored in a workspace as a hierarchy of <emphasis>items</emphasis> and each workspace has its own hierarchy of items. - </para> - <para> - Repositories access one or more workspaces. Persistent JCR workspaces consist of a directed acyclic graph of <emphasis>items</emphasis> where the edges represent the parent-child relation. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Items</term> - <listitem> - <para> - An <emphasis>item</emphasis> is either a <emphasis>node</emphasis> or a <emphasis>property</emphasis>. Properties contain the data (either simple values or binary data). The nodes of a workspace give it its structure while the properties hold the data itself. - </para> - <variablelist> - <varlistentry> - <term>Nodes</term> - <listitem> - <para> - Nodes are identified using accepted <emphasis>namespacing</emphasis> conventions. Changed nodes may be versioned through an associated version graph to preserve data integrity. - </para> - <para> - Nodes can have various properties or child nodes associated to them. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Properties</term> - <listitem> - <para> - Properties hold data as values of predefined types, such as: <emphasis role="bold">String</emphasis>, <emphasis role="bold">Binary</emphasis>, <emphasis role="bold">Long</emphasis>, <emphasis role="bold">Boolean</emphasis>, <emphasis role="bold">Double</emphasis>, <emphasis role="bold">Date</emphasis>, <emphasis role="bold">Reference</emphasis> and <emphasis role="bold">Path</emphasis>. - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <term>The Data Model</term> - <listitem> - <para> - The core of any Content Repository is the data model. The data model defines the 'data elements' (fields, columns, attributes, etc.) that are stored in the CR and the relationships between these elements. - </para> - <para> - Data elements can be singular pieces of information (the value 3.14, for example), or compound values ('<emphasis>pi</emphasis>' = 3.14). A data model uses concepts like 'nodes', 'arrays' and 'links' to define relationships between data elements. - </para> - <para> - The use and structure of these elements forms the content repository's 'data model'. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Data Abstraction</term> - <listitem> - <para> - Data abstraction describes the separation between <emphasis>abstract</emphasis> and <emphasis>concrete</emphasis> properties of data stored in a repository. The <emphasis>concrete</emphasis> properties of the data refer to its implementation details. - </para> - <para> - The <emphasis>concrete</emphasis> properties of the data implementation may be changed without affecting the <emphasis>abstract</emphasis> properties of the data itself, which are read by the data client. - </para> - <para> - Consider the presentation of data in a list, graph or table. While the information <emphasis>implementation</emphasis> may change, the data itself is unaffected, and readers to whom the data is presented can perform a mental abstraction to interpret it correctly, regardless of the implementation. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-Implementation"> - <title>Implementation</title> - <para> - The relationships between the eXo Repository Service components are illustrated below: - </para> - <figure> - <title id="exojcr">Exo JCR</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/concepts/exojcr.gif"/> - </imageobject> - </mediaobject> - </figure> - <variablelist id="vari-Reference_Guide-Implementation-Definitions"> - <title>Definitions</title> - <varlistentry> - <term>eXo Container:</term> - <listitem> - <para> - A subclass of <parameter>org.exoplatform.container.ExoContainer</parameter> (<parameter>org.exoplatform.container.PortalContainer</parameter>) holds a reference to the Repository Service. - </para> - <variablelist> - <title/> - <varlistentry> - <term>Repository Service</term> - <listitem> - <para> - This contains information about repositories. eXo JCR is able to manage many Repositories. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Repository</term> - <listitem> - <para> - An implementation of <literal>javax.jcr.Repository</literal>. It holds references to one or more Workspace(s). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Workspace</term> - <listitem> - <para> - Container of a single rooted tree of Items. - </para> - <note> - <title>Note:</title> - <para> - That here it is not exactly the same as <literal>javax.jcr.Workspace</literal> as it is not a per Session object. - </para> - </note> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - <para> - The usual JCR application usecase includes two initial steps: - </para> - <procedure> - <step> - <para> - Obtaining Repository object by getting <emphasis role="bold">Repository Service</emphasis> via JNDI lookup if eXo repository is bound to the naming context using (see <xref linkend="chap-Reference_Guide-JCR_configuration"/> for details). - </para> - </step> - <step> - <para> - Creating a <parameter>javax.jcr.Session object</parameter> that calls <parameter>Repository.login(..)</parameter>. - </para> - </step> - </procedure> - <section id="sect-Reference_Guide-Implementation-Workspace_Data_Model"> - <title>Workspace Data Model</title> - <para> - The following diagram explains which components of a eXo JCR implementation are used in a data flow to perform operations specified in the JCR API. - </para> - <figure> - <title id="wsdatamodel">Workspace Data Model</title> - <mediaobject> - <imageobject> - <imagedata width="444" fileref="images/eXoJCR/concepts/wsdatamodel.gif"/> - </imageobject> - </mediaobject> - </figure> - <para> - The Workspace Data Model can be split into four levels by data isolation and value from the JCR model point of view. - </para> - <itemizedlist> - <listitem> - <para> - The eXo JCR core implements <emphasis role="bold">JCR API</emphasis> interfaces, such as Item, Node, Property. It contains JCR "<emphasis>logical</emphasis>" view on stored data. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">Session Level</emphasis>: isolates transient data viewable inside one JCR Session and interacts with API level using eXo JCR internal API. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">Session Data Manager</emphasis>: maintains transient session data. With data access/ modification/ validation logic, it contains Modified Items Storage to hold the data changed between subsequent save() calling and Session Items Cache. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">Transaction Data Manager</emphasis>: maintains session data between save() and transaction commit/ rollback if the current session is part of a transaction. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">Workspace Level</emphasis>: operates for particular workspace shared data. It contains per-Workspace objects - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">Workspace Storage Data Manager:</emphasis> maintains workspace data, including final validation, events firing, caching. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">Workspace Data Container</emphasis>: implements physical data storage. It allows different types of backend (like RDB, FS files, etc) to be used as a storage for JCR data. With the main Data Container, other storages for persisted Property Values can be configured and used. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">Indexer:</emphasis> maintains workspace data indexing for further queries. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">Storage Level</emphasis>: Persistent storages for: - </para> - <itemizedlist> - <listitem> - <para> - JCR Data - </para> - </listitem> - <listitem> - <para> - Indexes (Apache Lucene) - </para> - </listitem> - <listitem> - <para> - Values (e.g., for BLOBs) if different from the main Data Container - </para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-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="XML" role="XML"><!ELEMENT repository-service (repositories)> -<!ATTLIST repository-service default-repository NMTOKEN #REQUIRED> -<!ELEMENT repositories (repository)> -<!ELEMENT repository (security-domain,access-control,session-max-age,authentication-policy,workspaces)> -<!ATTLIST repository - default-workspace NMTOKEN #REQUIRED - name NMTOKEN #REQUIRED - system-workspace NMTOKEN #REQUIRED -> -<!ELEMENT security-domain (#PCDATA)> -<!ELEMENT access-control (#PCDATA)> -<!ELEMENT session-max-age (#PCDATA)> -<!ELEMENT authentication-policy (#PCDATA)> -<!ELEMENT workspaces (workspace+)> -<!ELEMENT workspace (container,initializer,cache,query-handler)> -<!ATTLIST workspace name NMTOKEN #REQUIRED> -<!ELEMENT container (properties,value-storages)> -<!ATTLIST container class NMTOKEN #REQUIRED> -<!ELEMENT value-storages (value-storage+)> -<!ELEMENT value-storage (properties,filters)> -<!ATTLIST value-storage class NMTOKEN #REQUIRED> -<!ELEMENT filters (filter+)> -<!ELEMENT filter EMPTY> -<!ATTLIST filter property-type NMTOKEN #REQUIRED> -<!ELEMENT initializer (properties)> -<!ATTLIST initializer class NMTOKEN #REQUIRED> -<!ELEMENT cache (properties)> -<!ATTLIST cache - enabled NMTOKEN #REQUIRED - class NMTOKEN #REQUIRED -> -<!ELEMENT query-handler (properties)> -<!ATTLIST query-handler class NMTOKEN #REQUIRED> -<!ELEMENT access-manager (properties)> -<!ATTLIST access-manager class NMTOKEN #REQUIRED> -<!ELEMENT lock-manager (time-out,persister)> -<!ELEMENT time-out (#PCDATA)> -<!ELEMENT persister (properties)> -<!ELEMENT properties (property+)> -<!ELEMENT property EMPTY></programlisting> - <section id="sect-Reference_Guide-JCR_configuration-Portal_configuration"> - <title><remark>BZ#812412 </remark>Portal configuration</title> - <para> - JCR services are registered in the Portal container. - </para> - <remark>NEEDINFO - FILE PATHS - The path needs to be updated with the equivalent path for JBoss Portal Platform instead of gatein, please see below para. New info required?</remark> - <para> - Below is an example configuration from the <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/jcr-configuration.xml</filename> file. - </para> - <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/jcr-configuration.xml" parse="text"/></programlisting> - <section id="sect-Reference_Guide-Portal_configuration-JCR_Configuration"> - <title>JCR Configuration</title> - <para> - The JCR Service can use multiple <emphasis>Repositories</emphasis> and each repository can have multiple <emphasis>Workspaces</emphasis>. - <remark>NEEDINFO - FILE PATHS - The path needs to be updated with the equivalent path for JBoss Portal Platform instead of gatein, please see below para. New info required?</remark> </para> - <para> - Configure the workspaces by locating the workspace you need to modify in <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.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> - <emphasis role="bold">M</emphasis> or <emphasis role="bold">MB</emphasis> for megabytes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">G</emphasis> or <emphasis role="bold">GB</emphasis> for gigabytes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">T</emphasis> or <emphasis role="bold">TB</emphasis> for terabytes. - </para> - </listitem> - <listitem> - <para> - Examples: 200K or 200KB; 4M or 4MB; 1.4G or 1.4GB; 10T or 10TB. - </para> - </listitem> - </itemizedlist> - - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Time formats:</term> - <listitem> - <para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">ms</emphasis> for milliseconds. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">s</emphasis> for seconds. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">m</emphasis> for minutes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">h</emphasis> for hours. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">d</emphasis> for days. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">w</emphasis> for weeks. - </para> - </listitem> - <listitem> - <para> - The default time format is seconds if no other format is specified. - </para> - </listitem> - <listitem> - <para> - Examples: 500ms or 500 milliseconds; 20, 20s or 20 seconds; 30m or 30 minutes; 12h or 12 hours; 5d or 5 days; 4w or 4 weeks. - </para> - </listitem> - </itemizedlist> - - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sect-Reference_Guide-Portal_configuration-Repository_service_configuration_JCR_repositories_configuration"> - <title>Repository service configuration (JCR repositories configuration)</title> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/orig.xml" parse="text"/></programlisting> - <note> - <title> - <parameter> session-max-age </parameter> - </title> - <para> - <emphasis>session-max-age</emphasis>: This parameter is not shown in the example 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> - <para> - <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> - <section id="sect-Reference_Guide-Portal_configuration-Workspace_configuration"> - <title>Workspace configuration:</title> - <variablelist> - <title/> - <varlistentry> - <term>name</term> - <listitem> - <para> - The name of a workspace. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>auto-init-root-nodetype</term> - <listitem> - <para> - DEPRECATED in JCR 1.9 (use initializer). The node type for root node initialization. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>container</term> - <listitem> - <para> - Workspace data container (physical storage) configuration. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>initializer</term> - <listitem> - <para> - Workspace initializer configuration. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>cache</term> - <listitem> - <para> - Workspace storage cache configuration. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>query-handler</term> - <listitem> - <para> - Query handler configuration. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>auto-init-permissions</term> - <listitem> - <para> - 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 and the type of permission. - </para> - <para> - For example, any read; <literal>:/admin read;</literal>:/admin add_node; <literal>:/admin set_property;</literal>:/admin remove means that users from group <literal>admin</literal> have all permissions and other users have only a 'read' permission. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sect-Reference_Guide-Portal_configuration-Workspace_data_container_configuration"> - <title>Workspace data container configuration:</title> - <variablelist> - <title/> - <varlistentry> - <term>class</term> - <listitem> - <para> - A workspace data container class name. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> - <para> - The list of properties (name-value pairs) for the concrete Workspace data container. - </para> - </listitem> - </varlistentry> - </variablelist> - <table id="tabl-Reference_Guide-Workspace_data_container_configuration-Parameter_Descriptions"> - <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 descendants on rename or not. It allows to increase performance on rename operation but in same time Observation is 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> - <variablelist> - <title/> - <varlistentry> - <term>value-storage</term> - <listitem> - <para> - The list of value storage plug-ins. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sect-Reference_Guide-Portal_configuration-Value_Storage_plugin_configuration_for_data_container"> - <title>Value Storage plug-in configuration (for data container):</title> - <note> - <para> - The value-storage element is optional. If you do not include it, the values will be stored as BLOBs inside the database. - </para> - </note> - <variablelist> - <title/> - <varlistentry> - <term>value-storage</term> - <listitem> - <para> - Optional value Storage plug-in definition. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>class</term> - <listitem> - <para> - A value storage plug-in class name (attribute). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> - <para> - The list of properties (name-value pairs) for a concrete Value Storage plug-in. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>filters</term> - <listitem> - <para> - The list of filters defining conditions when this plug-in is applicable. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sect-Reference_Guide-Portal_configuration-Initializer_configuration_optional"> - <title>Initializer configuration (optional):</title> - <variablelist> - <title/> - <varlistentry> - <term>class</term> - <listitem> - <para> - Initializer implementation class. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> - <para> - The list of properties (name-value pairs). Properties are supported. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>root-nodetype</term> - <listitem> - <para> - The node type for root node initialization. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>root-permissions</term> - <listitem> - <para> - Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities (user, group etc, see Organization service documentation for details) and the type of permission. For example any read; <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> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sect-Reference_Guide-Portal_configuration-Cache_configuration"> - <title>Cache configuration:</title> - <variablelist> - <title/> - <varlistentry> - <term>enabled</term> - <listitem> - <para> - If workspace cache is enabled or not. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>class</term> - <listitem> - <para> - Cache implementation class, optional from 1.9. Default value is. <literal>org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl</literal>. - </para> - <para> - Cache can be configured to use concrete implementation of WorkspaceStorageCache interface. JCR core has two implementation to use: - </para> - <itemizedlist> - <listitem> - <para> - LinkedWorkspaceStorageCacheImpl - default, with configurable read behavior and statistic. - </para> - </listitem> - <listitem> - <para> - WorkspaceStorageCacheImpl - pre 1.9, still can be used. - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> - <para> - The list of properties (name-value pairs) for Workspace cache. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>max-size</term> - <listitem> - <para> - Cache maximum size (maxSize prior to v.1.9). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>live-time</term> - <listitem> - <para> - Cached item live time (liveTime prior to v.1.9). - </para> - <para> - From 1.9 <literal>LinkedWorkspaceStorageCacheImpl</literal> supports additional optional parameters. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>statistic-period</term> - <listitem> - <para> - Period (time format) of cache statistic thread execution, 5 minutes by default. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>statistic-log</term> - <listitem> - <para> - If true cache statistic will be printed to default logger (log.info), false by default or not. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>statistic-clean</term> - <listitem> - <para> - If true cache statistic will be cleaned after was gathered, false by default or not. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>cleaner-period</term> - <listitem> - <para> - Period of the eldest items remover execution, 20 minutes by default. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>blocking-users-count</term> - <listitem> - <para> - Number of concurrent users allowed to read cache storage, 0 - unlimited by default. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sect-Reference_Guide-Portal_configuration-Query_Handler_configuration"> - <title>Query Handler configuration:</title> - <variablelist> - <title/> - <varlistentry> - <term>class</term> - <listitem> - <para> - A Query Handler class name. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> - <para> - The list of properties (name-value pairs) for a Query Handler (indexDir). - </para> - <para> - Properties and advanced features described in Search Configuration. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sect-Reference_Guide-Portal_configuration-Lock_Manager_configuration"> - <title>Lock Manager configuration:</title> - <variablelist> - <title/> - <varlistentry> - <term>time-out</term> - <listitem> - <para> - Time after which the unused global lock will be removed. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>persister</term> - <listitem> - <para> - A class for storing lock information for future use. For example, remove lock after jcr restart. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>path</term> - <listitem> - <para> - A lock folder. Each workspace has its own one. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-Multi_language_Support_the_JCR_RDB"> - <title>Multi-language Support</title> - <para> - Whenever a relational database is used to store multilingual text data in the eXo Java Content Repository the configuration must be adapted to support UTF-8 encoding. Dialect is automatically detected for certified database. You can still enforce it in case of failure, see below. - </para> - <para> - The following sections describe enabling UTF-8 support with various databases. - </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-Oracle"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-DB2"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-MySQL"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-PostgreSQL"/> - </para> - </listitem> - </itemizedlist> - <note> - <itemizedlist> - <listitem> - <remark>NEEDINFO - FILE PATHS - The path needs to be updated with the equivalent path for JBoss Portal Platform instead of gatein, please see below para. New info required?</remark> - <para> - The configuration file to be modified for these changes is <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. - </para> - </listitem> - <listitem> - <para> - The datasource <parameter>jdbcjcr</parameter> used in the following examples can be configured via the <literal>InitialContextInitializer</literal> component. - </para> - </listitem> - </itemizedlist> - </note> - <section id="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-Oracle"> - <title>Oracle</title> - <para> - In order to run multilanguage JCR on an Oracle backend Unicode encoding for characters set should be applied to the database. Other Oracle globalization parameters do not have any effect. The property to modify is <literal>NLS_CHARACTERSET</literal>. - </para> - <para> - The <literal>NLS_CHARACTERSET = AL32UTF8</literal> entry has been successfully tested with many European and Asian languages. - </para> - <para> - Example of database configuration: - </para> - <programlisting>NLS_LANGUAGE AMERICAN -NLS_TERRITORY AMERICA -NLS_CURRENCY $ -NLS_ISO_CURRENCY AMERICA -NLS_NUMERIC_CHARACTERS ., -NLS_CHARACTERSET AL32UTF8 -NLS_CALENDAR GREGORIAN -NLS_DATE_FORMAT DD-MON-RR -NLS_DATE_LANGUAGE AMERICAN -NLS_SORT BINARY -NLS_TIME_FORMAT HH.MI.SSXFF AM -NLS_TIMESTAMP_FORMAT DD-MON-RR HH.MI.SSXFF AM -NLS_TIME_TZ_FORMAT HH.MI.SSXFF AM TZR -NLS_TIMESTAMP_TZ_FORMAT DD-MON-RR HH.MI.SSXFF AM TZR -NLS_DUAL_CURRENCY $ -NLS_COMP BINARY -NLS_LENGTH_SEMANTICS BYTE -NLS_NCHAR_CONV_EXCP FALSE -NLS_NCHAR_CHARACTERSET AL16UTF16</programlisting> - <para> - Create database with Unicode encoding and use Oracle dialect for the Workspace Container: - </para> - <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default54.xml" parse="text"/></programlisting> - </section> - <section id="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-DB2"> - <title>DB2</title> - <para> - DB2 Universal Database (DB2 UDB) supports <ulink url="http://publib.boulder.ibm.com/infocenter/db2luw/v9/index.jsp?topic=/com.i...">UTF-8 and UTF-16/UCS-2</ulink>. When a Unicode database is created, <parameter>CHAR</parameter>, <parameter>VARCHAR</parameter> and <parameter>LONG VARCHAR</parameter> data are stored in UTF-8 form. - </para> - <para> - This enables JCR multi-lingual support. - </para> - <para> - Below is an example of creating a UTF-8 database using the <parameter>db2</parameter> dialect for a workspace container with DB2 version 9 and higher: - </para> - <programlisting>DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US -</programlisting> - <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default56.xml" parse="text"/></programlisting> - <note> - <para> - For DB2 version 8.<replaceable>x</replaceable> support change the property "dialect" to db2v8. - </para> - </note> - </section> - <section id="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-MySQL"> - <title>MySQL</title> - <para> - Using JCR with a MySQL-back end requires a special dialect <ulink url="http://jira.exoplatform.org/browse/JCR-375">MySQL-UTF8</ulink> to be used for internationalization support. - </para> - <para> - The database default charset should be <parameter>latin1</parameter> so as to use limited index space effectively (767 for <literal>InnoDB</literal>). - </para> - <para> - If the database default charset is multibyte, a JCR database initialization error is encountered concerning index creation failure. - </para> - <para> - JCR can work on any single byte default charset of database, with UTF8 supported by MySQL server. However it has only been tested using the <parameter>latin1</parameter> charset. - </para> - <para> - An example entry: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default57.xml" parse="text"/></programlisting> - </section> - <section id="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-PostgreSQL"> - <title>PostgreSQL</title> - <para> - Multilingual support can be enabled with a PostgreSQL-back end in <ulink url="http://www.postgresql.org/docs/8.3/interactive/charset.html">different ways</ulink>: - </para> - <orderedlist> - <listitem> - <para> - Using the locale features of the operating system to provide locale-specific collation order, number formatting, translated messages, and other aspects. - </para> - <para> - UTF-8 is widely used on Linux distributions by default, so it can be useful in such cases. - </para> - </listitem> - <listitem> - <para> - Providing a number of different character sets defined in the PostgreSQL server, including multiple-byte character sets, to support storing text any language, and providing character set translation between client and server. - </para> - <para> - Using UTF-8 database charset is recommended as it will allow any-to-any conversations and make this issue transparent for the JCR. - </para> - </listitem> - </orderedlist> - <para> - Example of a database with UTF-8 encoding using PgSQL dialect for the Workspace Container: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default58.xml" parse="text"/></programlisting> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-Search_Configuration"> - <title>Configuring Search</title> - <para> - The search function in JCR can be configured to perform in specific ways. This section will discuss configuring the search function to improve search performance and results. - </para> - <para> - Below is an example of the configuration file that governs search behaviors. Refer to <xref linkend="sect-Reference_Guide-Search_Configuration-Global_Search_Index"/> for how searching operates in JCR and information about customized searches. - </para> - <para> - The JCR index configuration file is located at <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. - </para> - <para> - A code example is included below with a list of the configuration parameters shown below that. - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default61.xml" parse="text"/></programlisting> - <para> - The table below outlines <emphasis role="bold">some</emphasis> of the Configuration Parameters available, their default setting, which version of eXo JCR they were implemented in and other useful information (further parameters are explained in <xref linkend="sect-Reference_Guide-JBoss_Cache_configuration-Indexer_lock_manager_and_data_container_configuration"/>): - </para> - <table id="tabl-Reference_Guide-Search_Configuration-Configuration_parameters"> - <title>Configuration parameters</title> - <tgroup cols="4"> - <colspec colname="1" colwidth="90pt"/> - <colspec colname="2" colwidth="90pt"/> - <colspec colname="3" colwidth="150pt"/> - <colspec colname="4" colwidth="50pt"/> - <thead> - <row> - <entry> - <para> - Parameter - </para> - </entry> - <entry> - <para> - Default - </para> - </entry> - <entry> - <para> - Description - </para> - </entry> - <entry> Implemented in Version </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para> - index-dir - </para> - </entry> - <entry> - <para> - none - </para> - </entry> - <entry> - <para> - The location of the index directory. This parameter is mandatory. It is called "<literal>indexDir</literal>" in versions prior to eXo JCR version 1.9. - </para> - </entry> - <entry> 1.0 </entry> - </row> - <row> - <entry> - <para> - use-compoundfile - </para> - </entry> - <entry> - <para> - true - </para> - </entry> - <entry> - <para> - Advises lucene to use compound files for the index files. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - min-merge-docs - </para> - </entry> - <entry> - <para> - 100 - </para> - </entry> - <entry> - <para> - The minimum number of nodes in an index until segments are merged. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - volatile-idle-time - </para> - </entry> - <entry> 3 </entry> - <entry> - <para> - Idle time in seconds until the volatile index part is moved to a persistent index even though <literal>minMergeDocs</literal> is not reached. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - max-merge-docs - </para> - </entry> - <entry> - <para> - Integer.MAX_VALUE - </para> - </entry> - <entry> - <para> - The maximum number of nodes in segments that will be merged. The default value changed to <literal>Integer.MAX_VALUE</literal> in eXo JCR version 1.9. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - merge-factor - </para> - </entry> - <entry> - <para> - 10 - </para> - </entry> - <entry> - <para> - Determines how often segment indices are merged. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - max-field-length - </para> - </entry> - <entry> - <para> - 10000 - </para> - </entry> - <entry> - <para> - The number of words that are full-text indexed at most per property. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - cache-size - </para> - </entry> - <entry> - <para> - 1000 - </para> - </entry> - <entry> - <para> - Size of the document number cache. This cache maps UUID to lucene document numbers - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - force-consistencycheck - </para> - </entry> - <entry> - <para> - false - </para> - </entry> - <entry> - <para> - Runs a consistency check on every start up. If false, a consistency check is only performed when the search index detects a prior forced shutdown. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - auto-repair - </para> - </entry> - <entry> - <para> - true - </para> - </entry> - <entry> - <para> - Errors detected by a consistency check are automatically repaired. If false, errors are only written to the log. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> query-class </entry> - <entry> QueryImpl </entry> - <entry> - <para> - Classname that implements the javax.jcr.query.Query interface. - </para> - <para> - This class must also extend from the class: <literal>org.exoplatform.services.jcr.impl.core. query.AbstractQueryImpl</literal>. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - document-order - </para> - </entry> - <entry> - <para> - true - </para> - </entry> - <entry> - <para> - If true and the query does not contain an 'order by' clause, result nodes will be in document order. For better performance set to 'false' when queries return many nodes. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - result-fetch-size - </para> - </entry> - <entry> - <para> - Integer.MAX_VALUE - </para> - </entry> - <entry> - <para> - The number of results when a query is executed. Default value: <literal>Integer.MAX_VALUE</literal>. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - excerptprovider-class - </para> - </entry> - <entry> - <para> - DefaultXMLExcerpt - </para> - </entry> - <entry> - <para> - The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.ExcerptProvider</literal>. - </para> - <para> - This should be used for the <literal>rep:excerpt()</literal> function in a query. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - support-highlighting - </para> - </entry> - <entry> - <para> - false - </para> - </entry> - <entry> - <para> - If set to true additional information is stored in the index to support highlighting using the <literal>rep:excerpt()</literal> function. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - synonymprovider-class - </para> - </entry> - <entry> - <para> - none - </para> - </entry> - <entry> - <para> - The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.SynonymProvider</literal>. - </para> - <para> - The default value is null. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - synonymprovider-config-path - </para> - </entry> - <entry> - <para> - none - </para> - </entry> - <entry> - <para> - The path to the synonym provider configuration file. This path is interpreted relative to the path parameter. If there is a path element inside the <literal>SearchIndex</literal> element, then this path is interpreted relative to the root path of the path. Whether this parameter is mandatory depends on the synonym provider implementation. The default value is null. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - indexing-configuration-path - </para> - </entry> - <entry> - <para> - none - </para> - </entry> - <entry> - <para> - The path to the indexing configuration file. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - indexing-configuration-class - </para> - </entry> - <entry> - <para> - IndexingConfigurationImpl - </para> - </entry> - <entry> - <para> - The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.IndexingConfiguration</literal>. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - force-consistencycheck - </para> - </entry> - <entry> - <para> - false - </para> - </entry> - <entry> - <para> - If set to true a consistency check is performed depending on the parameter <literal>forceConsistencyCheck</literal>. If set to false no consistency check is performed on start up, even if a redo log had been applied. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - spellchecker-class - </para> - </entry> - <entry> - <para> - none - </para> - </entry> - <entry> - <para> - The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.SpellChecker</literal>. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - errorlog-size - </para> - </entry> - <entry> - <para> - 50(KB) - </para> - </entry> - <entry> - <para> - The default size of error log file in KB. - </para> - </entry> - <entry> 1.9 </entry> - </row> - <row> - <entry> - <para> - upgrade-index - </para> - </entry> - <entry> - <para> - false - </para> - </entry> - <entry> - <para> - Allows JCR to convert an existing index into the new format. It is also possible to set this property via system property. - </para> - <para> - Indexes prior to eXo JCR 1.12 will not run with eXo JCR 1.12. You must run an automatic migration. - </para> - <para> - Start eXo JCR with: - </para> - <programlisting><command> -Dupgrade-index=true</command></programlisting> - <para> - The old index format is then converted in the new index format. After the conversion the new format is used. - </para> - <para> - On subsequent starts this option is no longer needed. The old index is replaced and a back conversion is not possible - </para> - <para> - It is recommended that a backup of the index be made before conversion. (Only for migrations from JCR 1.9 and later.) - </para> - </entry> - <entry> 1.12 </entry> - </row> - <row> - <entry> - <para> - analyzer - </para> - </entry> - <entry> - <para> - org.apache.lucene.analysis. standard.StandardAnalyzer - </para> - </entry> - <entry> - <para> - Class name of a lucene analyzer to use for full-text indexing of text. - </para> - </entry> - <entry> 1.12 </entry> - </row> - </tbody> - </tgroup> - </table> - <section id="sect-Reference_Guide-Search_Configuration-Global_Search_Index"> - <title>Global Search Index</title> - <para> - By default eXo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content - </para> - <example> - <title>Standard Analyzed Filters</title> - <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default62.java" parse="text"/></programlisting> - <para> - Comment #1: The first filter (StandardFilter) removes possessive apostrophes (<emphasis role="bold">'s</emphasis>) from the end of words and removes periods (<emphasis role="bold">.</emphasis>) from acronyms. - </para> - <para> - Comment #2: The second filter (LowerCaseFilter) normalizes token text to lower case. - </para> - <para> - Comment #3: The last filter (StopFilter) removes stop words from a token stream. The stop set is defined in the analyzer. - </para> - </example> - <para> - The global search index is configured in the <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the "query-handler" tag. - </para> - <programlisting language="XML" role="XML"><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> -</programlisting> - <para> - The same analyzer should always be used for indexing and for querying in lucene otherwise results may be unpredictable. eXo JCR does this automatically. The StandardAnalyzer (configured by default) can, however, be replaced with another. - </para> - <para> - A customized QueryHandler can also be easily created. - </para> - <formalpara id="form-Reference_Guide-Global_Search_Index-Customized_Search_Indexes_and_Analyzers"> - <title>Customized Search Indexes and Analyzers</title> - <para> - By default Exo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content: - </para> - </formalpara> - <programlisting language="Java" role="Java">public TokenStream tokenStream(String fieldName, Reader reader) { - StandardTokenizer tokenStream = new StandardTokenizer(reader, replaceInvalidAcronym); - tokenStream.setMaxTokenLength(maxTokenLength); - TokenStream result = new StandardFilter(tokenStream); - result = new LowerCaseFilter(result); - result = new StopFilter(result, stopSet); - return result; - }</programlisting> - <itemizedlist> - <listitem> - <para> - The first one (StandardFilter) removes 's (as 's in "Peter's") from the end of words and removes dots from acronyms. - </para> - </listitem> - <listitem> - <para> - The second one (LowerCaseFilter) normalizes token text to lower case. - </para> - </listitem> - <listitem> - <para> - The last one (StopFilter) removes stop words from a token stream. The stop set is defined in the analyzer. - </para> - </listitem> - </itemizedlist> - <para> - Additional filters can be used in specific cases. The <phrase>ISOLatin1AccentFilter</phrase> filter, for example, which replaces accented characters in the ISO Latin 1 character set (ISO-8859-1) by their unaccented equivalents. - </para> - <para> - The <phrase>ISOLatin1AccentFilter</phrase> is not present in the current lucene version used by eXo. - </para> - <para> - In order to use a different filter, a new analyzer must be created, as well as new search index to use the analyzer. These are packaged into a jar file, which is then deployed with the application. - </para> - <procedure id="proc-Reference_Guide-Global_Search_Index-Create_a_new_filter_analyzer_and_search_index"> - <title>Create a new filter, analyzer and search index</title> - <step> - <para> - Create a new filter with the method: - </para> - <programlisting language="Java" role="JAVA">public final Token next(final Token reusableToken) throws java.io.IOException -</programlisting> - <para> - This defines how characters are read and used by the filter. - </para> - </step> - <step> - <para> - Create the analyzer. - </para> - <para> - The analyzer must extend <literal>org.apache.lucene.analysis.standard.StandardAnalyzer</literal> and overload the method. - </para> - <para> - Use the following to use new filters. - </para> - <programlisting language="Java" role="JAVA">public TokenStream tokenStream(String fieldName, Reader reader) -</programlisting> - </step> - <step> - <para> - To create the new search index, extend <literal>org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex</literal> and write the constructor to set the correct analyzer. - </para> - <para> - Use the method below to return your analyzer: - </para> - <programlisting language="Java" role="JAVA">public Analyzer getAnalyzer() { -return MyAnalyzer; -} -</programlisting> - </step> - </procedure> - <note> - <para> - In eXo JCR version 1.12 (and later) the analyzer can be directly set in the configuration. For users with this version the creation of a new SearchIndex for new analyzers is redundant. - </para> - </note> - <para> - To configure an application to use a new <literal>SearchIndex</literal>, replace the following code: - </para> - <programlisting language="XML" role="XML"><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - -</programlisting> - <para> - in <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> with the new class: - </para> - <programlisting language="XML" role="XML"><query-handler class="mypackage.indexation.MySearchIndex> - -</programlisting> - <para> - To configure an application to use a new analyzer, add the <parameter>analyzer</parameter> parameter to each query-handler configuration in <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default69.xml" parse="text"/></programlisting> - <para> - The new <literal>SearchIndex</literal> will start to index contents with the specified filters when the JCR is next started. - </para> - </section> - <section id="sect-Reference_Guide-Search_Configuration-IndexingConfiguration"> - <title>IndexingConfiguration</title> - <para> - From version 1.9, the default search index implementation in JCR allows user control over which properties of a node are indexed. Different analyzers can also be set for different nodes. - </para> - <para> - The configuration parameter is called <literal>indexingConfiguration</literal> and is not set by default. This means all properties of a node are indexed. - </para> - <para> - To configure the indexing behavior add a parameter to the query-handler element in your configuration file. - </para> - <programlisting language="XML" role="XML"><param name="indexing-configuration-path" value="/indexing_configuration.xml"/> - -</programlisting> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Node_Scope_Limit"> - <title>Node Scope Limit</title> - <para> - The node scope can be limited so that only certain properties of a node type are indexed. This can optimize the index size. - </para> - </formalpara> - <para> - With the configuration below only properties named <parameter>Text</parameter> are indexed for <parameter>nt:unstructured</parameter> node types. This configuration also applies to all nodes whose type extends from <parameter>nt:unstructured</parameter>. - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default71.xml" parse="text"/></programlisting> - <note> - <title>Namespace Prefixes</title> - <para> - The <phrase>namespace prefixes</phrase> must be declared throughout the XML file in the configuration element that is being used. - </para> - </note> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Indexing_Boost_Value"> - <title>Indexing Boost Value</title> - <para> - It is also possible to configure a <phrase>boost value</phrase> for the nodes that match the index rule. The default boost value is 1.0. Higher boost values (a reasonable range is 1.0 - 5.0) will yield a higher score value and appear as more relevant. - </para> - </formalpara> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default72.xml" parse="text"/></programlisting> - <para> - If you do not wish to boost the complete node, but only certain properties, you can also provide a boost value for the listed properties: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default73.xml" parse="text"/></programlisting> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Conditional_Index_Rules"> - <title>Conditional Index Rules</title> - <para> - You may also add a <phrase>condition</phrase> to the index rule and have multiple rules with the same nodeType. The first index rule that matches will apply and all remaining ones are ignored: - </para> - </formalpara> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default74.xml" parse="text"/></programlisting> - <para> - In the above example the first rule only applies if the <parameter>nt:unstructured</parameter> node has a priority property with a value <parameter>high</parameter>. The condition syntax only supports the equals operator and a string literal. - </para> - <para> - Properties may also be referenced on the condition that are not on the current node: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default75.xml" parse="text"/></programlisting> - <para> - The indexing configuration allows the type of a node in the condition to be specified. Please note however that the type match must be exact. It does not consider sub types of the specified node type. - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default76.xml" parse="text"/></programlisting> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Exclusion_from_the_Node_Scope_Index"> - <title>Exclusion from the Node Scope Index</title> - <para> - All configured properties are full-text indexed by default (if they are of type STRING and included in the node scope index). - </para> - </formalpara> - <para> - A node scope search normally finds all nodes of an index. That is to say; <literal>jcr:contains(., 'foo')</literal> returns all nodes that have a string property containing the word '<replaceable>foo</replaceable>'. - </para> - <para> - Properties can be explicitly excluded from the node scope index with: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default77.xml" parse="text"/></programlisting> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Index_Aggregates"> - <title>Index Aggregates</title> - <para> - Sometimes it is useful to include the contents of descendant nodes into a single node to more easily search on content that is scattered across multiple nodes. - </para> - </formalpara> - <para> - JCR allows the definition of index aggregates based on relative path patterns and primary node types. - </para> - <para> - The following example creates an index aggregate on <literal>nt:file</literal> that includes the content of the jcr:content node: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default78.xml" parse="text"/></programlisting> - <para> - Included nodes can also be restricted to a certain type: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default79.xml" parse="text"/></programlisting> - <para> - The <emphasis role="bold">*</emphasis> wild-card can be used to match all child nodes: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default80.xml" parse="text"/></programlisting> - <para> - Nodes to a certain depth below the current node can be included by adding multiple include elements. The <parameter>nt:file</parameter> node may contain a complete XML document under jcr:content for example: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default81.xml" parse="text"/></programlisting> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Property_Level_Analyzers"> - <title>Property-Level Analyzers</title> - <para> - How a property has to be analyzed can be defined in the following configuration section. If there is an analyzer configuration for a property, this analyzer is used for indexing and searching of this property. For example: - </para> - </formalpara> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default82.xml" parse="text"/></programlisting> - <para> - The configuration above sets lucene <emphasis role="bold">KeywordAnalyzer</emphasis> to index and search the property "<replaceable>mytext</replaceable>" across the entire workspace while the "<replaceable>mytext2</replaceable>" property is searched with the <emphasis role="bold">WhitespaceAnalyzer</emphasis>. - </para> - <para> - The <emphasis role="bold">WhitespaceAnalyzer</emphasis> tokenizes a property, the <emphasis role="bold">KeywordAnalyzer</emphasis> takes the property as a whole. - </para> - <para> - Using different analyzers for different languages can be particularly useful. - </para> - <formalpara id="form-Reference_Guide-IndexingConfiguration-Characteristics_of_Node_Scope_Searches"> - <title>Characteristics of Node Scope Searches</title> - <para> - Unexpected behavior may be encountered when using analyzers to search within a <emphasis>property</emphasis> compared to searching within a <emphasis>node scope</emphasis>. This is because the node scope always uses the global analyzer. - </para> - </formalpara> - <para> - For example: the property "<parameter>mytext</parameter>" contains the text; "<emphasis>testing my analyzers</emphasis>" but no analyzers have been configured for this property (and the default analyzer in SearchIndex has not been changed). - </para> - <para> - If the query is: - </para> - <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(mytext,'analyzer')]" -</programlisting> - <para> - The <literal>xpath</literal> does not return a result in the node with the property above and default analyzers. - </para> - <para> - Also, if a search is done on the node scope as follows: - </para> - <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(.,'analyzer')]" -</programlisting> - <para> - No result will be returned. - </para> - <para> - Only specific analyzers can be set on a node property, and the node scope indexing and analyzing is always done with the globally defined analyzer in the SearchIndex element. - </para> - <para> - If the analyzer used to index the "mytext" property above is changed to: - </para> - <programlisting language="XML" role="XML"><analyzer class="org.apache.lucene.analysis.Analyzer.GermanAnalyzer"> -<property>mytext</property> -</analyzer> -</programlisting> - <para> - The search below would return a result because of the word stemming (analyzers - analyzer). - </para> - <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(mytext,'analyzer')]" -</programlisting> - <para> - The second search in the example: - </para> - <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(.,'analyzer')]" -</programlisting> - <para> - Would still not give a result, since the node scope is indexed with the global analyzer, which in this case does not take into account any word stemming. - </para> - <para> - Be aware that when using analyzers for specific properties, a result may be found in a property for certain search text, but the same search text in the node scope of the property may not find a result. - </para> - <note> - <para> - Both index rules and index aggregates influence how content is indexed in JCR. If the configuration is changed, the existing content is not automatically re-indexed according to the new rules. - </para> - <para> - Content must be manually re-indexed when the configuration is changed. - </para> - </note> - </section> - <section id="sect-Reference_Guide-Search_Configuration-Advanced_features"> - <title>Advanced features</title> - <para> - eXo JCR supports some advanced features, which are not specified in JSR 170: - </para> - <itemizedlist> - <listitem> - <para> - Get a text excerpt with <emphasis role="bold">highlighted words</emphasis> that matches the query: <xref linkend="sect-Reference_Guide-Highlighting-DefaultXMLExcerpt"/>>. - </para> - </listitem> - <listitem> - <para> - Search a term and its <emphasis role="bold">synonyms</emphasis>: <xref linkend="sect-Reference_Guide-Searching_Repository_Content-SynonymSearch"/>. - </para> - </listitem> - <listitem> - <para> - Search <emphasis role="bold">similar</emphasis> nodes: <xref linkend="sect-Reference_Guide-Searching_Repository_Content-Similarity"/>. - </para> - </listitem> - <listitem> - <para> - Check <emphasis role="bold">spelling</emphasis> of a full text query statement: <xref linkend="sect-Reference_Guide-Searching_Repository_Content-SpellChecker"/>. - </para> - </listitem> - <listitem> - <para> - Define index <emphasis role="bold">aggregates and rules</emphasis>: IndexingConfiguration. - </para> - </listitem> - </itemizedlist> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-JDBC_Data_Container_Config"> - <title>Configuring the JDBC Data Container</title> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Introduction"> - <title>Introduction</title> - <para> - eXo JCR persistent data container can work in two configuration modes: - </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> - <para> - Currently the data container is tested with the following RDBMS: - </para> - <table id="tabl-Reference_Guide-Introduction-Supported-databases"> - <title>Supported databases</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Database </entry> - <entry> Driver Version </entry> - </row> - </thead> - <tbody> - <row> - <entry> IBM DB2 9.7 (FP5) </entry> - <entry> IBM DB2 JDBC Universal Driver Architecture 4.13.80 </entry> - </row> - <row> - <entry> Oracle 11g R1 (11.1.0.7.0) </entry> - <entry> Oracle JDBC Driver 11.1.0.7 </entry> - </row> - <row> - <entry> Oracle 11g R1 RAC (11.1.0.7.0) </entry> - <entry> Oracle JDBC Driver 11.1.0.7 </entry> - </row> - <row> - <entry> Oracle 11g R2 (11.2.0.3.0) </entry> - <entry> Oracle JDBC Driver v11.2.0.3.0 </entry> - </row> - <row> - <entry> Oracle 11g R2 RAC (11.2.0.3.0) </entry> - <entry> Oracle JDBC Driver v11.2.0.3.0 </entry> - </row> - <row> - <entry> MySQL 5.1 </entry> - <entry> MySQL Connector/J 5.1.21 </entry> - </row> - <row> - <entry> MySQL 5.5 </entry> - <entry> MySQL Connector/J 5.1.21 </entry> - </row> - <row> - <entry> Microsoft SQL Server 2008 </entry> - <entry> Microsoft SQL Server JDBC Driver 3.0.1301.101, Microsoft SQL Server JDBC Driver 4.0.2206.100 </entry> - </row> - <row> - <entry> Microsoft SQL Server 2008 R2 </entry> - <entry> Microsoft SQL Server JDBC Driver 3.0.1301.101, Microsoft SQL Server JDBC Driver 4.0.2206.100 </entry> - </row> - <row> - <entry> PostgreSQL 8.4.8 </entry> - <entry> JDBC4 Postgresql Driver, Version 8.4-703 </entry> - </row> - <row> - <entry> PostgreSQL 9.1.0 </entry> - <entry> JDBC4 Postgresql Driver, Version 9.1-903 </entry> - </row> - <row> - <entry> Sybase ASE 15.7 </entry> - <entry> Sybase jConnect JDBC driver v7 </entry> - </row> - </tbody> - </tgroup> - </table> - <note> - <title>Isolation Levels</title> - <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">here.</ulink> - </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> - <remark>NEEDINFO - FILE PATHS - The path needs to be updated with the equivalent path for JBoss Portal Platform instead of gatein, please see below para. New info required?</remark> - <para> - You can find SQL-scripts in <filename>conf/storage/</filename> directory of the <filename><replaceable>JPP_HOME</replaceable>/modules/org/gatein/lib/main/exo.jcr.component.core-&JCR_VERSION;.jar</filename> file . - </para> - <para> - The following tables show the correspondence between the scripts and databases: - </para> - <table id="tabl-Reference_Guide-Introduction-Single_database"> - <title>Single-database</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Database </entry> - <entry> Script </entry> - </row> - </thead> - <tbody> - <row> - <entry> MySQL DB </entry> - <entry> - <filename>jcr-sjdbc.mysql.sql</filename> - </entry> - </row> - <row> - <entry> MySQL DB with utf-8 </entry> - <entry> - <filename>jcr-sjdbc.mysql-utf8.sql</filename> - </entry> - </row> - <row> - <entry> PostgresSQL </entry> - <entry> - <filename>jcr-sjdbc.pqsql.sql</filename> - </entry> - </row> - <row> - <entry> Oracle DB </entry> - <entry> - <filename>jcr-sjdbc.ora.sql</filename> - </entry> - </row> - <row> - <entry> DB2 9.7 </entry> - <entry> - <filename>jcr-sjdbc.db2.sql</filename> - </entry> - </row> - <row> - <entry> MS SQL Server </entry> - <entry> - <filename>jcr-sjdbc.mssql.sql</filename> - </entry> - </row> - <row> - <entry> Sybase </entry> - <entry> - <filename>jcr-sjdbc.sybase.sql</filename> - </entry> - </row> - <row> - <entry> HSQLDB </entry> - <entry> - <filename>jcr-sjdbc.sql</filename> - </entry> - </row> - </tbody> - </tgroup> - </table> - <table id="tabl-Reference_Guide-Introduction-Multi_database"> - <title>Multi-database</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Database </entry> - <entry> Script </entry> - </row> - </thead> - <tbody> - <row> - <entry> MySQL DB </entry> - <entry> - <filename>jcr-mjdbc.mysql.sql</filename> - </entry> - </row> - <row> - <entry> MySQL DB with utf-8 </entry> - <entry> - <filename>jcr-mjdbc.mysql-utf8.sql</filename> - </entry> - </row> - <row> - <entry> PostgresSQL </entry> - <entry> - <filename>jcr-mjdbc.pqsql.sql</filename> - </entry> - </row> - <row> - <entry> Oracle DB </entry> - <entry> - <filename>jcr-mjdbc.ora.sql</filename> - </entry> - </row> - <row> - <entry> DB2 9.7 </entry> - <entry> - <filename>jcr-mjdbc.db2.sql</filename> - </entry> - </row> - <row> - <entry> MS SQL Server </entry> - <entry> - <filename>jcr-mjdbc.mssql.sql</filename> - </entry> - </row> - <row> - <entry> Sybase </entry> - <entry> - <filename>jcr-mjdbc.sybase.sql</filename> - </entry> - </row> - <row> - <entry> HSQLDB </entry> - <entry> - <filename>jcr-mjdbc.sql</filename> - </entry> - </row> - </tbody> - </tgroup> - </table> - <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-&JCR_VERSION;.jar</package> or source-distribution of eXo JCR implementation. - </para> - <example id="exam-Reference_Guide-Introduction-Example_Parameter"> - <title>Example Parameter</title> - <programlisting><code>jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8</code></programlisting> - </example> - <para> - The configuration files are located in service jars <filename>/conf/portal/configuration.xml</filename> (eXo services including JCR Repository Service) and <filename>exo-jcr-config.xml</filename> (repositories configuration) by default. In JBoss Portal Platform, the JCR is configured in portal web application <filename>portal/WEB-INF/conf/jcr/jcr-configuration.xml</filename> (JCR Repository Service and related services) and <filename>repository-configuration.xml</filename> (repositories configuration). - </para> - <para> - Read more about <xref linkend="chap-Reference_Guide-JCR_configuration"/>. - </para> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Multi_database_Configuration"> - <title>Multi-database Configuration</title> - <para> - You need to configure each workspace in a repository as part of multi-database configuration. Databases may reside on remote servers as required. - </para> - <procedure> - <title/> - <step> - <para> - Configure the data containers in the <literal>org.exoplatform.services.naming.InitialContextInitializer</literal> service. It's the JNDI context initializer which registers (binds) naming resources (DataSources) for data containers. - </para> - <para> - For example (two data containers <parameter>jdbcjcr</parameter> - local HSQLDB, <parameter>jdbcjcr1</parameter> - remote MySQL): - </para> - <programlisting language="XML" role="XML"> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/example-1.xml" parse="text"/></programlisting> - <substeps> - <step> - <para> - Configure the database connection parameters: - </para> - <itemizedlist> - <listitem> - <para> - <parameter>driverClassName</parameter>, e.g. "org.hsqldb.jdbcDriver", "com.mysql.jdbc.Driver", "org.postgresql.Driver" - </para> - </listitem> - <listitem> - <para> - <parameter>url</parameter>, e.g. "jdbc:hsqldb:file:target/temp/data/portal", "jdbc:mysql://exoua.dnsalias.net/jcr" - </para> - </listitem> - <listitem> - <para> - <parameter>username</parameter>, e.g. "sa", "exoadmin" - </para> - </listitem> - <listitem> - <para> - <parameter>password</parameter>, e.g. "", "exo12321" - </para> - </listitem> - </itemizedlist> - </step> - </substeps> - <para> - There can be connection pool configuration parameters (org.apache.commons.dbcp.BasicDataSourceFactory): - </para> - <itemizedlist> - <listitem> - <para> - <parameter>maxActive</parameter>, e.g. 50 - </para> - </listitem> - <listitem> - <para> - <parameter>maxIdle</parameter>, e.g. 5 - </para> - </listitem> - <listitem> - <para> - <parameter>initialSize</parameter>, e.g. 5 - </para> - </listitem> - <listitem> - <para> - and other according to <ulink url="http://jakarta.apache.org/commons/dbcp/configuration.html">Apache DBCP configuration</ulink> - </para> - </listitem> - </itemizedlist> - </step> - <step> - <para> - Configure the repository service. Each workspace will be configured for its own data container. - </para> - <para> - For example (two workspaces <parameter>ws</parameter> - jdbcjcr, <parameter>ws1</parameter> - jdbcjcr1): - </para> - <programlisting language="XML" role="XML"> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/example-2.xml" parse="text"/></programlisting> - <itemizedlist> - <listitem> - <para> - <parameter>source-name</parameter>: A javax.sql.DataSource name configured in InitialContextInitializer component (was <parameter>sourceName</parameter> prior JCR 1.9); - </para> - </listitem> - <listitem> - <para> - <parameter>dialect</parameter>: A database dialect, one of <literal>hsqldb</literal>, <literal>mysql</literal>, <literal>mysql-utf8</literal>, <literal>pgsql</literal>, <literal>oracle</literal>, <literal>oracle-oci</literal>, <literal>mssql</literal>, <literal>sybase</literal>, <literal>derby</literal>, <literal>db2</literal>, <literal>db2v8</literal> or <literal>auto</literal> for dialect autodetection; - </para> - </listitem> - <listitem> - <para> - <parameter>multi-db</parameter>: Enable multi-database container with this parameter (set value "true"); - </para> - </listitem> - <listitem> - <para> - <parameter>max-buffer-size: A</parameter> a threshold (in bytes) after which a <literal>javax.jcr.Value</literal> content will be swapped to a file in a temporary storage. A swap for pending changes, for example. - </para> - </listitem> - <listitem> - <para> - <parameter>swap-directory</parameter>: A path in the file system used to swap the pending changes. - </para> - </listitem> - </itemizedlist> - </step> - </procedure> - <para> - This procedure configures two workspace which will be persistent in two different databases (<emphasis>ws</emphasis> in HSQLDB and <emphasis>ws1</emphasis> in MySQL). - </para> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Single_database_Configuration"> - <title>Single-database Configuration</title> - <para> - Configuring a single-database data container is easier than configuring a multi-database data container as only one naming resource must be configured. - </para> - <example id="exam-Reference_Guide-Single_database_Configuration-jdbcjcr_Data_Container"> - <title>jdbcjcr Data Container</title> - <programlisting language="XML"> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/example-3.xml" parse="text"/></programlisting> - </example> - <para> - Configure repository workspaces with this one database. The <parameter>multi-db</parameter> parameter must be set as <literal>false</literal>. - </para> - <para> - For example (two workspaces <parameter>ws</parameter> - <literal>jdbcjcr</literal>, <parameter>ws1</parameter> - <literal>jdbcjcr</literal>): - </para> - <example id="exam-Reference_Guide-Single_database_Configuration-Example"> - <title>Example</title> - <programlisting language="XML" role="XML"> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/example-4.xml" parse="text"/></programlisting> - </example> - <para> - This configures two persistent workspaces in one database (PostgreSQL). - </para> - <section id="sect-Reference_Guide-Single_database_Configuration-Configuration_without_DataSource"> - <title>Configuration without DataSource</title> - <para> - It is possible to configure the repository without binding <literal>javax.sql.DataSource</literal> in the JNDI service if you have a dedicated JDBC driver implementation with special features like XA transactions, statements/connections pooling etc: - </para> - <procedure> - <title/> - <step> - <para> - Remove the configuration in <literal>InitialContextInitializer</literal> for your database and configure a new one directly in the workspace container. - </para> - </step> - <step> - <para> - Remove parameter <parameter>source-name</parameter> and add next lines instead. Describe your values for a JDBC driver, database URL and username. - </para> - </step> - </procedure> - <warning> - <title>Connection Pooling</title> - <para> - Ensure the JDBC driver provides connection pooling. Connection pooling is strongly recommended for use with the JCR to prevent a database overload. - </para> - </warning> - <programlisting language="XML" role="XML"><workspace name="ws" auto-init-root-nodetype="nt:unstructured"> - <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> - <properties> - <property name="dialect" value="hsqldb"/> - <property name="driverliteral" value="org.hsqldb.jdbcDriver"/> - <property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/> - <property name="username" value="su"/> - <property name="password" value=""/> - ......</programlisting> - </section> - <section id="sect-Reference_Guide-Single_database_Configuration-Dynamic_Workspace_Creation"> - <title>Dynamic Workspace Creation</title> - <para> - Workspaces can be added dynamically during runtime. - </para> - <para> - This can be performed in two steps: - </para> - <procedure> - <title/> - <step> - <para> - <literal>ManageableRepository.configWorkspace(WorkspaceEntry wsConfig)</literal>: Register a new configuration in RepositoryContainer and create a WorkspaceContainer. - </para> - </step> - <step> - <para> - <literal>ManageableRepository.createWorkspace(String workspaceName)</literal>: Creation a new workspace. - </para> - </step> - </procedure> - </section> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Simple_and_Complex_queries"> - <title>Simple and Complex queries</title> - <para> - eXo JCR provides two ways to interact with the database; - </para> - <variablelist> - <title/> - <varlistentry> - <term> - <literal>JDBCStorageConnection</literal> - </term> - <listitem> - <para> - Which uses simple queries. Simple queries do not use sub queries, left or right joins. They are implemented in such a way as to support as many database dialects as possible. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>CQJDBCStorageConection</literal> - </term> - <listitem> - <para> - Which uses complex queries. Complex queries are optimized to reduce the number of database calls. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Simple queries will be used if you chose <literal>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</literal>: - </para> - <programlisting language="XML" role="XML"><workspaces> - <workspace name="ws" auto-init-root-nodetype="nt:unstructured"> - <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> - ... - </workspace> -</worksapces> -</programlisting> - <para> - Complex queries will be used if you chose <literal>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</literal>: - </para> - <programlisting language="XML" role="XML"><workspaces> - <workspace name="ws" auto-init-root-nodetype="nt:unstructured"> - <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"> - ... - </workspace> -</worksapces></programlisting> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Force_Query_Hints"> - <title>Force Query Hints</title> - <para> - Some databases, such as Oracle and MySQL, support hints to increase query performance. The eXo JCR has separate Complex Query implementations for the Orcale database dialect, which uses query hints to increase performance for few important queries. - </para> - <para> - To enable this option, use the following configuration property: - </para> - <programlisting language="XML" role="XML"><workspace name="ws" auto-init-root-nodetype="nt:unstructured"> - <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> - <properties> - <property name="dialect" value="oracle"/> - <property name="force.query.hints" value="true" /> - ......</programlisting> - <para> - Query hints are only used for Complex Queries with the Oracle dialect. For all other dialects this parameter is ignored. - </para> - </section> - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Notes_for_Microsoft_Windows_users"> - <title>Notes for Microsoft Windows users</title> - <para> - The current configuration of eXo JCR uses <ulink url="http://commons.apache.org/dbcp/">Apache DBCP</ulink> connection pool (<literal>org.apache.commons.dbcp.BasicDataSourceFactory</literal>). - </para> - <para> - It is possible to set a high value for the <parameter>maxActive</parameter> parameter in the <filename>configuration.xml</filename> file. This creates a high use of TCP/IP ports from a client machine inside the pool (the JDBC driver, for example). As a result, the data container can throw exceptions like "<emphasis>Address already in use</emphasis>". - </para> - <para> - To solve this problem, you must configure the client's machine networking software to use shorter timeouts for open TCP/IP ports. - </para> - <para> - This is done by editing two registry keys within the <parameter>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters</parameter> node. Both of these keys are unset by default. To set the keys as required: - </para> - <procedure> - <title/> - <step> - <para> - Set the <parameter>MaxUserPort</parameter> registry key to <parameter>=dword:00001b58</parameter>. This sets the maximum of open ports to 7000 or higher (the default is 5000). - </para> - </step> - <step> - <para> - Set <parameter>TcpTimedWaitDelay</parameter> to <parameter>=dword:0000001e</parameter>. This sets <parameter>TIME_WAIT</parameter> parameter to 30 seconds (the default is 240). - </para> - </step> - </procedure> - <example id="exam-Reference_Guide-Notes_for_Microsoft_Windows_users-Sample_Registry_File"> - <title>Sample Registry File</title> - <programlisting>Windows Registry Editor Version 5.00 - -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters] -"MaxUserPort"=dword:00001b58 -"TcpTimedWaitDelay"=dword:0000001e</programlisting> - </example> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-External_Value_Storages"> - <title>External Value Storages</title> - <section id="sect-Reference_Guide-External_Value_Storages-Introduction"> - <title>Introduction</title> - <para> - JCR values are stored in the Workspace Data container by default. 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> - Tree-based storage is recommended in most cases. - </para> - </section> - <section id="sect-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage"> - <title>Tree File Value Storage</title> - <para> - Tree File Value Storage holds values in tree-like file system files. <property>Path</property> property points to the root directory to store the files. - </para> - <para> - This is a recommended type of external storage because it can contain large amount of files limited only by disk/volume free space. - </para> - <para> - However, using Tree File Value Storage can result in a higher time on value deletion, due to the removal of unused tree-nodes. - </para> - <example> - <title>Tree File Value Storage Configuration</title> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default25.xml" parse="text"/></programlisting> - <para> - Comment #1: The <emphasis role="bold">id</emphasis> is the value storage unique identifier, used for linking with properties stored in a workspace container. - </para> - <para> - Comment #2: the <emphasis role="bold">path</emphasis> is a location where value files will be stored. - </para> - </example> - <para> - Each file value storage can have the <function>filters</function> for incoming values. A filter can match values by <property>property-type</property>, <property>property-name</property>, <property>ancestor-path</property>. It can also match the size of values stored (<property>min-value-size</property>) in bytes. - </para> - <para> - In the previous example a filter with <property>property-type</property> and <property>min-value-size</property> has been used. This results in storage for binary values with size greater of 1MB. - </para> - <para> - It is recommended that properties with large values are stored in file value storage only. - </para> - <para> - The example below shows a value storage with different locations for large files (<property>min-value-size</property> a 20Mb-sized filter). - </para> - <para> - A value storage uses ORed logic in the process of filter selection. This means the first filter in the list will be called first and if it is not matched the next will be called, and so on. - </para> - <para> - In this example a value matches the 20MB filter <property>min-value-size</property> and will be stored in the path "<literal>data/20Mvalues</literal>". All other filters will be stored in "<literal>data/values</literal>". - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default26.xml" parse="text"/></programlisting> - </section> - <section id="sect-Reference_Guide-External_Value_Storages-Disabling_value_storage"> - <title>Disabling value storage</title> - <para> - The JCR allows you to disable value storage by adding the following property into its configuration. - </para> - <programlisting language="XML"><property name="enabled" value="false" /></programlisting> - <warning> - <title>Warning</title> - <para> - It is recommended that this functionality be used for internal and testing purpose only, and with caution, as all stored values will be inaccessible. - </para> - </warning> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-Workspace_Data_Container"> - <title>Workspace Data Container</title> - <para> - Each Workspace of the JCR has its own persistent storage to hold that workspace's items data. The eXo JCR can be configured so that it can use one or more workspaces that are logical units of the repository content. - </para> - <para> - The physical data storage mechanism is configured using mandatory element <emphasis role="bold">container</emphasis>. The type of container is described in the attribute <parameter>class = <replaceable>fully_qualified_name_of_org.exoplatform.services.jcr.storage.WorkspaceDataContainer_subclass</replaceable></parameter>. - </para> - <example> - <title>Physical Data Storage Configuration</title> - <programlisting language="XML" role="XML"><container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> - <properties> - <property name="source-name" value="jdbcjcr1"/> - <property name="dialect" value="hsqldb"/> - <property name="multi-db" value="true"/> - <property name="max-buffer-size" value="200K"/> - <property name="swap-directory" value="target/temp/swap/ws"/> - <property name="lazy-node-iterator-page-size" value="50"/> - <property name="acl-bloomfilter-false-positive-probability" value="0.1d"/> - <property name="acl-bloomfilter-elements-number" value="1000000"/> - </properties></programlisting> - <para> - <literal>source-name</literal>: The JDBC data source name which is registered in JDNI by InitialContextInitializer. This was known as <literal>sourceName</literal> in versions prior to 1.9. - </para> - <para> - <literal>dialect</literal>: The database dialect. Must be one of the following: <literal>hsqldb</literal>, <literal>mysql</literal>, <literal>mysql-utf8</literal>, <literal>pgsql</literal>, <literal>oracle</literal>, <literal>oracle-oci</literal>, <literal>mssql</literal>, <literal>sybase</literal>, <literal>derby</literal>, <literal>db2</literal> or <literal>db2v8</literal>). - </para> - <para> - <literal>multi-db</literal>: This parameter, if <literal>true</literal>, enables multi-database container. - </para> - <para> - <literal>max-buffer-size</literal>: A threshold in bytes. If a value size is greater than this setting, then it will be spooled to a temporary file. - </para> - <para> - <literal>swap-directory</literal>: A location where the value will be spooled if no value storage is configured but a <literal>max-buffer-size</literal> is exceeded. - </para> - <para> - <literal>lazy-node-iterator-page-size</literal>: "Lazy" child nodes iterator settings. Defines size of page, the number of nodes that are retrieved from persistent storage at once. - </para> - <para> - <literal>acl-bloomfilter-false-positive-probability</literal>: ACL Bloom-filter settings. ACL Bloom-filter desired false positive probability. Range [0..1]. Default value 0.1d. - </para> - <para> - <literal>acl-bloomfilter-elements-number</literal>: ACL Bloom-filter settings. Expected number of ACL-elements in the Bloom-filter. Default value 1000000. - </para> - </example> - <note> - <para> - Bloom filters are not supported by all the cache implementations so far only the inplementation for infinispan supports it. - </para> - <para> - Bloom-filter used to avoid read nodes that definitely do not have ACL. <emphasis role="bold">acl-bloomfilter-false-positive-probability</emphasis> and <emphasis role="bold">acl-bloomfilter-elements-number</emphasis> used to configure such filters. Bloom filters are not supported by all the cache implementations so far only the inplementation for infinispan supports it. - </para> - <para> - More about Bloom filters you can read here <ulink url="http://en.wikipedia.org/wiki/Bloom_filter">http://en.wikipedia.org/wiki/Bloom_filter</ulink>. - </para> - </note> - <para> - The eXo JCR has a JDBC-based, relational database, production ready <emphasis role="bold">Workspace Data Container</emphasis>. - </para> - <para> - Workspace Data Container <emphasis>may</emphasis> support external storages for <literal>javax.jcr.Value</literal> (which can be the case for BLOB values for example) using the optional element <literal>value-storages</literal>. - </para> - <para> - The Data Container will try to read or write a Value using the underlying value storage plug-in if the filter criteria (see below) match the current property. - </para> - <example> - <title>External Value Storage Configuration</title> - <programlisting language="XML" role="XML"><value-storages> - <value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> - <properties> - <property name="path" value="data/values"/> - </properties> - <filters> - <filter property-type="Binary" min-value-size="1M"/> - </filters> -......... -</value-storages></programlisting> - <para> - <literal>value-storage</literal> is the subclass of <literal>org.exoplatform.services.jcr.storage.value.ValueStoragePlugin</literal> and <literal>properties</literal> are optional plug-in specific parameters. - </para> - <para> - <literal>filters</literal>: Each file value storage can have the filter(s) for incoming values. If there are several filter criteria, they all have to match (AND-Condition). - </para> - </example> - <para> - A filter can match values by property type (property-type), property name (property-name), ancestor path (ancestor-path) and/or the size of values stored (min-value-size, e.g. 1M, 4.2G, 100 (bytes)). - </para> - <para> - In a code sample, we use a filter with property-type and min-value-size only. That means that the storage is only for binary values whose size is greater than 1Mbyte. - </para> - <para> - It is recommended that you store properties with large values in a file value storage only. - </para> - </section> - <section xmlns="" id="chap-Reference_Guide-Cluster_Configuration"> - <title>Configuring Cluster</title> - <section id="sect-Reference_Guide-Cluster_Configuration-Launching_Cluster"> - <title>Launching Cluster</title> - <section id="sect-Reference_Guide-Launching_Cluster-Configuring_JCR_to_use_external_configuration"> - <title>Configuring JCR to use external configuration</title> - <itemizedlist> - <listitem> - <para> - To manually configure a repository, create a new configuration file (<filename>exo-jcr-configuration.xml</filename> for example). For details, see <xref linkend="chap-Reference_Guide-JCR_configuration"/>. - </para> - <para> - The configuration file must be formatted as follows: - </para> - <example> - <title>External Configuration</title> - <programlisting language="XML" role="XML"><repository-service default-repository="repository1"> - <repositories> - <repository name="repository1" system-workspace="ws1" default-workspace="ws1"> - <security-domain>exo-domain</security-domain> - <access-control>optional</access-control> - <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy> - <workspaces> - <workspace name="ws1"> - <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"> - <properties> - <property name="source-name" value="jdbcjcr" /> - <property name="dialect" value="oracle" /> - <property name="multi-db" value="false" /> - <property name="update-storage" value="false" /> - <property name="max-buffer-size" value="200k" /> - <property name="swap-directory" value="../temp/swap/production" /> - </properties> - <value-storages> - <![CDATA[]]> - </value-storages> - </container> - <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"> - <properties> - <property name="root-nodetype" value="nt:unstructured" /> - </properties> - </initializer> - <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"> - <![CDATA[]]> - </cache> - <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - <![CDATA[]]> - </query-handler> - <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"> - <![CDATA[]]> - </lock-manager> - </workspace> - <workspace name="ws2"> - ... - </workspace> - <workspace name="wsN"> - ... - </workspace> - </workspaces> - </repository> - </repositories> -</repository-service></programlisting> - <para> - Comment #1: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Value_Storage_configuration"/>. - </para> - <para> - Comment #2: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Cache_configuration"/>. - </para> - <para> - Comment #3: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Indexer_configuration"/>. - </para> - <para> - Comment #4: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Lock_Manager_configuration"/>. - </para> - </example> - </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"><component> - <key>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</key> - <type>org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl</type> - <init-params> - <value-param> - <name>conf-path</name> - <description>JCR configuration file</description> - <value>exo-jcr-configuration.xml</value> - </value-param> - </init-params> -</component></programlisting> - </listitem> - </itemizedlist> - </section> - </section> - <section id="sect-Reference_Guide-Cluster_Configuration-Requirements"> - <title>Requirements</title> - <section id="sect-Reference_Guide-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-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> - </itemizedlist> - </section> - <section id="sect-Reference_Guide-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-Configuration_requirements-Value_Storage_configuration"> - <title>Value Storage configuration</title> - <programlisting language="XML" role="XML"><value-storages> - <value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> - <properties> - <property name="path" value="/mnt/tornado/temp/values/production" />  - </properties> - <filters> - <filter property-type="Binary" /> - </filters> - </value-storage> -</value-storages></programlisting> - </example> - <example id="exam-Reference_Guide-Configuration_requirements-Cache_configuration"> - <title>Cache configuration</title> - <programlisting language="XML" role="XML"><cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"> - <properties> - <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-data.xml" />  - <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />  - <property name="jbosscache-cluster-name" value="JCR_Cluster_cache_production" />  - <property name="jgroups-multiplexer-stack" value="true" /> - </properties> -</cache></programlisting> - </example> - <example id="exam-Reference_Guide-Configuration_requirements-Indexer_configuration"> - <title>Indexer configuration</title> - <programlisting language="XML" role="XML"><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - <properties> - <property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /> - <property name="index-dir" value="/mnt/tornado/temp/jcrlucenedb/production" />  - <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-indexer.xml" />  - <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />  - <property name="jbosscache-cluster-name" value="JCR_Cluster_indexer_production" />  - <property name="jgroups-multiplexer-stack" value="true" /> - </properties> -</query-handler></programlisting> - </example> - <example id="exam-Reference_Guide-Configuration_requirements-Lock_Manager_configuration"> - <title>Lock Manager configuration</title> - <programlisting language="XML" role="XML"><lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"> - <properties> - <property name="time-out" value="15m" /> - <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-lock.xml" />  - <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />  - <property name="jgroups-multiplexer-stack" value="true" /> - <property name="jbosscache-cluster-name" value="JCR_Cluster_lock_production" />  - - <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_production"/>  - <property name="jbosscache-cl-cache.jdbc.table.create" value="true"/> - <property name="jbosscache-cl-cache.jdbc.table.drop" value="false"/> - <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_production_pk"/> - <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn"/> - <property name="jbosscache-cl-cache.jdbc.node.column" value="node"/> - <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent"/> - <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr"/> - </properties> -</lock-manager></programlisting> - </example> - </section> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-JBoss_Cache_configuration"> - <title>Configuring JBoss Cache</title> - <section id="sect-Reference_Guide-JBoss_Cache_configuration-Indexer_lock_manager_and_data_container_configuration"> - <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"><property name="jbosscache-configuration" value="conf/standalone - /test-jbosscache-lock-db1-ws1.xml" /></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-<parameter name>} 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">... -<clustering mode="replication" clusterName="${jbosscache-cluster-name}"> - <stateRetrieval timeout="20000" fetchInMemoryState="false" /> -...</programlisting> - <para> - and JCR configuration file: - </para> - <programlisting language="XML" role="XML">... -<property name="jbosscache-configuration" value="jar:/conf/portal/jbosscache-lock.xml" /> -<property name="jbosscache-cluster-name" value="JCR-cluster-locks-db1-ws" /> -...</programlisting> - </section> - <section id="sect-Reference_Guide-JBoss_Cache_configuration-JGroups_configuration"> - <title>JGroups configuration</title> - <para> - JGroups is used by JBoss Cache for network communications and transport in 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"><property name="jgroups-configuration" value="your/path/to/modified-udp.xml" /></programlisting> - <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"><property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> -<property name="jgroups-multiplexer-stack" value="true" /></programlisting> - </section> - <section id="sect-Reference_Guide-JBoss_Cache_configuration-Sharing_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"><property name="jbosscache-shareable" value="true" /></programlisting> - <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><PARAM_NAME></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-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 <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/jbosscache</filename> directory, inside either the <filename>cluster</filename> or <filename>local</filename> directory. - </para> - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Data_container_template"> - <title>Data container template</title> - <para> - The data container template is <filename>config.xml</filename>: - </para> - <programlisting language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?> -<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"> - - <locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" - lockAcquisitionTimeout="20000" /> - - <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> - <stateRetrieval timeout="20000" fetchInMemoryState="false" /> - <jgroupsConfig multiplexerStack="jcr.stack" /> - <sync /> - </clustering> - -  - <eviction wakeUpInterval="5000"> - <default algorithmClass="org.jboss.cache.eviction.LRUAlgorithm" - actionPolicyClass="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.ParentNodeEvictionActionPolicy" - eventQueueSize="1000000"> - <property name="maxNodes" value="1000000" /> - <property name="timeToLive" value="120000" /> - </default> - </eviction> -</jbosscache></programlisting> - </section> - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template"> - <title>Lock manager template</title> - <para> - The lock manager template is <filename>lock-config.xml</filename>: - </para> - <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/lock-config.xml_code" parse="text"/></programlisting> - </section> - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Query_handler_indexer_template"> - <title>Query handler (indexer) template</title> - <para> - The query handler template is called <filename>indexer-config.xml</filename>: - </para> - <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/indexer-config.xml_code" parse="text"/></programlisting> - </section> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-LockManager"> - <title>LockManager</title> - <para> - The LockManager stores lock objects. It can lock or release objects as required. It is also responsible for removing stale locks. - </para> - <para> - The LockManager in JBoss Portal Platform is implemented with <classname>org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl</classname>. - </para> - <para> - It is enabled by adding <literal>lock-manager-configuration</literal> to <literal>workspace-configuration</literal>. - </para> - <para> - For example: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default47.xml" parse="text"/></programlisting> - <section id="sect-Reference_Guide-LockManager-CacheableLockManagerImpl"> - <title>CacheableLockManagerImpl</title> - <para> - <classname>CacheableLockManagerImpl</classname> stores lock objects in JBoss-cache (which implements JDBCCacheLoader to store locks in a database). This means its locks are replicable and can affect an entire cluster rather than just a single node. - </para> - <para> - The length of time LockManager allows a lock to remain in place can be configured with the "<literal>time-out</literal>" property. - </para> - <para> - The LockRemover thread periodically polls LockManager for locks that have passed the time-out limit and must be removed. - </para> - <para> - The time-out for LockRemover is set as follows (the default value is 30m): - </para> - <programlisting language="XML"><properties> - <property name="time-out" value="10m" /> - ... -</properties></programlisting> - <para> - There are a number of ways to configure <classname>CacheableLockManagerImpl</classname>. Each involves configuring JBoss Cache and JDBCCacheLoader. - </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"/> - </para> - </listitem> - </itemizedlist> - <para> - Refer to <ulink url="http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader">http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader</ulink> for more information about JBoss Cache and JDBCCacheLoader. - </para> - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration"> - <title>Simple JBoss Cache Configuration</title> - <para> - One method to configure the LockManager is to put a JBoss Cache configuration file path into <classname>CacheableLockManagerImpl</classname>. - </para> - <note> - <para> - This is not the most efficient method for configuring the LockManager as it requires a JBoss Cache configuration file for each LockManager configuration in each workspace of each repository. The configuration set up can subsequently become quite difficult to manage. - </para> - <para> - This method is useful, however, if a single, specially configured LockManager is required. - </para> - </note> - <para> - The required configuration is shown in the example below: - </para> - <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default49.xml" parse="text"/></programlisting> - <para> - Sample content of the <replaceable>jbosscache-lock-config.xml</replaceable> file specified in the <replaceable>jbosscache-configuration</replaceable> property is shown in the code example below. - </para> - <example> - <title>Sample Content of the jbosscache-lock-config.xml File</title> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default50.xml" parse="text"/></programlisting> - <para> - Comment #1: The cluster name at <parameter>clustering mode="replication" clusterName="JBoss-Cache-Lock-Cluster_Name"</parameter> must be unique; - </para> - <para> - Comment #2: The <parameter>cache.jdbc.table.name</parameter> must be unique per datasource. - </para> - <para> - Comment #3: The <parameter>cache.jdbc.node.type</parameter> and <parameter>cache.jdbc.fqn.type</parameter> parameters must be configured according to the database in use. Refer to the table below for information about data types. - </para> - </example> - <table id="tabl-Reference_Guide-Simple_JBoss_Cache_Configuration-Data_Types_in_Different_Databases"> - <title>Data Types in Different Databases</title> - <tgroup cols="3"> - <thead> - <row> - <entry> DataBase name </entry> - <entry> Node data type </entry> - <entry> FQN data type </entry> - </row> - </thead> - <tbody> - <row> - <entry> default </entry> - <entry> BLOB </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> HSSQL </entry> - <entry> OBJECT </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> MySQL </entry> - <entry> LONGBLOB </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> ORACLE </entry> - <entry> BLOB </entry> - <entry> VARCHAR2(512) </entry> - </row> - <row> - <entry> PostgreSQL </entry> - <entry> bytea </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> MSSQL </entry> - <entry> VARBINARY(MAX) </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> DB2 </entry> - <entry> BLOB </entry> - <entry> VARCHAR(512) </entry> - </row> - <row> - <entry> Sybase </entry> - <entry> IMAGE </entry> - <entry> VARCHAR(512) </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"> - <title>Template JBoss Cache Configuration</title> - <para> - Another method to configure LockManager is to use a JBoss Cache configuration template for all LockManagers. - </para> - <para> - Below is an example <filename>test-jbosscache-lock.xml</filename> template file: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/you.xml" parse="text"/></programlisting> - <para> - The parameters that will populate the above file are shown below: - </para> - <example> - <title>JBoss Cache Configuration Parameters</title> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default51.xml" parse="text"/></programlisting> - <para> - Comment #1: The <literal>jgroups-configuration</literal> has been moved to a separate configuration file (<filename>udp-mux.xml</filename>, shown below). In this case the <filename>udp-mux.xml</filename> is a common configuration for all JGroup components (QueryHandler, cache, LockManager), but this is not a requirement of the configuration method. - </para> - <para> - Comment #2: The <parameter>jbosscache-cl-cache.jdbc.fqn.column</parameter> and <parameter>jbosscache-cl-cache.jdbc.node.type</parameter> parameters are not explicitly defined as <parameter>cache.jdbc.fqn.type</parameter> and <parameter>cache.jdbc.node.type</parameter> are defined in the JBoss Cache configuration. - </para> - </example> - <para> - Refer to <xref linkend="tabl-Reference_Guide-Simple_JBoss_Cache_Configuration-Data_Types_in_Different_Databases"/> for information about setting these parameters or set them as <parameter>AUTO</parameter> and the data type will by detected automatically. - </para> - <para> - <filename>udp-mux.xml</filename>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default52.xml" parse="text"/></programlisting> - </section> - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Lock_migration_from_1.12.x"> - <title>Lock Migration</title> - <para> - There are three options available: - </para> - <variablelist id="vari-Reference_Guide-Lock_migration_from_1.12.x-Lock_Migration_Options"> - <title>Lock Migration Options</title> - <varlistentry> - <term>When new Shareable Cache feature is not going to be used and all locks should be kept after migration.</term> - <listitem> - <procedure> - <title/> - <step> - <para> - Ensure that the same lock tables are used in configuration - </para> - </step> - <step> - <para> - Start the server - </para> - </step> - </procedure> - </listitem> - </varlistentry> - <varlistentry> - <term>When new Shareable Cache feature is not going to be used and all locks should be removed after migration.</term> - <listitem> - <procedure> - <title/> - <step> - <para> - Ensure that the same lock tables used in configuration - </para> - </step> - <step> - <para> - Start the sever WITH system property: - </para> - <programlisting>-Dorg.exoplatform.jcr.locks.force.remove=true -</programlisting> - </step> - <step> - <para> - Stop the server - </para> - </step> - <step> - <para> - Start the server WITHOUT system property: - </para> - <programlisting>-Dorg.exoplatform.jcr.locks.force.remove -</programlisting> - </step> - </procedure> - </listitem> - </varlistentry> - <varlistentry> - <term>When new Shareable Cache feature will be used (in this case all locks are removed after migration).</term> - <listitem> - <procedure> - <title/> - <step> - <para> - Start the sever WITH system property: - </para> - <programlisting>-Dorg.exoplatform.jcr.locks.force.remove=true -</programlisting> - </step> - <step> - <para> - Stop the server. - </para> - </step> - <step> - <para> - Start the server WITHOUT system property: - </para> - <programlisting>-Dorg.exoplatform.jcr.locks.force.remove -</programlisting> - </step> - <step> - <title>Optional:</title> - <para> - Manually remove old tables for lock. - </para> - </step> - </procedure> - </listitem> - </varlistentry> - </variablelist> - </section> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-QueryHandler_configuration"> - <title>Configuring QueryHandler</title> - <section id="sect-Reference_Guide-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> - <figure> - <title id="diagramlocalindez">Local Index Diagram</title> - <mediaobject> - <imageobject> - <imagedata width="444" align="center" fileref="images/diagram-local-index.png"/> - </imageobject> - </mediaobject> - </figure> - <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 scenarios. 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> - <figure> - <title id="diagramsharedindex">Shared Index Diagram</title> - <mediaobject> - <imageobject> - <imagedata width="444" align="center" fileref="images/diagram-shared-index.png"/> - </imageobject> - </mediaobject> - </figure> - <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="chap-Reference_Guide-Search_Configuration"/> . - </para> - </section> - <section id="sect-Reference_Guide-QueryHandler_configuration-Configuration"> - <title>Configuration</title> - <section id="sect-Reference_Guide-Configuration-Query_handler_configuration_overview"> - <title>Query-handler configuration overview</title> - <para> - Configuration example: - </para> - <programlisting language="XML"><workspace name="ws"> - <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - <properties> - <property name="index-dir" value="shareddir/index/db1/ws" /> - <property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /> - <property name="jbosscache-configuration" value="jbosscache-indexer.xml" /> - <property name="jgroups-configuration" value="udp-mux.xml" /> - <property name="jgroups-multiplexer-stack" value="true" /> - <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /> - <property name="max-volatile-time" value="60" /> - <property name="rdbms-reindexing" value="true" /> - <property name="reindexing-page-size" value="1000" /> - <property name="index-recovery-mode" value="from-coordinator" /> - <property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /> - </properties> - </query-handler> -</workspace> -</programlisting> - <table id="tabl-Reference_Guide-Query_handler_configuration_overview-Configuration_properties"> - <title>Configuration properties</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Property name </entry> - <entry> Description </entry> - </row> - </thead> - <tbody> - <row> - <entry> index-dir </entry> - <entry> path to index </entry> - </row> - <row> - <entry> 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> jgroups-configuration </entry> - <entry> jgroups-configuration is template configuration for all components (search, cache, locks) [Add link to document describing template configurations] </entry> - </row> - <row> - <entry> jgroups-multiplexer-stack </entry> - <entry> [TODO about jgroups-multiplexer-stack - add link to JBoss doc] </entry> - </row> - <row> - <entry> jbosscache-cluster-name </entry> - <entry> cluster name (must be unique) </entry> - </row> - <row> - <entry> max-volatile-time </entry> - <entry> max time to live for Volatile Index </entry> - </row> - <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> 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-filter </entry> - <entry> Defines implementation class or classes of RecoveryFilters, the mechanism of index synchronization for Local Index strategy. </entry> - </row> - <row> - <entry> async-reindexing </entry> - <entry> Controls the process of re-indexing on JCR's startup. If this flag is set, indexing will be launched asynchronously, without blocking the JCR. Default is "<literal>false</literal>". </entry> - </row> - </tbody> - </tgroup> - </table> - <formalpara id="form-Reference_Guide-Query_handler_configuration_overview-Improving_Query_Performance_With_postgreSQL_and_rdbms_reindexing"> - <title>Improving Query Performance With <literal>postgreSQL</literal> and <parameter>rdbms-reindexing</parameter></title> - <para> - If you use <literal>postgreSQL</literal> and <parameter>rdbms-reindexing</parameter> is set to <literal>true</literal>, the performance of the queries used while indexing can be improved by: - </para> - </formalpara> - <procedure> - <title/> - <step> - <para> - Set the parameter "<parameter>enable_seqscan</parameter>" to "<literal>off</literal>" - </para> - <para> - <emphasis role="bold">OR</emphasis> - </para> - <para> - Set "<parameter>default_statistics_target</parameter>" to at least "<literal>50</literal>". - </para> - </step> - <step> - <para> - Restart DB server and make analyze of the JCR_SVALUE (or JCR_MVALUE) table. - </para> - </step> - </procedure> - <formalpara id="form-Reference_Guide-Query_handler_configuration_overview-Improving_Query_Performance_With_DB2_and_rdbms_reindexing"> - <title>Improving Query Performance With <literal>DB2</literal> and <parameter>rdbms-reindexing</parameter></title> - <para> - If you use <literal>DB2</literal> and <parameter>rdbms-reindexing</parameter> is set to <literal>true</literal>, the performance of the queries used while indexing can be improved by: - </para> - </formalpara> - <procedure> - <title/> - <step> - <para> - Make statistics on tables by running the following for <literal>JCR_SITEM</literal> (or <literal>JCR_MITEM</literal>) and <literal>JCR_SVALUE</literal> (or <literal>JCR_MVALUE</literal>) tables: - </para> - <programlisting><code>RUNSTATS ON TABLE <scheme>.<table> WITH DISTRIBUTION AND INDEXES ALL</code></programlisting> - </step> - </procedure> - </section> - <section id="sect-Reference_Guide-Configuration-Cluster_ready_indexing"> - <title>Cluster-ready indexing</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"><workspace name="ws"> - <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - <properties> - <property name="index-dir" value="/mnt/nfs_drive/index/db1/ws" /> - <property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /> - <property name="jbosscache-configuration" value="jbosscache-indexer.xml" /> - <property name="jgroups-configuration" value="udp-mux.xml" /> - <property name="jgroups-multiplexer-stack" value="true" /> - <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /> - <property name="max-volatile-time" value="60" /> - <property name="rdbms-reindexing" value="true" /> - <property name="reindexing-page-size" value="1000" /> - <property name="index-recovery-mode" value="from-coordinator" /> - </properties> - </query-handler> -</workspace></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> - <programlisting language="XML" role="XML"><workspace name="ws"> - <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> - <properties> - <property name="index-dir" value="/mnt/nfs_drive/index/db1/ws" /> - <property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter" /> - <property name="jbosscache-configuration" value="jbosscache-indexer.xml" /> - <property name="jgroups-configuration" value="udp-mux.xml" /> - <property name="jgroups-multiplexer-stack" value="true" /> - <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /> - <property name="max-volatile-time" value="60" /> - <property name="rdbms-reindexing" value="true" /> - <property name="reindexing-page-size" value="1000" /> - <property name="index-recovery-mode" value="from-coordinator" /> - </properties> - </query-handler> -</workspace> -</programlisting> - </section> - <section id="sect-Reference_Guide-Configuration-Local_Index_Recovery_Filters"> - <title>Local Index Recovery Filters</title> - <para> - A common usecase for all cluster-ready applications is a hot joining and leaving of processing units. All nodes that are joining a cluster for the first time or nodes joining after some downtime, must be in a synchronized state. - </para> - <para> - When using shared value storages, databases and indexes, cluster nodes are synchronized at any given time. But is not the case when a local index strategy is used. - </para> - <para> - If a new node joins a cluster, without an index it is retrieved or recreated. Nodes can be also be restarted and thus the index is not empty. By default, even though the existing index is thought to be up to date, it can be outdated. - </para> - <para> - The JBoss Portal Platform JCR offers a mechanism called <literal>RecoveryFilters</literal> that will automatically retrieve index for the joining node on start up. This feature is a set of filters that can be defined via <literal>QueryHandler</literal> configuration: - </para> - <programlisting language="XML"><property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /></programlisting> - <para> - Filter numbers are not limited so they can be combined: - </para> - <programlisting language="XML"><property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /> - <property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.SystemPropertyRecoveryFilter" /> -</programlisting> - <para> - If any one returns fires, the index is re-synchronized. This feature uses standard index recovery mode defined by previously described parameter (can be "from-indexing" (default) or "from-coordinator") - </para> - <programlisting language="XML"><property name="index-recovery-mode" value="from-coordinator" /> -</programlisting> - <para> - There are multiple filter implementations: - </para> - <variablelist id="vari-Reference_Guide-Local_Index_Recovery_Filters-org.exoplatform.services.jcr.impl.core.query.lucene.DummyRecoveryFilter"> - <varlistentry> - <term>org.exoplatform.services.jcr.impl.core.query.lucene.DummyRecoveryFilter</term> - <listitem> - <para> - Always returns true, for cases when index must be force resynchronized (recovered) each time. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.exoplatform.services.jcr.impl.core.query.lucene.SystemPropertyRecoveryFilter</term> - <listitem> - <para> - Returns value of system property "<literal>org.exoplatform.jcr.recoveryfilter.forcereindexing</literal>". So index recovery can be controlled from the top without changing documentation using system properties. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.exoplatform.services.jcr.impl.core.query.lucene.ConfigurationPropertyRecoveryFilter</term> - <listitem> - <para> - Returns value of <literal>QueryHandler</literal> configuration property "<literal>index-recovery-filter-forcereindexing</literal>". So index recovery can be controlled from configuration separately for each workspace. For example: - </para> - <programlisting language="XML"><property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.ConfigurationPropertyRecoveryFilter" /> - <property name="index-recovery-filter-forcereindexing" value="true" /> -</programlisting> - </listitem> - </varlistentry> - <varlistentry> - <term>org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter</term> - <listitem> - <para> - Checks the number of documents in index on coordinator side and self-side. It returns <literal>true</literal> if the count differs. - </para> - <para> - The advantage of this filter compared to others, is that it will skip reindexing for workspaces where the index was not modified. - </para> - <para> - For example; if there is ten repositories with three workspaces in each and only one is heavily used in the cluster, this filter will only reindex those workspaces that have been changed, without affecting other indexes. - </para> - <para> - This greatly reduces start up time. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sect-Reference_Guide-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 id="exam-Reference_Guide-JBoss_Cache_template_configuration-jbosscache_indexer.xml"> - <title>jbosscache-indexer.xml</title> - <programlisting language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?> -<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"> - <locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" - lockAcquisitionTimeout="20000" /> -  - <transaction transactionManagerLookupClass="org.jboss.cache.transaction.JBossStandalone - JTAManagerLookup" /> - <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> - <stateRetrieval timeout="20000" fetchInMemoryState="false" /> - <jgroupsConfig multiplexerStack="jcr.stack" /> - <sync /> - </clustering> -  - <eviction wakeUpInterval="5000"> - <default algorithmClass="org.jboss.cache.eviction.FIFOAlgorithm" eventQueueSize="1000000"> - <property name="maxNodes" value="10000" /> - <property name="minTimeToLive" value="60000" /> - </default> - </eviction> -</jbosscache></programlisting> - </example> - <para> - Read more about template configurations <xref linkend="chap-Reference_Guide-JBoss_Cache_configuration"/>. - </para> - </section> - </section> - <section id="sect-Reference_Guide-QueryHandler_configuration-Asynchronous_Reindexing"> - <title>Asynchronous Re-indexing</title> - <para> - Managing a large data set using a JCR in a production environment at times requires special operations with Indexes, stored on File System. One of those maintenance operations is a recreation of it. Also called "re-indexing". There are various usecases when it's important to do. They include hardware faults, hard restarts, data-corruption, migrations and JCR updates that brings new features related to index. Usually index re-creation requested on server's startup or in runtime. - </para> - <section id="sect-Reference_Guide-Asynchronous_Reindexing-On_startup_indexing"> - <title>On startup indexing</title> - <para> - A common usecase for updating and re-creating the index is to stop the server and manually remove indexes for workspaces requiring it. When the server is re-started, the missing indexes are automatically recovered by re-indexing. - </para> - <para> - The eXo JCR Supports direct RDBMS re-indexing, which can be faster than ordinary and can be configured via <literal>QueryHandler</literal> parameter <parameter>rdbms-reindexing</parameter> set to <literal>true</literal>. - </para> - <para> - A new feature is asynchronous indexing on startup. Usually startup is blocked until the indexing process is finished. This block can take any period of time, depending on amount of data persisted in repositories. But this can be resolved by using an asynchronous approaches of startup indexation. - </para> - <para> - Essentially, all indexing operations are performed in the background without blocking the repository. This is controlled by the value of the <parameter>async-reindexing</parameter> parameter in <literal>QueryHandler</literal> configuration. - </para> - <para> - With asynchronous indexation active, the JCR starts with no active indexes present. Queries on JCR still can be executed without exceptions, but no results will be returned until index creation completed. - </para> - <para> - The index state check is accomplished via <literal>QueryManagerImpl</literal>: - </para> - <para> - -<programlisting lang="java">boolean online = ((QueryManagerImpl)Workspace.getQueryManager()).getQueryHandeler().isOnline();</programlisting> - - </para> - <para> - The <emphasis role="bold">OFFLINE</emphasis> state means that the index is currently re-creating. When the state is changed, a corresponding log event is printed. When the background index task starts the index is switched to <emphasis role="bold">OFFLINE</emphasis>, with following log event : - </para> - <programlisting>[INFO] Setting index OFFLINE (repository/production[system]).</programlisting> - <para> - When the indexing process is finished, the following two events are logged : - </para> - <programlisting>[INFO] Created initial index for 143018 nodes (repository/production[system]). -[INFO] Setting index ONLINE (repository/production[system]).</programlisting> - <para> - Those two log lines indicates the end of process for workspace given in brackets. Calling isOnline() as mentioned above, will also return true. - </para> - </section> - <section id="sect-Reference_Guide-Asynchronous_Reindexing-Hot_Asynchronous_Workspace_Reindexing_via_JMX"> - <title>Hot Asynchronous Workspace Re-indexing using JMX</title> - <para> - Some hard system faults, errors during upgrades, migration issues and some other factors may corrupt the index. Current versions of JCR supports <emphasis role="bold">Hot Asynchronous Workspace Reindexing</emphasis> feature. It allows Service Administrators to launch the process in background without stopping or blocking the whole application by using any JMX-compatible console. - </para> - <figure> - <title id="jmx-jconsole">JMX Jconsole</title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/jmx-jconsole.png"/> - </imageobject> - </mediaobject> - </figure> - <para> - The server can continue working as expected while the index is recreated. - </para> - <para> - This depends on the flag <parameter>allow queries</parameter> being passed via JMX interface to the reindex operation invocation. If the flag is set, the application continues working. - </para> - <para> - However, there is one critical limitation users must be aware of; <emphasis>the index is frozen while the background task is running</emphasis>. - </para> - <para> - This means that queries are performed on a version of the index present at the moment the indexing task is started, and that data written into the repository after startup will not be available through the search until process completes. - </para> - <para> - Data added during re-indexation is also indexed, but will be available only when reindexing is complete. The JCR makes a snapshot of indexes at the invocation of the asynchronous indexing task and uses that snapshot for searches. - </para> - <para> - When the operation is finished, the stale index is replaced by the newly created index, which included any newly added data. - </para> - <para> - If the <parameter>allow queries</parameter> flag is set to <literal>false</literal>, then all queries will throw an exception while task is running. The current state can be acquired using the following JMX operation: - </para> - <itemizedlist> - <listitem> - <para> - getHotReindexingState() - returns information about latest invocation: start time, if in progress or finish time if done. - </para> - </listitem> - </itemizedlist> - </section> - <section id="sect-Reference_Guide-Asynchronous_Reindexing-Notices"> - <title>Notices</title> - <para> - Hot re-indexing via JMX cannot be launched if the index is already in offline mode. This means that the index is currently involved in some other operations, such as re-indexing at startup, copying in cluster to another node or whatever. - </para> - <para> - Also; <emphasis>Hot Asynchronous Reindexing via JMX</emphasis> and <literal>on startup</literal> reindexing are different features. So you can't get the state of startup reindexing using command <code>getHotReindexingState</code> in JMX interface, but there are some common JMX operations: - </para> - <itemizedlist> - <listitem> - <para> - getIOMode - returns current index IO mode (READ_ONLY / READ_WRITE), belongs to clustered configuration states; - </para> - </listitem> - <listitem> - <para> - getState - returns current state: ONLINE / OFFLINE. - </para> - </listitem> - </itemizedlist> - </section> - </section> - <section id="sect-Reference_Guide-QueryHandler_configuration-Advanced_tuning"> - <title>Advanced tuning</title> - <section id="sect-Reference_Guide-Advanced_tuning-Lucene_tuning"> - <title>Lucene tuning</title> - <para> - As mentioned, JCR Indexing is based on the Lucene indexing library as the underlying search engine. It uses Directories to store index and manages access to index by Lock Factories. - </para> - <para> - By default, the JCR implementation uses optimal combination of Directory implementation and Lock Factory implementation. - </para> - <para> - The <literal>SimpleFSDirectory</literal> is used in Windows environments and the <literal>NIOFSDirectory</literal> implementation is used in non-Windows systems. - </para> - <para> - <literal>NativeFSLockFactory</literal> is an optimal solution for a wide variety of cases including clustered environment with NFS shared resources. - </para> - <para> - But those defaults can be overridden in the system properties. - </para> - <para> - Two properties: <literal>org.exoplatform.jcr.lucene.store.FSDirectoryLockFactoryClass</literal> and <literal>org.exoplatform.jcr.lucene.FSDirectory.class</literal> control (and change) the default behavior. - </para> - <para> - The first defines the implementation of abstract Lucene <literal>LockFactory</literal> class and the second sets implementation class for <literal>FSDirectory</literal> instances. - </para> - <para> - For more information, refer to the Lucene documentation. But be careful, for while the JCR allows users to change implementation classes of Lucene internals, it does not guarantee the stability and functionality of those changes. - </para> - </section> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-JBossTransactionsService"> - <title>JBossTransactionsService</title> - <section id="sect-Reference_Guide-JBossTransactionsService-Introduction"> - <title>Introduction</title> - <para> - JBossTransactionsService implements eXo TransactionService and provides access to <ulink url="http://www.jboss.org/jbosstm/">JBoss Transaction Service (JBossTS)</ulink> JTA implementation via eXo container dependency. - </para> - <para> - TransactionService used in JCR cache <emphasis>org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache</emphasis> implementation. - </para> - </section> - <section id="sect-Reference_Guide-JBossTransactionsService-Configuration"> - <title>Configuration</title> - <para> - Example configuration: - </para> - <programlisting language="XML" role="XML"> <component> - <key>org.exoplatform.services.transaction.TransactionService</key> - <type>org.exoplatform.services.transaction.jbosscache.JBossTransactionsService</type> - <init-params> - <value-param> - <name>timeout</name> - <value>3000</value> - </value-param> - </init-params> - </component></programlisting> - <para> - timeout - XA transaction timeout in seconds - </para> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-JCR_Query_Usecases"> - <title>JCR Query Use-cases</title> - <section id="sect-Reference_Guide-JCR_Query_Usecases-Introduction"> - <title>Introduction</title> - <para> - The JCR supports two query languages; JCR and XPath. A query, whether XPath or SQL, specifies a subset of nodes within a workspace, called the result set. The result set constitutes all the nodes in the workspace that meet the constraints stated in the query. - </para> - </section> - <section id="sect-Reference_Guide-JCR_Query_Usecases-Query_Lifecycle"> - <title>Query Lifecycle</title> - <section id="sect-Reference_Guide-Query_Lifecycle-Query_Creation_and_Execution"> - <title>Query Creation and Execution</title> - <example id="exam-Reference_Guide-Query_Lifecycle-Query_Creation_and_Execution-SQL"> - <title>SQL</title> - <programlisting language="Java" role="Java">// get QueryManager -QueryManager queryManager = workspace.getQueryManager();  -// make SQL query -Query query = queryManager.createQuery("SELECT * FROM nt:base ", Query.SQL); -// execute query -QueryResult result = query.execute();</programlisting> - </example> - <example id="exam-Reference_Guide-Query_Lifecycle-Query_Creation_and_Execution-XPath"> - <title>XPath</title> - <programlisting language="Java" role="Java">// get QueryManager -QueryManager queryManager = workspace.getQueryManager(); -// make XPath query -Query query = queryManager.createQuery("//element(*,nt:base)", Query.XPATH); -// execute query -QueryResult result = query.execute();</programlisting> - </example> - </section> - <section id="sect-Reference_Guide-Query_Lifecycle-Query_Result_Processing"> - <title>Query Result Processing</title> - <programlisting language="Java" role="Java">// fetch query result -QueryResult result = query.execute();</programlisting> - <para> - To fetch the nodes: - </para> - <programlisting language="Java" role="Java">NodeIterator it = result.getNodes();</programlisting> - <para> - The results can be formatted in a table: - </para> - <programlisting language="Java" role="Java">// get column names -String[] columnNames = result.getColumnNames(); -// get column rows -RowIterator rowIterator = result.getRows(); -while(rowIterator.hasNext()){ - // get next row - Row row = rowIterator.nextRow(); - // get all values of row - Value[] values = row.getValues(); -}</programlisting> - </section> - <section id="sect-Reference_Guide-Query_Lifecycle-Scoring"> - <title>Scoring</title> - <para> - The result returns a score for each row in the result set. The score contains a value that indicates a rating of how well the result node matches the query. A high value means a better matching than a low value. This score can be used for ordering the result. - </para> - <para> - eXo JCR Scoring is a mapping of Lucene scoring. For a more in-depth understanding, please study <ulink url="http://lucene.apache.org/java/2_4_1/scoring.html">Lucene documentation</ulink>. - </para> - <para> - The <literal>jcr:score</literal> is calculated as; <literal>(lucene score)*1000f</literal>. - </para> - </section> - </section> - <section id="sect-Reference_Guide-JCR_Query_Usecases-Tips_and_tricks"> - <title>Tips and tricks</title> - <section xmlns="" id="sect-Reference_Guide-XPath_queries_containing_node_names_starting_with_a_number"> - <title>XPath queries containing node names starting with a number</title> - <para> - If you execute an XPath request like this... - </para> - <programlisting language="Java" role="Java">// get QueryManager -QueryManager queryManager = workspace.getQueryManager(); -// make XPath query -Query query = queryManager.createQuery("/jcr:root/Documents/Publie/2010//element(*, exo:article)", Query.XPATH);</programlisting> - <para> - ...you will receive an <code>Invalid request</code> error. This is because XML (and thus XPath) does not allow names starting with a number. - </para> - <para> - Therefore, XPath requests using a node name that starts with a number are invalid. - </para> - <para> - Some possible alternatives are: - </para> - <itemizedlist> - <listitem> - <para> - Use an SQL request. - </para> - </listitem> - <listitem> - <para> - Use escaping: - </para> - <programlisting language="Java" role="Java">// get QueryManager -QueryManager queryManager = workspace.getQueryManager(); -// make XPath query -Query query = queryManager.createQuery("/jcr:root/Documents/Publie/_x0032_010//element(*, exo:article)", Query.XPATH);</programlisting> - </listitem> - </itemizedlist> - </section> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-Searching_Repository_Content"> - <title>Searching Repository Content</title> - <section id="sect-Reference_Guide-Searching_Repository_Content-Introduction"> - <title>Introduction</title> - <para> - You can find the JCR configuration file here: <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. - </para> - <para> - Please refer to <xref linkend="chap-Reference_Guide-Search_Configuration"/> for more information about index configuration. - </para> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-Bi_directional_RangeIterator"> - <title>Bi-directional RangeIterator</title> - <para> - <literal>QueryResult.getNodes()</literal> will return bi-directional <literal>NodeIterator</literal> implementation. - </para> - <note> - <para> - Bi-directional NodeIterator is <emphasis role="bold">not supported</emphasis> in two cases: - </para> - <orderedlist> - <listitem> - <para> - SQL query: select * from nt:base - </para> - </listitem> - <listitem> - <para> - XPath query: //* . - </para> - </listitem> - </orderedlist> - </note> - <para> - <literal>TwoWayRangeIterator</literal> interface: - </para> - <programlisting language="Java" role="Java">/** - * Skip a number of elements in the iterator. - * - * @param skipNum the non-negative number of elements to skip - * @throws java.util.NoSuchElementException if skipped past the first element - * in the iterator. - */ -public void skipBack(long skipNum);</programlisting> - <para> - Usage: - </para> - <programlisting language="Java" role="Java">NodeIterator iter = queryResult.getNodes(); -while (iter.hasNext()) { - if (skipForward) { - iter.skip(10); // Skip 10 nodes in forward direction - } else if (skipBack) { - TwoWayRangeIterator backIter = (TwoWayRangeIterator) iter; - backIter.skipBack(10); // Skip 10 nodes back - } - ....... -}</programlisting> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-Fuzzy_Searches"> - <title>Fuzzy Searches</title> - <para> - The JBoss Portal Platform JCR supports features such as Lucene Fuzzy Searches. To perform a fuzzy search, form your query like the one below: - </para> - <programlisting language="Java" role="Java">QueryManager qman = session.getWorkspace().getQueryManager(); -Query q = qman.createQuery("select * from nt:base where contains(field, 'ccccc~')", Query.SQL); -QueryResult res = q.execute();</programlisting> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-SynonymSearch"> - <title>SynonymSearch</title> - <para> - Searching with synonyms is integrated in the <literal>jcr:contains()</literal> function and uses the same syntax as synonym searches in web search engines (Google, for example). If a search term is prefixed by a tilde symbol ( ~ ), synonyms of the search term are taken into consideration. For example: - </para> - <programlisting>SQL: select * from nt:resource where contains(., '~parameter') - -XPath: //element(*, nt:resource)[jcr:contains(., '~parameter')</programlisting> - <para> - This feature is disabled by default and you need to add a configuration parameter to the query-handler element in your JCR configuration file to enable it. - </para> - <programlisting language="XML" role="XML"><param name="synonymprovider-config-path" value="..you path to configuration file....."/> -<param name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider"/></programlisting> - <programlisting language="XML" role="XML">/** - * <code>SynonymProvider</code> defines an interface for a component that - * returns synonyms for a given term. - */ -public interface SynonymProvider { - - /** - * Initializes the synonym provider and passes the file system resource to - * the synonym provider configuration defined by the configuration value of - * the <code>synonymProviderConfigPath</code> parameter. The resource may be - * <code>null</code> if the configuration parameter is not set. - * - * @param fsr the file system resource to the synonym provider - * configuration. - * @throws IOException if an error occurs while initializing the synonym - * provider. - */ - public void initialize(InputStream fsr) throws IOException; - - /** - * Returns an array of terms that are considered synonyms for the given - * <code>term</code>. - * - * @param term a search term. - * @return an array of synonyms for the given <code>term</code> or an empty - * array if no synonyms are known. - */ - public String[] getSynonyms(String term); -}</programlisting> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-Highlighting"> - <title>Highlighting</title> - <para> - An <literal>ExcerptProvider</literal> retrieves text excerpts for a node in the query result and marks up the words in the text that match the query terms. - </para> - <para> - By default, match highlighting is disabled because as it requires that additional information is written to the search index. - </para> - <para> - To enable this feature, you need to add a configuration parameter to the <parameter>query-handler</parameter> element in your JCR configuration file: - </para> - <programlisting language="XML" role="XML"><param name="support-highlighting" value="true"/></programlisting> - <para> - Additionally, there is a parameter that controls the format of the excerpt created. In JCR 1.9, the default is set to <literal>org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt</literal>. The configuration parameter for this setting is: - </para> - <programlisting language="XML" role="XML"><param name="excerptprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.DefaultXMLExcerpt"/></programlisting> - <section id="sect-Reference_Guide-Highlighting-DefaultXMLExcerpt"> - <title>DefaultXMLExcerpt</title> - <para> - This excerpt provider creates an XML fragment of the following form: - </para> - <programlisting language="XML" role="XML"><excerpt> - <fragment> - <highlight>exoplatform</highlight> implements both the mandatory - XPath and optional SQL <highlight>query</highlight> syntax. - </fragment> - <fragment> - Before parsing the XPath <highlight>query</highlight> in - <highlight>exoplatform</highlight>, the statement is surrounded - </fragment> -</excerpt></programlisting> - </section> - <section id="sect-Reference_Guide-Highlighting-DefaultHTMLExcerpt"> - <title>DefaultHTMLExcerpt</title> - <para> - This excerpt provider creates an HTML fragment of the following form: - </para> - <programlisting language="HTML" role="HTML"><div> - <span> - <strong>exoplatform</strong> implements both the mandatory XPath - and optional SQL <strong>query</strong> syntax. - </span> - <span> - Before parsing the XPath <strong>query</strong> in - <strong>exoplatform</strong>, the statement is surrounded - </span> -</div></programlisting> - </section> - <section id="sect-Reference_Guide-Highlighting-Usage"> - <title>Usage</title> - <para> - If you are using XPath, you must use the <code>rep:excerpt()</code> function in the last location step, just like you would select properties: - </para> - <programlisting language="Java" role="Java">QueryManager qm = session.getWorkspace().getQueryManager(); -Query q = qm.createQuery("//*[jcr:contains(., 'exoplatform')]/(@Title|rep:excerpt(.))", Query.XPATH); -QueryResult result = q.execute(); -for (RowIterator it = result.getRows(); it.hasNext(); ) { - Row r = it.nextRow(); - Value title = r.getValue("Title"); - Value excerpt = r.getValue("rep:excerpt(.)"); -}</programlisting> - <para> - The above code searches for nodes that contain the word <emphasis>exoplatform</emphasis> and then gets the value of the <parameter>Title</parameter> property and an excerpt for each resultant node. - </para> - <para> - It is also possible to use a relative path in the call <code>Row.getValue()</code> while the query statement still remains the same. Also, you may use a relative path to a string property. The returned value will then be an excerpt based on string value of the property. - </para> - <para> - Both available excerpt providers will create fragments of about 150 characters and up to three fragments. - </para> - <para> - In SQL, the function is called <code>excerpt()</code> without the rep prefix, but the column in the <literal>RowIterator</literal> will nonetheless be labelled <code>rep:excerpt(.)</code>. - </para> - <programlisting language="Java" role="Java">QueryManager qm = session.getWorkspace().getQueryManager(); -Query q = qm.createQuery("select excerpt(.) from nt:resource where contains(., 'exoplatform')", Query.SQL); -QueryResult result = q.execute(); -for (RowIterator it = result.getRows(); it.hasNext(); ) { - Row r = it.nextRow(); - Value excerpt = r.getValue("rep:excerpt(.)"); -}</programlisting> - </section> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-SpellChecker"> - <title>SpellChecker</title> - <para> - The lucene based query handler implementation supports a pluggable spell-checker mechanism. By default, spell checking is not available, it must be configured first. - </para> - <para> - Information about the <parameter>spellCheckerClass</parameter> parameter is available in <xref linkend="chap-Reference_Guide-Search_Configuration"/>. - </para> - <para> - The JCR currently provides an implementation class which uses the <ulink url="http://wiki.apache.org/jakarta-lucene/SpellChecker">lucene-spellchecker</ulink>. - </para> - <para> - The dictionary is derived from the fulltext, indexed content of the workspace and updated periodically. You can configure the refresh interval by picking one of the available inner classes of <literal>org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker</literal>: - </para> - <itemizedlist> - <listitem> - <para> - <literal>OneMinuteRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>FiveMinutesRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>ThirtyMinutesRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>OneHourRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>SixHoursRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>TwelveHoursRefreshInterval</literal> - </para> - </listitem> - <listitem> - <para> - <literal>OneDayRefreshInterval</literal> - </para> - </listitem> - </itemizedlist> - <para> - For example, if you want a refresh interval of six hours, the class name would be; <literal>org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$SixHoursRefreshInterval</literal>. - </para> - <para> - If you use <literal>org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker</literal>, the refresh interval will be one hour. - </para> - <para> - The spell checker dictionary is stored as a lucene index under <filename><index-dir>/spellchecker</filename>. If this index does not exist, a background thread will create it on start up. Similarly, the dictionary refresh is also done in a background thread so as not to block regular queries. - </para> - <section id="sect-Reference_Guide-SpellChecker-Usage"> - <title>Usage</title> - <para> - You can spell check a fulltext statement either with an XPath or a SQL query: - </para> - <programlisting language="Java" role="Java">// rep:spellcheck('explatform') will always evaluate to true -Query query = qm.createQuery("/jcr:root[rep:spellcheck('explatform')]/(rep:spellcheck())", Query.XPATH); -RowIterator rows = query.execute().getRows(); -// the above query will always return the root node no matter what string we check -Row r = rows.nextRow(); -// get the result of the spell checking -Value v = r.getValue("rep:spellcheck()"); -if (v == null) { - // no suggestion returned, the spelling is correct or the spell checker - // does not know how to correct it. -} else { - String suggestion = v.getString(); -}</programlisting> - <para> - And the same using SQL: - </para> - <programlisting language="Java" role="Java">// SPELLCHECK('exoplatform') will always evaluate to true -Query query = qm.createQuery("SELECT rep:spellcheck() FROM nt:base WHERE jcr:path = '/' AND SPELLCHECK('explatform')", Query.SQL); -RowIterator rows = query.execute().getRows(); -// the above query will always return the root node no matter what string we check -Row r = rows.nextRow(); -// get the result of the spell checking -Value v = r.getValue("rep:spellcheck()"); -if (v == null) { - // no suggestion returned, the spelling is correct or the spell checker - // does not know how to correct it. -} else { - String suggestion = v.getString(); -}</programlisting> - </section> - </section> - <section id="sect-Reference_Guide-Searching_Repository_Content-Similarity"> - <title>Similarity</title> - <para> - Starting with version, 1.12 JCR allows you to search for nodes that are similar to an existing node. - </para> - <para> - Similarity is determined by looking up terms that are common to nodes. There are some conditions that must be met for a term to be considered. This is required to limit the number possibly relevant terms. - </para> - <para> - To be considered, terms must: - </para> - <itemizedlist> - <listitem> - <para> - Be at least four characters long. - </para> - </listitem> - <listitem> - <para> - Occur at least twice in the source node. - </para> - </listitem> - <listitem> - <para> - Occur in at least five other nodes. - </para> - </listitem> - </itemizedlist> - <note> - <title>Note</title> - <para> - The similarity function requires that the support Hightlighting is enabled. Please make sure that you have the following parameter set for the query handler in your <filename>workspace.xml</filename>. - </para> - <programlisting language="XML" role="XML"><param name="support-highlighting" value="true"/></programlisting> - </note> - <para> - The functions (<code>rep:similar()</code> in XPath and <code>similar()</code> in SQL) have two arguments: - </para> - <variablelist> - <title/> - <varlistentry> - <term>relativePath</term> - <listitem> - <para> - A relative path to a descendant node or a period (<literal>.</literal>) for the current node. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>absoluteStringPath</term> - <listitem> - <para> - A string literal that contains the path to the node for which to find similar nodes. - </para> - </listitem> - </varlistentry> - </variablelist> - <warning> - <title>Warning</title> - <para> - Relative path is not supported yet. - </para> - </warning> - <example id="exam-Reference_Guide-Similarity-Example"> - <title>Example</title> - <programlisting>//element(*, nt:resource)[rep:similar(., '/parentnode/node.txt/jcr:content')]</programlisting> - <para> - Finds <literal>nt:resource</literal> nodes, which are similar to node by path <filename>/parentnode/node.txt/jcr:content</filename>. - </para> - </example> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-Fulltext_Search_And_Affecting_Settings"> - <title>Full Text Search And Affecting Settings</title> - <formalpara id="form-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Property_content_indexing"> - <title>Property content indexing</title> - <para> - Each property of a node (if it is indexable) is processed with the Lucene analyzer and stored in the Lucene index. This is called indexing of a property. It allows fulltext searching of these indexed properties. - </para> - </formalpara> - <section id="sect-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Lucene_Analyzers"> - <title>Lucene Analyzers</title> - <para> - The purpose of analyzers is to transform all strings stored in the index into a well-defined condition. The same analyzer(s) is/are used when searching in order to adapt the query string to the index reality. - </para> - <para> - Therefore, performing the same query using different analyzers can return different results. - </para> - <para> - The example below illustrates how the same string is transformed by different analyzers. - </para> - <table id="tabl-Reference_Guide-Lucene_Analyzers-The_quick_brown_fox_jumped_over_the_lazy_dogs"> - <title>"The quick brown fox jumped over the lazy dogs"</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Analyzer </entry> - <entry> Parsed </entry> - </row> - </thead> - <tbody> - <row> - <entry> org.apache.lucene.analysis.WhitespaceAnalyzer </entry> - <entry> [The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.SimpleAnalyzer </entry> - <entry> [the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.StopAnalyzer </entry> - <entry> [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.standard.StandardAnalyzer </entry> - <entry> [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.snowball.SnowballAnalyzer </entry> - <entry> [quick] [brown] [fox] [jump] [over] [lazi] [dog] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.standard.StandardAnalyzer (configured without stop word - jcr default analyzer) </entry> - <entry> [the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] </entry> - </row> - </tbody> - </tgroup> - </table> - <table id="tabl-Reference_Guide-Lucene_Analyzers-XYampZ_Corporation_xyzexample.com"> - <title>"XY&Z Corporation - xyz(a)example.com"</title> - <tgroup cols="2"> - <thead> - <row> - <entry> Analyzer </entry> - <entry> Parsed </entry> - </row> - </thead> - <tbody> - <row> - <entry> org.apache.lucene.analysis.WhitespaceAnalyzer </entry> - <entry> [XY&Z] [Corporation] [-] [xyz(a)example.com] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.SimpleAnalyzer </entry> - <entry> [xy] [z] [corporation] [xyz] [example] [com] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.StopAnalyzer </entry> - <entry> [xy] [z] [corporation] [xyz] [example] [com] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.standard.StandardAnalyzer </entry> - <entry> [xy&z] [corporation] [xyz@example] [com] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.snowball.SnowballAnalyzer </entry> - <entry> [xy&z] [corpor] [xyz@exampl] [com] </entry> - </row> - <row> - <entry> org.apache.lucene.analysis.standard.StandardAnalyzer (configured without stop word - jcr default analyzer) </entry> - <entry> [xy&z] [corporation] [xyz@example] [com] </entry> - </row> - </tbody> - </tgroup> - </table> - <note> - <para> - <literal>StandardAnalyzer</literal> is the default analyzer in the JBoss Portal Platform JCR search engine. But it does not use stop words. - </para> - </note> - <para> - You can assign your analyzer as described in <xref linkend="chap-Reference_Guide-Search_Configuration"/>. - </para> - </section> - <section id="sect-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Property_Indexing"> - <title>Property Indexing</title> - <para> - Different properties are indexed in different ways and this affects whether it can be searched via fulltext by property or not. - </para> - <para> - Only two property types are indexed as fulltext searcheable: <parameter>STRING</parameter> and <parameter>BINARY</parameter>. - </para> - <table id="tabl-Reference_Guide-Property_Indexing-Fulltext_search_by_different_properties"> - <title>Fulltext search by different properties</title> - <tgroup cols="3"> - <thead> - <row> - <entry> Property Type </entry> - <entry> Fulltext search by all properties </entry> - <entry> Fulltext search by exact property </entry> - </row> - </thead> - <tbody> - <row> - <entry> STRING </entry> - <entry> YES </entry> - <entry> YES </entry> - </row> - <row> - <entry> BINARY </entry> - <entry> YES </entry> - <entry> NO </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - For example, the <literal>jcr:data</literal> property (which is <parameter>BINARY</parameter>) will not be found with a query structured as: - </para> - <programlisting>SELECT * FROM nt:resource WHERE CONTAINS(jcr:data, 'some string')</programlisting> - <para> - This is because, <parameter>BINARY</parameter> is not searchable by fulltext search by exact property. - </para> - <para> - However, the following query <emphasis>will</emphasis> return some results (provided, of course they node contains the targeted data): - </para> - <programlisting>SELECT * FROM nt:resource WHERE CONTAINS( * , 'some string')</programlisting> - </section> - <section id="sect-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Different_Analyzers"> - <title>Different Analyzers</title> - <para> - First of all, we will fill repository by nodes with mixin type 'mix:title' and different values of 'jcr:description' property. - </para> - <programlisting>root - ├── document1 (mix:title) jcr:description = "The quick brown fox jumped over the lazy dogs" - ├── document2 (mix:title) jcr:description = "Brown fox live in forest." - └── document3 (mix:title) jcr:description = "Fox is a nice animal." -</programlisting> - <para> - The example below shows different Analyzers in action. The first instance uses base JCR settings, so the string; "<emphasis>The quick brown fox jumped over the lazy dogs</emphasis>" will be transformed to the set; <emphasis role="bold">{[the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] }</emphasis>. - </para> - <programlisting language="Java" role="Java">// make SQL query -QueryManager queryManager = workspace.getQueryManager(); -String sqlStatement = "SELECT * FROM mix:title WHERE CONTAINS(jcr:description, 'the')"; -// create query -Query query = queryManager.createQuery(sqlStatement, Query.SQL); -// execute query and fetch result -QueryResult result = query.execute();</programlisting> - <para> - The <literal>NodeIterator</literal> will return <emphasis>document1</emphasis>. - </para> - <para> - However, if the default analyzer is changed to <literal>org.apache.lucene.analysis.StopAnalyzer</literal>, the repository populated again (the new Analyzer must process node properties) and the same query run, it will return nothing, because stop words like "<emphasis>the</emphasis>" will be excluded from parsed string set. - </para> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-WebDAV"> - <title>WebDAV</title> - <section id="sect-Reference_Guide-WebDAV-Introduction"> - <title>Introduction</title> - <para> - The <application>WebDAV</application> protocol enables you to use third party tools to communicate with hierarchical content servers via the HTTP protocol. It is possible to add and remove documents or a set of documents from a path on the server. - </para> - <para> - <application>DeltaV</application> is an extension of the WebDav protocol that allows managing document versioning. The <emphasis>Locking</emphasis> feature guarantees protection against multiple access when writing resources. The ordering support allows changing the position of the resource in the list and sort the directory to make the directory tree viewed conveniently. The full-text search makes it easy to find the necessary documents. You can search by using two languages: SQL and XPATH. - </para> - <para> - In the eXo JCR, the WebDAV layer (based on the code taken from the extension modules of the reference implementation) is plugged in on top of our JCR implementation. This makes it possible to browse a workspace using the third party tools regardless of operating system environments. You can use a Java WebDAV client, such as <application>DAVExplorer</application> or <application>Internet Explorer</application> using <menuchoice> - <guimenu>File</guimenu> - <guimenuitem>Open as a Web Folder</guimenuitem> - </menuchoice>. - </para> - <para> - WebDav is an extension of the REST service. To get the WebDav server ready, you must deploy the REST application. Then, you can access any workspaces of your repository by using the following URL: - </para> - <para> - <ulink url="http://host:port/portal/rest/private/jcr/{RepositoryName}/{WorkspaceName}..." type="http"/> - </para> - <para> - When accessing the WebDAV server via <ulink url="http://localhost:8080/rest/jcr/repository/production" type="http"/>, you can substitute <ulink url="http://localhost:8080/rest/jcr/repository/production" type="http">production</ulink> with <ulink url="http://localhost:8080/rest/jcr/repository/collaboration" type="http">collaboration</ulink>. - </para> - <para> - You will be asked to enter your login credentials. These will then be checked by using the organization service that can be implemented thanks to an InMemory (dummy) module or a DB module or an LDAP one and the JCR user session will be created with the correct JCR Credentials. - </para> - <note> - <title>Note:</title> - <para> - If you try the "in ECM" option, add "@ecm" to the user's password. Alternatively, you may modify jaas.conf by adding the <emphasis role="bold">domain=ecm</emphasis> option as follows: - </para> - <programlisting>exo-domain { - org.exoplatform.services.security.jaas.BasicLoginModule required domain=ecm; -};</programlisting> - </note> - </section> - <section id="sect-Reference_Guide-WebDAV-WebDAV_Configuration"> - <title>WebDAV Configuration</title> - <para> - The WebDAV configuration file: - </para> - <programlisting language="XML" role="XML"><component> - <key>org.exoplatform.services.webdav.WebDavServiceImpl</key> - <type>org.exoplatform.services.webdav.WebDavServiceImpl</type> - <init-params> - -  -  - -  - <value-param> - <name>auth-header</name> - <value>Basic realm="eXo-Platform Webdav Server 1.6.1"</value> - </value-param> - -  - <value-param> - <name>def-folder-node-type</name> - <value>nt:folder</value> - </value-param> - -  - <value-param> - <name>def-file-node-type</name> - <value>nt:file</value> - </value-param> - -  - <value-param> - <name>def-file-mimetype</name> - <value>application/octet-stream</value> - </value-param> - -  - - <value-param> - <name>update-policy</name> - <value>create-version</value> -  -  - </value-param> - -  - <value-param> - <name>auto-version</name> - <value>checkout-checkin</value> -  - </value-param> - -  - <value-param> - <name>cache-control</name> - <value>text/xml,text/html:max-age=3600;image/png,image/jpg:max-age=1800;*/*:no-cache;</value> - </value-param> - -  - <value-param> - <name>folder-icon-path</name> - <value>/absolute/path/to/file</value> - </value-param> - - </init-params> -</component></programlisting> - </section> - <section id="sect-Reference_Guide-WebDAV-Corresponding_WebDav_and_JCR_actions"> - <title>Corresponding WebDAV and JCR actions</title> - <table> - <title/> - <tgroup cols="2"> - <thead> - <row> - <entry> WebDav </entry> - <entry> JCR </entry> - </row> - </thead> - <tbody> - <row> - <entry> COPY </entry> - <entry> Workspace.copy(...) </entry> - </row> - <row> - <entry> DELETE </entry> - <entry> Node.remove() </entry> - </row> - <row> - <entry> GET </entry> - <entry> Node.getProperty(...); Property.getValue() </entry> - </row> - <row> - <entry> HEAD </entry> - <entry> Node.getProperty(...); Property.getLength() </entry> - </row> - <row> - <entry> MKCOL </entry> - <entry> Node.addNode(...) </entry> - </row> - <row> - <entry> MOVE </entry> - <entry> Session.move(...) or Workspace.move(...) </entry> - </row> - <row> - <entry> PROPFIND </entry> - <entry> Session.getNode(...); Node.getNode(...); Node.getNodes(...); Node.getProperties() </entry> - </row> - <row> - <entry> PROPPATCH </entry> - <entry> Node.setProperty(...); Node.getProperty(...).remove() </entry> - </row> - <row> - <entry> PUT </entry> - <entry> Node.addNode("node","nt:file"); Node.setProperty("jcr:data", "data") </entry> - </row> - <row> - <entry> CHECKIN </entry> - <entry> Node.checkin() </entry> - </row> - <row> - <entry> CHECKOUT </entry> - <entry> Node.checkout() </entry> - </row> - <row> - <entry> REPORT </entry> - <entry> Node.getVersionHistory(); VersionHistory.getAllVersions(); Version.getProperties() </entry> - </row> - <row> - <entry> RESTORE </entry> - <entry> Node.restore(...) </entry> - </row> - <row> - <entry> UNCHECKOUT </entry> - <entry> Node.restore(...) </entry> - </row> - <row> - <entry> VERSION-CONTROL </entry> - <entry> Node.addMixin("mix:versionable") </entry> - </row> - <row> - <entry> LOCK </entry> - <entry> Node.lock(...) </entry> - </row> - <row> - <entry> UNLOCK </entry> - <entry> Node.unlock() </entry> - </row> - <row> - <entry> ORDERPATCH </entry> - <entry> Node.orderBefore(...) </entry> - </row> - <row> - <entry> SEARCH </entry> - <entry> Workspace.getQueryManager(); QueryManager.createQuery(); Query.execute() </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section id="sect-Reference_Guide-WebDAV-WebDAV_Considerations"> - <title>WebDAV Considerations</title> - <para> - There are some restrictions for WebDAV in different operating systems. - </para> - <formalpara id="form-Reference_Guide-WebDAV_Considerations-Windows_7"> - <title>Windows 7</title> - <para> - When attempting to set up a web folder through <guilabel>Add a Network Location</guilabel> or <guilabel>Map a Network Drive</guilabel> through <guilabel>My Computer</guilabel>, an error message stating <guilabel>The folder you entered does not appear to be valid. Please choose another</guilabel> or <guilabel>Windows cannot access … Check the spelling of the name. Otherwise, there might be …</guilabel> may be encountered. These errors may appear when you are using SSL or non-SSL. - </para> - </formalpara> - <para> - To fix this, do as follows: - </para> - <procedure> - <step> - <para> - Go to Windows Registry Editor. - </para> - </step> - <step> - <para> - Find a key: \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlset\services\WebClient\Parameters\BasicAuthLevel . - </para> - </step> - <step> - <para> - Change the value to 2. - </para> - </step> - </procedure> - <formalpara id="form-Reference_Guide-WebDAV_Considerations-Microsoft_Office_2010"> - <title>Microsoft Office 2010</title> - <para> - If you have: - </para> - </formalpara> - <itemizedlist> - <listitem> - <para> - Microsoft Office 2007/2010 applications installed on a client computer AND... - </para> - </listitem> - <listitem> - <para> - The client computer is connected to a web server configured for Basic authentication VIA... - </para> - </listitem> - <listitem> - <para> - A connection that does not use Secure Sockets Layer (SSL) AND... - </para> - </listitem> - <listitem> - <para> - You try to access an Office file that is stored on the remote server... - </para> - </listitem> - <listitem> - <para> - You might experience the following symptoms when you try to open or to download the file: - </para> - <itemizedlist> - <listitem> - <para> - The Office file does not open or download. - </para> - </listitem> - <listitem> - <para> - You do not receive a Basic authentication password prompt when you try to open or to download the file. - </para> - </listitem> - <listitem> - <para> - You do not receive an error message when you try to open the file. The associated Office application starts. However, the selected file does not open. - </para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - <para> - These outcomes can be circumvented by enabling Basic authentication on the client machine. - </para> - <para> - To enable Basic authentication on the client computer, follow these steps: - </para> - <procedure> - <step> - <para> - Click Start, type <literal>regedit</literal> in the Start Search box, and then press Enter. - </para> - </step> - <step> - <para> - Locate and then click the following registry subkey: - </para> - <para> - <envar>HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Common\Internet</envar> - </para> - </step> - <step> - <para> - On the <guilabel>Edit</guilabel> menu, point to <guilabel>New</guilabel>, and then click <guilabel>DWORD Value</guilabel>. - </para> - </step> - <step> - <para> - Type <literal>BasicAuthLevel</literal>, and then press <keycap>Enter</keycap>. - </para> - </step> - <step> - <para> - Right-click <literal>BasicAuthLevel</literal>, and then click <guilabel>Modify</guilabel>. - </para> - </step> - <step> - <para> - In the Value data box, type <literal>2</literal>, and then click <guilabel>OK</guilabel>. - </para> - </step> - </procedure> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-FTP"> - <title>FTP</title> - <section id="sect-Reference_Guide-FTP-Introduction"> - <title>Introduction</title> - <para> - The JCR-FTP Server operates as an FTP server with access to a content stored in JCR repositories in the form of <literal>nt:file/nt:folder</literal> nodes or their successors. The client of an executed Server can be any FTP client. The FTP server is supported by a standard configuration which can be changed as required. - </para> - </section> - <section id="sect-Reference_Guide-FTP-Configuration_Parameters"> - <title>Configuration Parameters</title> - <variablelist id="vari-Reference_Guide-Configuration_Parameters-Parameters"> - <title>Parameters</title> - <varlistentry> - <term>command-port:</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>command-port</name> - <value>21</value> -</value-param></programlisting> - <para> - The value of the command channel port. The value '<literal>21</literal>' is default. - </para> - <para> - If you have already other FTP server installed in your system, this parameter needs to be changed (to <literal>2121</literal>, for example) to avoid conflicts or if the port is protected. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>data-min-port and data-max-port</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>data-min-port</name> - <value>52000</value> -</value-param></programlisting> - <programlisting language="XML" role="XML"><value-param> - <name>data-max-port</name> - <value>53000</value> -</value-param></programlisting> - <para> - These two parameters indicate the minimum and maximum values of the range of ports, used by the server. The usage of the additional data channel is required by the FTP protocol, which is used to transfer the contents of files and the listing of catalogues. This range of ports should be free from listening by other server-programs. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>system</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>system</name> - - <value>Windows_NT</value> - or - <value>UNIX Type: L8</value> -</value-param></programlisting> - <para> - Types of formats of listing of catalogues which are supported. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>client-side-encoding</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>client-side-encoding</name> - - <value>windows-1251</value> - or - <value>KOI8-R</value> - -</value-param></programlisting> - <para> - This parameter specifies the coding which is used for dialogue with the client. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>def-folder-node-type</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>def-folder-node-type</name> - <value>nt:folder</value> -</value-param></programlisting> - <para> - This parameter specifies the type of a node, when an FTP-folder is created. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>def-file-node-type</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>def-file-node-type</name> - <value>nt:file</value> -</value-param></programlisting> - <para> - This parameter specifies the type of a node, when an FTP-file is created. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>def-file-mime-type</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>def-file-mime-type</name> - <value>application/zip</value> -</value-param></programlisting> - <para> - The mime type of a created file is chosen by using its file extension. In case, a server cannot find the corresponding mime type, this value is used. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>cache-folder-name</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>cache-folder-name</name> - <value>../temp/ftp_cache</value> -</value-param></programlisting> - <para> - The Path of the cache folder. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>upload-speed-limit</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>upload-speed-limit</name> - <value>20480</value> -</value-param></programlisting> - <para> - Restriction of the upload speed. It is measured in bytes. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>download-speed-limit</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>download-speed-limit</name> - <value>20480</value> -</value-param></programlisting> - <para> - Restriction of the download speed. It is measured in bytes. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>timeout</term> - <listitem> - <programlisting language="XML" role="XML"><value-param> - <name>timeout</name> - <value>60</value> -</value-param></programlisting> - <para> - Defines the value of a timeout. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-Use_External_Backup_Tool"> - <title>Use External Backup Tool</title> - <section id="sect-Reference_Guide-Use_External_Backup_Tool-Repository_Suspending"> - <title>Repository Suspending</title> - <para> - To have the repository content consistent with the search index and value storage, the repository should be suspended. This means all working threads are suspended until a resume operation is performed. The index will be flushed. - </para> - <para> - JCR provides ability to suspend repository via JMX. - </para> - <figure> - <title id="repositorysuspendcontroller">Repository Suspend Controller</title> - <mediaobject> - <imageobject> - <imagedata width="444" fileref="images/repository-suspend-controller.png"/> - </imageobject> - </mediaobject> - </figure> - <para> - To suspend repository you need to invoke the <literal>suspend()</literal> operation. The returned result will be "<emphasis>suspended</emphasis>" if everything passed successfully. - </para> - <figure> - <title id="repository-suspend-controller-suspended.">Repository Suspend Controller Suspended</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/repository-suspend-controller-suspended.png"/> - </imageobject> - </mediaobject> - </figure> - <para> - An "<emphasis>undefined</emphasis>" result means not all components were successfully suspended. Check the console to review the stack traces. - </para> - </section> - <section id="sect-Reference_Guide-Use_External_Backup_Tool-Backup"> - <title>Backup</title> - <para> - You can backup your content manually or by using third part software. You should back up: - </para> - <itemizedlist> - <listitem> - <para> - Database. - </para> - </listitem> - <listitem> - <para> - Lucene index. - </para> - </listitem> - <listitem> - <para> - Value storage (if configured). - </para> - </listitem> - </itemizedlist> - </section> - <section id="sect-Reference_Guide-Use_External_Backup_Tool-Repository_Resuming"> - <title>Repository Resuming</title> - <para> - Once a backup is done you need to invoke the <literal>resume()</literal> operation to switch the repository back to on-line. The returned result will be "<emphasis>on-line</emphasis>". - </para> - <figure> - <title id="repository-suspend-controller-online.">Repository Suspend Controller Online</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/repository-suspend-controller-online.png"/> - </imageobject> - </mediaobject> - </figure> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-eXo_JCR_statistics"> - <title>eXo JCR statistics</title> - <section id="sect-Reference_Guide-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 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 the method has been called. - </para> - </listitem> - </itemizedlist> - <para> - Those figures are also available globally 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-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> 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> 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> 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> 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> 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> 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> 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> 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> close </entry> - <entry> This is the alias for the method <emphasis>close().</emphasis></entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section id="sect-Reference_Guide-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 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="https://repository.jboss.org/nexus/content/groups/public/org/exoplatform/...">https://repository.jboss.org/nexus/content/groups/public/org/exoplatform/...</ulink>. - </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"> - <uri>http://repo2.maven.org/maven2/org/aspectj/aspectjrt</uri> - </ulink>. - </para> - </listitem> - </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">http://repo2.maven.org/maven2/org/aspectj/aspectjweaver</ulink>. - </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-configuration.html">http://www.eclipse.org/aspectj/doc/released/devguide/ltw-configuration.html</ulink>. - </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"><configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"> - - <component> - <type>org.exoplatform.services.jcr.statistics.JCRAPIAspectConfig</type> - <init-params> - <values-param> - <name>targetInterfaces</name> - <value>org.exoplatform.services.jcr.core.ExtendedSession</value> - <value>org.exoplatform.services.jcr.core.ExtendedNode</value> - <value>javax.jcr.Property</value> - </values-param> - </init-params> - </component> -</configuration></programlisting> - <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"><aspectj> - <aspects> - <concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect"> - <pointcut name="JCRAPIPointcut" - expression="(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) && call(public * *(..))" /> - </concrete-aspect> - </aspects> - <weaver options="-XnoInline"> - <include within="org.exoplatform..*" /> - </weaver> -</aspectj></programlisting> - <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_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-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> 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> Times </entry> - <entry> The total amount of times the method has been called. </entry> - </row> - </tbody> - </tgroup> - </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-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 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 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 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> - </tbody> - </tgroup> - </table> - The full name of the related MBean is <literal>xo:service=statistic, view=jcr</literal>. - </para> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-Checking_repository_integrity_and_consistency"> - <title>Checking repository integrity and consistency</title> - <section id="sect-Reference_Guide-Checking_repository_integrity_and_consistency-JMX_based_consistency_tool"> - <title>JMX-based consistency tool</title> - <para> - It is important to check the integrity and consistency of system regularly, especially if there is no, or stale, backups. The JBoss Portal Platform JCR implementation offers an innovative JMX-based complex checking tool. - </para> - <para> - During an inspection, the tool checks every major JCR component, such as persistent data layer and the index. The persistent layer includes JDBC Data Container and Value-Storages if they are configured. - </para> - <para> - The database is verified using the set of complex specialized domain-specific queries. The Value Storage tool checks the existence of, and access to, each file. - </para> - <para> - Access to the check tool is exposed via the JMX interface, with the following operations available: - </para> - <table id="tabl-Reference_Guide-JMX_based_consistency_tool-Available_methods"> - <title>Available methods</title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - <code>checkRepositoryDataConsistency()</code> - </entry> - <entry> Inspect full repository data (db, value storage and search index) </entry> - </row> - <row> - <entry> - <code>checkRepositoryDataBaseConsistency()</code> - </entry> - <entry> Inspect only DB </entry> - </row> - <row> - <entry> - <code>checkRepositoryValueStorageConsistency()</code> - </entry> - <entry> Inspect only ValueStorage </entry> - </row> - <row> - <entry> - <code>checkRepositorySearchIndexConsistency()</code> - </entry> - <entry> Inspect only SearchIndex </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - All inspection activities and corrupted data details are stored in a file in the <filename>app</filename> directory and named as per the following convention: <code> report-<replaceable><repository name></replaceable>-<replaceable>dd-MMM-yy-HH-mm</replaceable>.txt </code>. - </para> - <para> - The path to the file will be returned in result message also at the end of the inspection. - </para> - <note> - <para> - There are three types of inconsistency (Warning, Error and Index) and two of them are critical (Errors and Index): - </para> - <itemizedlist> - <listitem> - <para> - Index faults are marked as "Reindex" and can be fixed by re-indexing the workspace. - </para> - </listitem> - <listitem> - <para> - Errors can only be fixed manually. - </para> - </listitem> - <listitem> - <para> - Warnings can be a normal situation in some cases and usually production system will still remain fully functional. - </para> - </listitem> - </itemizedlist> - </note> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-JCR_Performance_Tuning_Guide"> - <title>JCR Performance Tuning Guide</title> - <section id="sect-Reference_Guide-JCR_Performance_Tuning_Guide-Introduction"> - <title>Introduction</title> - <para> - This section will show you various ways of improving JCR performance. - </para> - <para> - It is intended for Administrators and others who want to use the JCR features more efficiently. - </para> - </section> - <section id="sect-Reference_Guide-JCR_Performance_Tuning_Guide-JCR_Performance_and_Scalability"> - <title>JCR Performance and Scalability</title> - <section id="sect-Reference_Guide-JCR_Performance_and_Scalability-Cluster_configuration"> - <title>Cluster configuration</title> - <para> - The table below contains details about the configuration of the cluster used in benchmark testing: - </para> - <table id="tabl-Reference_Guide-Cluster_configuration-EC2_network_1Gbit"> - <title>EC2 network: 1Gbit</title> - <tgroup cols="2"> - <colspec colname="1"/> - <colspec colname="2"/> - <spanspec namest="1" nameend="2" spanname="hspan"/> - <thead> - <row> - <entry> Servers hardware </entry> - <entry> Specification </entry> - </row> - </thead> - <tbody> - <row> - <entry> RAM </entry> - <entry> 7.5 GB </entry> - </row> - <row> - <entry> Processors </entry> - <entry> 4 EC2 Compute Units (2 virtual cores with 2 EC2 Compute Units each) </entry> - </row> - <row> - <entry> Storage </entry> - <entry> 850 GB (2×420 GB plus 10 GB root partition) </entry> - </row> - <row> - <entry> Architecture </entry> - <entry> 64-bit </entry> - </row> - <row> - <entry> I/O Performance </entry> - <entry> High </entry> - </row> - <row> - <entry> API name </entry> - <entry> - <literal>m1.large</literal> - </entry> - </row> - <row> - <entry spanname="hspan"> - <emphasis role="bold">Note:</emphasis> - </entry> - </row> - <row> - <entry spanname="hspan"> NFS and statistics (cacti snmp) server were located on one physical server. </entry> - </row> - <row> - <entry spanname="hspan"> - <emphasis role="bold">JBoss Enterprise Application Platform 6 configuration:</emphasis> - </entry> - </row> - <row> - <entry spanname="hspan"> - <code>JAVA_OPTS: -Dprogram.name=run.sh -server -Xms4g -Xmx4g -XX:MaxPermSize=512m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -XX:+UseParallelGC -Djava.net.preferIPv4Stack=true</code> - </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section id="sect-Reference_Guide-JCR_Performance_and_Scalability-JCR_Clustered_Performance"> - <title>JCR Clustered Performance</title> - <para> - Benchmark test using WebDAV (Complex read/write load test (benchmark)) with 20K same file. To obtain per-operation results we have used custom output from the test case threads to CSV file. - </para> - <para> - <citetitle>Read operation</citetitle>: - <simplelist> - <member>Warm-up iterations: 100</member> - <member>Run iterations: 2000</member> - <member>Background writing threads: 25</member> - <member>Reading threads: 225</member> - </simplelist> - - </para> - <figure> - <title id="perf_EC2_result">EC2 Performance Results</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/perf_EC2_results.jpg"/> - </imageobject> - </mediaobject> - </figure> - <table> - <title/> - <tgroup cols="4"> - <thead> - <row> - <entry> Nodes count </entry> - <entry> tps </entry> - <entry> Responses >2s </entry> - <entry> Responses >4s </entry> - </row> - </thead> - <tbody> - <row> - <entry> 1 </entry> - <entry> 523 </entry> - <entry> 6.87% </entry> - <entry> 1.27% </entry> - </row> - <row> - <entry> 2 </entry> - <entry> 1754 </entry> - <entry> 0.64% </entry> - <entry> 0.08% </entry> - </row> - <row> - <entry> 3 </entry> - <entry> 2388 </entry> - <entry> 0.49% </entry> - <entry> 0.09% </entry> - </row> - <row> - <entry> 4 </entry> - <entry> 2706 </entry> - <entry> 0.46% </entry> - <entry> 0.1% </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - <citetitle>Read operation with more threads</citetitle>: - </para> - <simplelist> - <member>Warm-up iterations: 100</member> - <member>Run iterations: 2000</member> - <member>Background writing threads: 50</member> - <member>Reading threads: 450</member> - </simplelist> - <figure> - <title id="perf_EC2_result2">EC2 Performance Results 2</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/perf_EC2_results_2.jpg"/> - </imageobject> - </mediaobject> - </figure> - <table> - <title/> - <tgroup cols="4"> - <thead> - <row> - <entry> Nodes count </entry> - <entry> tps </entry> - <entry> Responses >2s </entry> - <entry> Responses >4s </entry> - </row> - </thead> - <tbody> - <row> - <entry> 1 </entry> - <entry> 116 </entry> - <entry> ? </entry> - <entry> ? </entry> - </row> - <row> - <entry> 2 </entry> - <entry> 1558 </entry> - <entry> 6.1% </entry> - <entry> 0.6% </entry> - </row> - <row> - <entry> 3 </entry> - <entry> 2242 </entry> - <entry> 3.1% </entry> - <entry> 0.38% </entry> - </row> - <row> - <entry> 4 </entry> - <entry> 2756 </entry> - <entry> 2.2% </entry> - <entry> 0.41% </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - </section> - <section id="sect-Reference_Guide-JCR_Performance_Tuning_Guide-Performance_Tuning_Guide"> - <title>Performance Tuning Guide</title> - <section id="sect-Reference_Guide-Performance_Tuning_Guide-JBoss_AS_Tuning"> - <title>JBoss Enterprise Application Platform 6 Tuning</title> - <para> - You can use <parameter>maxThreads</parameter> parameter to increase maximum amount of threads that can be launched in AS instance. This can improve performance if you need a high level of concurrency. also you can use <code>-XX:+UseParallelGC</code> java directory to use parallel garbage collector. - </para> - <note> - <title>Note</title> - <para> - Beware of setting <parameter>maxThreads</parameter> too big, this can cause <exceptionname>OutOfMemoryError</exceptionname>. We've got it with <code>maxThreads=1250</code> on such machine: - </para> - <simplelist> - <member>7.5 GB memory</member> - <member>4 EC2 Compute Units (2 virtual cores with 2 EC2 Compute Units each)</member> - <member>850 GB instance storage (2×420 GB plus 10 GB root partition)</member> - <member>64-bit platform</member> - <member>I/O Performance: High</member> - <member>API name: m1.large</member> - <member>java -Xmx 4g</member> - </simplelist> - </note> - </section> - <section id="sect-Reference_Guide-Performance_Tuning_Guide-JCR_Cache_Tuning"> - <title>JCR Cache Tuning</title> - <para> - <citetitle>Cache size</citetitle> - </para> - <para> - JCR-cluster implementation is built using JBoss Cache as distributed, replicated cache. But there is one particularity related to remove action in it. Speed of this operation depends on the actual size of cache. As many nodes are currently in cache as much time is needed to remove one particular node (subtree) from it. - </para> - <para> - <citetitle>Eviction</citetitle> - </para> - <para> - Manipulations with eviction <parameter>wakeUpInterval</parameter> value does not affect on performance. Performance results with values from 500 up to 3000 are approximately equal. - </para> - <para> - <citetitle>Transaction Timeout</citetitle> - </para> - <para> - Using short timeout for long transactions such as Export/Import, removing huge subtree defined timeout may cause <exceptionname>TransactionTimeoutException</exceptionname>. - </para> - </section> - <section id="sect-Reference_Guide-Performance_Tuning_Guide-Clustering"> - <title>Clustering</title> - <para> - For performance it is better to have a load-balancer, DB server and shared NFS on different computers. If in some reasons you see that one node gets more load than others you can decrease this load using load value in load balancer. - </para> - <para> - <citetitle>JGroups configuration</citetitle> - </para> - <para> - It's recommended to use "multiplexer stack" feature present in JGroups. It is set by default in eXo JCR and offers higher performance in cluster, using less network connections also. If there are two or more clusters in your network, please check that they use different ports and different cluster names. - </para> - <para> - <citetitle>Write performance in cluster</citetitle> - </para> - <para> - Exo JCR implementation uses Lucene indexing engine to provide search capabilities. But Lucene brings some limitations for write operations: it can perform indexing only in one thread. That is why write performance in cluster is not higher than in singleton environment. Data is indexed on coordinator node, so increasing write-load on cluster may lead to ReplicationTimeout exception. It occurs because writing threads queue in the indexer and under high load timeout for replication to coordinator will be exceeded. - </para> - <para> - Taking in consideration this fact, it is recommended to exceed <parameter>replTimeout</parameter> value in cache configurations in case of high write-load. - </para> - <para> - <citetitle>Replication timeout</citetitle> - </para> - <para> - Some operations may take too much time. So if you get <exceptionname>ReplicationTimeoutException</exceptionname> try increasing replication timeout: - </para> - <programlisting language="XML" role="XML"> <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> - ... - <sync replTimeout="60000" /> - </clustering> -</programlisting> - <para> - value is set in milliseconds. - </para> - </section> - </section> - </section> - <section xmlns="" id="chap-Reference_Guide-eXo_JCR_with_GateIn"> - <title>eXo JCR with JBoss Portal Platform</title> - <section xmlns="" id="sect-Reference_Guide-How_to_use_AS_Managed_DataSource_under_JBoss_AS"> - <title>How to use a Managed DataSource under JBoss Enterprise Application Platform 6</title> - <section id="sect-Reference_Guide-How_to_use_AS_Managed_DataSource_under_JBoss_AS-Configurations_Steps"> - <title>Configurations Steps</title> - <section id="sect-Reference_Guide-Configurations_Steps-Declaring_the_datasources_in_the_AS"> - <title>Declaring the Datasources in the AS</title> - <remark>NEEDINFO - FILE PATHS - I know this isn't right. Where do these get deployed again?</remark> - <para> - To declare the datasources using a JBoss application server, deploy a <literal>ds</literal> file (<filename><replaceable>XXX</replaceable>-ds.xml</filename>) into the <emphasis>deploy</emphasis> directory of the appropriate server profile (<filename>/server/<replaceable>PROFILE</replaceable>/deploy</filename>, for example). - </para> - <para> - This file configures all datasources which JBoss Portal Platform will need (there should be four specifically named: <emphasis>jdbcjcr_portal</emphasis>, <emphasis>jdbcjcr_portal-sample</emphasis>, <emphasis>jdbcidm_portal</emphasis> and <emphasis>jdbcidm_sample-portal</emphasis>). - </para> - <para> - For example: - </para> - <programlisting language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?> -<datasources> - <no-tx-datasource> - <jndi-name>jdbcjcr_portal</jndi-name> - <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcjcr_portal</connection-url> - <driver-class>org.hsqldb.jdbcDriver</driver-class> - <user-name>sa</user-name> - <password></password> - </no-tx-datasource> - - <no-tx-datasource> - <jndi-name>jdbcjcr_sample-portal</jndi-name> - <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcjcr_sample-portal</connection-url> - <driver-class>org.hsqldb.jdbcDriver</driver-class> - <user-name>sa</user-name> - <password></password> - </no-tx-datasource> - - <no-tx-datasource> - <jndi-name>jdbcidm_portal</jndi-name> - <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcidm_portal</connection-url> - <driver-class>org.hsqldb.jdbcDriver</driver-class> - <user-name>sa</user-name> - <password></password> - </no-tx-datasource> - - <no-tx-datasource> - <jndi-name>jdbcidm_sample-portal</jndi-name> - <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcidm_sample-portal</connection-url> - <driver-class>org.hsqldb.jdbcDriver</driver-class> - <user-name>sa</user-name> - <password></password> - </no-tx-datasource> -</datasources></programlisting> - <para> - The properties can be set for datasource can be found here: <ulink url="http://docs.jboss.org/jbossas/docs/Server_Configuration_Guide/4/html/Conn...">Configuring JDBC DataSources - The non transactional DataSource configuration schema</ulink> - </para> - </section> - <section id="sect-Reference_Guide-Configurations_Steps-Do_not_bind_datasources_explicitly"> - <title>Do not bind datasources explicitly</title> - <para> - Do not let the portal explicitly bind datasources. </para> - <remark>NEEDINFO - FILE PATHS - I think some of the values have changed in the referenced file when I look at the new file below. New info required?</remark> - <para>Edit the <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/configuration.properties</filename> and comment out the following rows in the JCR section: - </para> - <programlisting>#gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver -#gatein.jcr.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr_${name} -#gatein.jcr.datasource.username=sa -#gatein.jcr.datasource.password=</programlisting> - <para> - Comment out the following lines in the IDM section: - </para> - <programlisting>#gatein.idm.datasource.driver=org.hsqldb.jdbcDriver -#gatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name} -#gatein.idm.datasource.username=sa -#gatein.idm.datasource.password=</programlisting> - <para> - Open the <filename>jcr-configuration.xml</filename> and <filename>idm-configuration.xml</filename> files and comment out references to the plug-in <literal>InitialContextInitializer</literal>. - </para> - <programlisting language="XML" role="XML"> -</programlisting> - </section> - </section> - </section> - </section> - </appendix> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appendix-Quickstarts.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/> </book><?xxe-serial-numbers hgd3icsl jmorgan (1z141z5 (-) (-) (-) (1z141z6 (1z141z7) (-) (-)) (1z141z8 (1z141z9) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Load_Groups.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Localization.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml 2013-05-08 05:35:47 UTC (rev 9274) +++ epp/docs/JPP/trunk/Development_Guide/en-US/Revision_History.xml 2013-05-08 07:02:26 UTC (rev 9275) @@ -7,7 +7,21 @@ <title>Revision History</title> <simpara> <revhistory> - <revision> + <revision> + <revnumber>6.1.0-5</revnumber> + <date>Wed May 8 2013</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Base eXo JCR content from Reference Guide ported over to this guide. Next task is to add the missing content and atomise the content.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.1.0-2</revnumber> <date>Fri Apr 19 2013</date> <author> Modified: epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml =================================================================== (Binary files differ) Added: epp/docs/JPP/trunk/Development_Guide/en-US/eXo_JCR.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/eXo_JCR.xml ___________________________________________________________________ Added: svn:mime-type + application/xml

11 years, 7 months

1
0
0 / 0

gatein SVN: r9274 - in epp/docs/JPP/trunk/User_Guide/en-US: modules and 3 other directories.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-05-08 01:35:47 -0400 (Wed, 08 May 2013) New Revision: 9274 Modified: epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/Introduction.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/Language.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/gadgetsAdmin/Manage_Portlets_and_Gadgets.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/language/Change_Interface_Language.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/language/Multi-Language_Navigation_Nodes.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/language/Right_To_Left_Support_(RTL).xml epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Pages.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Permission.xml epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/User_Management.xml Log: All Figures now have correct alt text appended to them. Modified: epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml 2013-05-08 05:35:04 UTC (rev 9273) +++ epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml 2013-05-08 05:35:47 UTC (rev 9274) @@ -8,8 +8,8 @@ <simpara> <revhistory> <revision> - <revnumber>6.1.0-1</revnumber> - <date>Tue Mar 05 2013</date> + <revnumber>6.1.0-2</revnumber> + <date>Tue Apr 30 2013</date> <author> <firstname>Jared</firstname> <surname>Morgan</surname> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/Introduction.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/Introduction.xml 2013-05-08 05:35:04 UTC (rev 9273) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/Introduction.xml 2013-05-08 05:35:47 UTC (rev 9274) @@ -27,7 +27,7 @@ <term>Technical documentation</term> <listitem> <para> - Other technical documentation, including an <emphasis role="bold">Installation Guide</emphasis>, a <emphasis role="bold">Reference Guide</emphasis> and component specific documentation, can be found at <ulink url="http://www.redhat.com/docs" type="http">www.redhat.com/docs</ulink> + Other technical documentation, including an <citetitle role="bold">Installation Guide</citetitle>, a <citetitle>Development Guide</citetitle>, and an <citetitle>Administration and Configuration Guide</citetitle> can be found at <ulink url="https://access.redhat.com/site/documentation/JBoss_Portal_Platform/" type="http"/> </para> </listitem> </varlistentry> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/Language.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/Language.xml 2013-05-08 05:35:04 UTC (rev 9273) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/Language.xml 2013-05-08 05:35:47 UTC (rev 9274) @@ -1,15 +1,11 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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" [ <!ENTITY % BOOK_ENTITIES SYSTEM "../User_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-User_Guide-Language_administration"> - <title>Language administration</title> - <xi:include href="language/Change_Interface_Language.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="language/Right_To_Left_Support_(RTL).xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="language/Multi-Language_Navigation_Nodes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -  + <title>Language administration</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="language/Change_Interface_Language.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="language/Right_To_Left_Support_(RTL).xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="language/Multi-Language_Navigation_Nodes.xml"/> </chapter> - Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/gadgetsAdmin/Manage_Portlets_and_Gadgets.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/gadgetsAdmin/Manage_Portlets_and_Gadgets.xml 2013-05-08 05:35:04 UTC (rev 9273) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/gadgetsAdmin/Manage_Portlets_and_Gadgets.xml 2013-05-08 05:35:47 UTC (rev 9274) @@ -46,9 +46,9 @@ <imageobject role="html"> <imagedata align="center" scale="100" fileref="images/Column.png" format="PNG"/> </imageobject> - <imageobject role="fo"> - <imagedata contentwidth="120mm" align="center" scalefit="1" fileref="images/Column.png" format="PNG"/> - </imageobject> + <textobject> + <phrase>The Dashboard Portlet menu, with the mouse pointer hovering over the pencil icon.</phrase> + </textobject> </mediaobject> </step> <step> @@ -180,9 +180,9 @@ <imageobject role="html"> <imagedata align="center" scale="100" fileref="images/AddPortlet2.png" format="PNG"/> </imageobject> - <imageobject role="fo"> - <imagedata contentwidth="140mm" align="center" scalefit="1" fileref="images/AddPortlet2.png" format="PNG"/> - </imageobject> + <textobject> + <phrase>The Categories window, with the Gadgets category expanded, and the mouse hovering over the Add application to category (plus sign) button.</phrase> + </textobject> </mediaobject> <variablelist> <varlistentry> @@ -307,9 +307,14 @@ <imageobject role="html"> <imagedata align="center" scale="100" fileref="images/AddGadgetnew.png" format="PNG"/> </imageobject> - <imageobject role="fo"> - <imagedata contentwidth="150mm" align="center" fileref="images/AddGadgetnew.png" format="PNG"/> - </imageobject> + <textobject> + <phrase>The <menuchoice> + <guimenu> Group</guimenu> + <guimenu> Administration</guimenu> + <guimenu> Application Registry</guimenu> + <guimenu> Gadget</guimenu> + </menuchoice> menu, with the mouse pointer hovering over the Add a remote gadget menu item.</phrase> + </textobject> </mediaobject> </step> <step> @@ -360,9 +365,9 @@ <imageobject role="html"> <imagedata align="center" scale="100" fileref="images/Source.png" format="PNG"/> </imageobject> - <imageobject role="fo"> - <imagedata contentwidth="150mm" align="center" fileref="images/Source.png" format="PNG"/> - </imageobject> + <textobject> + <phrase>The rssAggregator Gadget source window open, with the gadget code displayed.</phrase> + </textobject> </mediaobject> </section>  ways to create a key for a node: + There are two ways to create a key for a node: </para> <orderedlist numeration="arabic"> <listitem> @@ -72,9 +72,9 @@ <imageobject role="html"> <imagedata align="center" scale="110" fileref="images/PageWizard.png" format="PNG"/> </imageobject> - <imageobject role="fo"> - <imagedata contentwidth="160mm" align="center" scalefit="1" fileref="images/PageWizard.png" format="PNG"/> - </imageobject> + <textobject> + <phrase>The Page Creation Wizard window, at Wizard Step 1, with the Home navigation node selected.</phrase> + </textobject> </mediaobject> </step> <step> @@ -89,36 +89,7 @@ </step> </procedure> </section> - <section id="sect-User_Guide-Multi_Language_Navigation_Nodes-CreatingEditing_Keys_using_the_Edit_Page_and_Navigation"> + <section id="sect-User_Guide-Multi_Language_Navigation_Nodes-CreatingEditing_Keys_using_the_Edit_Page_and_Navigation"> <title>Creating/Editing Keys using <emphasis role="bold">Navigation Management</emphasis></title> <procedure> <step> @@ -149,182 +120,10 @@ <para> To provide a translation for the resource key used as page name, resource bundles must be provided within the web archive. </para> + <remark>Docs Note - jmorgan - This file path needs to be reviewed.</remark> <para> Property files (or XML resource bundles) must be located in: <filename>/jboss-as/server/<replaceable><PROFILE></replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/classes/locale/navigation/portal/<replaceable><PORTAL_NAME></replaceable>_<replaceable><LANGUAGE_CODE></replaceable>.properties</filename> </para> </section> -</section> +</section> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/language/Right_To_Left_Support_(RTL).xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/language/Right_To_Left_Support_(RTL).xml 2013-05-08 05:35:04 UTC (rev 9273) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/language/Right_To_Left_Support_(RTL).xml 2013-05-08 05:35:47 UTC (rev 9274) @@ -12,59 +12,8 @@ <imageobject role="html"> <imagedata align="center" scale="130" fileref="images/HomePage2.png" format="PNG"/> </imageobject> - <imageobject role="fo"> - <imagedata contentwidth="150mm" align="center" scalefit="1" fileref="images/HomePage2.png" format="PNG"/> - </imageobject> + <textobject> + <phrase>The Main portal screen, with the right-to-left Arabic language selected to demonstrate the support.</phrase> + </textobject> </mediaobject> -</section> +</section> Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Pages.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Pages.xml 2013-05-08 05:35:04 UTC (rev 9273) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Pages.xml 2013-05-08 05:35:47 UTC (rev 9274) @@ -26,9 +26,9 @@ <imageobject role="html"> <imagedata align="center" scale="100" fileref="images/Wizard1.png" format="PNG"/> </imageobject> - <imageobject role="fo"> - <imagedata contentwidth="150mm" align="center" fileref="images/Wizard1.png" format="PNG"/> - </imageobject> + <textobject> + <phrase>Page Creation Wizard window displayed, with the Home node selected, and the the Add a new page parameters group displayed.</phrase> + </textobject> </mediaobject> <para> In the left pane, you can navigate up and down the node/page structure. Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Permission.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Permission.xml 2013-05-08 05:35:04 UTC (rev 9273) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/Manage_Permission.xml 2013-05-08 05:35:47 UTC (rev 9274) @@ -1,379 +1,359 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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 "../../User_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-User_Guide-Manage_Permissions"> - <title>Manage Permissions</title> - <para> + <title>Manage Permissions</title> + <para> Permissions play an important part in accessing and performing actions in the Portal. Depending on these permissions assigned by an administrator, users gain access to various components and actions such as edit portals, pages or portlets. </para> - <para> + <para> Details about permission types and levels can be found in <xref linkend="sect-User_Guide-Permissions"/> </para> - - <section id="sect-User_Guide-Manage_Permission-Set_Portal_Permission"> - <title>Set Portal Permissions</title> - <variablelist> - <varlistentry> - <term><emphasis role="bold">New portals</emphasis></term> - <listitem> - <para> - Click on <menuchoice><guimenu>Site</guimenu></menuchoice> on the <guilabel>Toolbar</guilabel> , then click on <menuchoice><guimenuitem>Add New Portal</guimenuitem><guimenuitem>Permission Setting</guimenuitem></menuchoice> + <section id="sect-User_Guide-Manage_Permission-Set_Portal_Permission"> + <title>Set Portal Permissions</title> + <variablelist> + <varlistentry> + <term> + <emphasis role="bold">New portals</emphasis> + </term> + <listitem> + <para> + Click on <menuchoice> + <guimenu>Site</guimenu> + </menuchoice> on the <guilabel>Toolbar</guilabel> , then click on <menuchoice> + <guimenuitem>Add New Portal</guimenuitem> + <guimenuitem>Permission Setting</guimenuitem> + </menuchoice> </para> - - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis role="bold">Existing portals</emphasis></term> - <listitem> - <para> - On the Toolbar click <emphasis role="bold">Site</emphasis> then <emphasis role="bold">Edit Portal's Config</emphasis>. Then select the <emphasis role="bold">Permission Setting</emphasis> tab. + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis role="bold">Existing portals</emphasis> + </term> + <listitem> + <para> + On the Toolbar click <emphasis role="bold">Site</emphasis> then <emphasis role="bold">Edit Portal's Config</emphasis>. Then select the <emphasis role="bold">Permission Setting</emphasis> tab. </para> - </listitem> - </varlistentry> - </variablelist> - - - <section id="sect-User_Guide-Manage_Permission-Set_the_Access_Permission_on_a_Portal"> - <title>Set Access permissions</title> - - <note> - <title>Public access</title> - <para> + </listitem> + </varlistentry> + </variablelist> + <section id="sect-User_Guide-Manage_Permission-Set_the_Access_Permission_on_a_Portal"> + <title>Set Access permissions</title> + <note> + <title>Public access</title> + <para> If you do not want your Portal to be publicly accessible, make sure the <emphasis role="bold">Make it public</emphasis> check box is clear. - </para> - </note> - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/PortalPermission.png" format="PNG" align="center" scale="100" /> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/PortalPermission.png" format="PNG" align="center" contentwidth="150mm" /> - </imageobject> - </mediaobject> - - <para> + </para> + </note> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" scale="100" fileref="images/PortalPermission.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The Permission Setting tab, with the Make it public check box selected.</phrase> + </textobject> + </mediaobject> + <para> If <emphasis role="bold">Make it public</emphasis> is clear, you need to add permissions by member group. </para> - - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/PermissionSetting2.png" format="PNG" align="center" scale="100" /> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/PermissionSetting2.png" format="PNG" align="center" contentwidth="150mm" /> - </imageobject> - </mediaobject> - - <procedure> - <step> - <para> - Click <emphasis role="bold">Add Permission</emphasis> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" scale="100" fileref="images/PermissionSetting2.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The Select Permission window, with the group and membership options for the portal displayed.</phrase> + </textobject> + </mediaobject> + <procedure> + <step> + <para> + Click <emphasis role="bold">Add Permission</emphasis>. </para> - </step> - <step> - <para> + </step> + <step> + <para> Make the appropriate selections from the group and membership options presented in the <guilabel>Select Permission</guilabel> dialogue box. </para> - </step> - <step> - <para> + </step> + <step> + <para> After selecting a membership type, the selected permission is displayed in the access permission list. You can only select one group with one membership type at a time. If you want to add more, click <emphasis role="bold">Add Permission</emphasis> and select again. Repeat the process for as many permission settings as you require. </para> - </step> - </procedure> - - - - </section> - - <section id="sect-User_Guide-Manage_Permission-Set_the_Edit_Permission_on_a_Portal"> - - <title>Set Edit Permissions</title> - <para> + </step> + </procedure> + </section> + <section id="sect-User_Guide-Manage_Permission-Set_the_Edit_Permission_on_a_Portal"> + <title>Set Edit Permissions</title> + <para> Only members of the Editor group can edit that portal. Access rights can be given to several groups but edit rights can only be given to a group with a membership type. To assign an edit permission to a user, you must add him/her to the editor group of the respective portal. </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> Click <emphasis role="bold">Edit Permission Setting</emphasis> </para> - </step> - - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">Select Permission</emphasis> to choose a group. </para> - </step> - <step> - <para> + </step> + <step> + <para> Select a group and a membership type from the left and right panes, respectively, of the <emphasis role="bold">Permission Selector</emphasis> window (select * if you want to assign all available membership types to the selected group). </para> - </step> - - </procedure> - </section> - + </step> + </procedure> </section> - - - - - - - - <section id="sect-User_Guide-Manage_Permission-Set_Page_Permission"> - <title>Set Page Permission</title> - <variablelist> - <varlistentry> - <term><emphasis role="bold">Group</emphasis></term> - <listitem> - <para> - If the Owner type of a page is "group", initial permissions on page are: + </section> + <section id="sect-User_Guide-Manage_Permission-Set_Page_Permission"> + <title>Set Page Permission</title> + <variablelist> + <varlistentry> + <term> + <emphasis role="bold">Group</emphasis> + </term> + <listitem> + <para> + If the Owner type of a page is "group", initial permissions on page are: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Access permission: everyone in that group. </para> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Edit permission: the manager of that group. </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis role="bold">Portal</emphasis></term> - <listitem> - <para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis role="bold">Portal</emphasis> + </term> + <listitem> + <para> If the Owner type of a page is portal, initial permissions are: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Access permission: users who can access that portal. </para> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Edit permission: users who can edit that portal. </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - - <section id="sect-User_Guide-Manage_Permission-Set_the_Access_Permission_on_a_Page"> - <title>Set Access Permission on a Page</title> - - <procedure> - <step> - <para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + <section id="sect-User_Guide-Manage_Permission-Set_the_Access_Permission_on_a_Page"> + <title>Set Access Permission on a Page</title> + <procedure> + <step> + <para> Open up the page you wish to configure. Select <emphasis role="bold">Site Editor</emphasis> on the Toolbar and select <emphasis role="bold">Edit Page</emphasis>. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">View Page Properties</emphasis> in the <emphasis role="bold">Page Editor</emphasis>. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click the <emphasis role="bold">Permission Setting</emphasis> tab. </para> - <para> + <para> To be able to access a page users have to be in one of the groups that have access permission to that page. There may be several groups that have access rights to a page. A list of the permissions for that page will be shown (provided the <emphasis role="bold">Make it public</emphasis> check-box has not been used). </para> - </step> - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">Add Permission</emphasis> </para> - </step> - <step> - <para> + </step> + <step> + <para> Select a group in the left pane then select a membership type. </para> - </step> - <step> - <para> + </step> + <step> + <para> After selecting a membership type, the selected permission is displayed in the access right list. Note that you may associate group and membership only one at a time. To add more access permissions, click the <emphasis role="bold">Add Permission</emphasis> button and apply the same process again. </para> - </step> - </procedure> - <para> + </step> + </procedure> + <para> If you want to allow any visitors to access the page tick the <emphasis role="bold">Make it public</emphasis> check-box. Any permission set for that page will be relaxed and the permissions list will disappear. </para> - - </section> - - <section id="sect-User_Guide-Manage_Permission-Set_the_Edit_Permission_on_a_Page"> - <title>Set Edit Permission on a Page</title> - <para> - Only users who are in the page's editor group can edit it. The access right can be set for several groups but the edit right only can be set for one group. To give a user the edit permission, you must add them to the editors group of that page. + </section> + <section id="sect-User_Guide-Manage_Permission-Set_the_Edit_Permission_on_a_Page"> + <title>Set Edit Permission on a Page</title> + <para> + Only users who are in the page's editor group can edit it. The access right can be set for several groups but the edit right only can be set for one group. To give a user the edit permission, you must add them to the editors group of that page. </para> - <para> + <para> The Permission Setting tab is available in two different ways: </para> - <procedure> - <title>Via Edit Page:</title> - <step> - <para> + <procedure> + <title>Via Edit Page:</title> + <step> + <para> Mouse over <emphasis role="bold">Site Editor</emphasis> on the Toolbar and select <emphasis role="bold">Edit Page</emphasis>. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click on <emphasis role="bold">View Page Properties</emphasis> in the <emphasis role="bold">Page Editor</emphasis>. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click the <emphasis role="bold">Permission Setting</emphasis> tab then the <emphasis role="bold">Edit Permission Setting</emphasis> sub tab. </para> - </step> - </procedure> - <procedure> - <title>Via Page Management:</title> - <step> - <para> + </step> + </procedure> + <procedure> + <title>Via Page Management:</title> + <step> + <para> Mouse over <emphasis role="bold">Group</emphasis> on the Toolbar, highlight <emphasis role="bold">Administration</emphasis> and click on <emphasis role="bold">Page Management</emphasis>. </para> - </step> - <step> - <para> + </step> + <step> + <para> Locate the page you want to edit using the <emphasis role="bold">Page Id</emphasis> column then click the edit icon (next to the trash icon). You will be taken to the <emphasis role="bold">Page Editor</emphasis>. - </para> - </step> - <step> - <para> + </para> + </step> + <step> + <para> Click on <emphasis role="bold">View Page Properties</emphasis> in the <emphasis role="bold">Page Editor</emphasis>. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click on the <emphasis role="bold">Permission Setting</emphasis> tab then the <emphasis role="bold">Edit Permission Setting</emphasis> sub tab. </para> - <para> + <para> You will see the <emphasis role="bold">Current Permission</emphasis> listed. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click the <emphasis role="bold">Select Permission</emphasis> button to set new or change another group. </para> - </step> - <step> - <para> + </step> + <step> + <para> Select a group with a membership type (select * if you want all membership types in a selected group) </para> - </step> - <step> - <para> + </step> + <step> + <para> After selecting a specific membership from the right, the selected information is displayed. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click the <emphasis role="bold">Save</emphasis> </para> - </step> - </procedure> - </section> - + </step> + </procedure> </section> - - <section id="sect-User_Guide-Manage_Permission-Set_the_Access_Permission_on_a_Category"> - <title>Set Access Permission on a Category</title> - <para> + </section> + <section id="sect-User_Guide-Manage_Permission-Set_the_Access_Permission_on_a_Category"> + <title>Set Access Permission on a Category</title> + <para> Setting access permission on a category allows to be able to list those categories when editing a page in order to add portlets or gadgets. </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> Mouse over <emphasis role="bold">Group</emphasis> on the Toolbar, highlight <emphasis role="bold">Administration</emphasis> then click on <emphasis role="bold">Application Registry</emphasis>. </para> - </step> - <step> - <para> + </step> + <step> + <para> In the list of categories available in the left pane, click the edit icon, then choose the <emphasis role="bold">Permission Setting</emphasis> tab. </para> - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/EditCategoryPermissions.png" format="PNG" align="center" scale="100" /> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/EditCategoryPermissions.png" format="PNG" align="center" contentwidth="150mm" /> - </imageobject> - </mediaobject> - </step> - <step> - <para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" scale="100" fileref="images/EditCategoryPermissions.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The Permission Setting tab of the Application Registry group focused, with the groups displayed.</phrase> + </textobject> + </mediaobject> + </step> + <step> + <para> To set permissions for a category: </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> Click the <emphasis role="bold">Add Permission</emphasis> button to add access permissions to more groups. </para> - </step> - <step> - <para> + </step> + <step> + <para> Or select the <emphasis role="bold">Make it public</emphasis> check box to allow everyone to access. </para> - </step> - </procedure> - </step> - </procedure> - </section> - - <section id="sect-User_Guide-Manage_Permission-Set_the_Access_Permission_on_a_Portlet"> - <title>Set Access Permission on a Portlet</title> - <procedure> - <step> - <para> + </step> + </procedure> + </step> + </procedure> + </section> + <section id="sect-User_Guide-Manage_Permission-Set_the_Access_Permission_on_a_Portlet"> + <title>Set Access Permission on a Portlet</title> + <procedure> + <step> + <para> Select <emphasis role="bold">Group</emphasis> on the Toolbar. Highlight the <emphasis role="bold">Administration</emphasis> entry and click on <emphasis role="bold">Application Registry</emphasis>. <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/Application1.png" format="PNG" align="center" scale="100" /> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/Application1.png" format="PNG" align="center" contentwidth="150mm" /> - </imageobject> - </mediaobject> + <imageobject role="html"> + <imagedata align="center" scale="100" fileref="images/Application1.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The Application Registry window, with the Administration group open in the left pane, and the Application Registry details displayed.</phrase> + </textobject> + </mediaobject> </para> - </step> - <step> - <para> + </step> + <step> + <para> Select a category on the left pane that includes the portlet you want to set rights for. Then all portlets of the selected category are listed immediately and detail information of each portlet is displayed on the right pane. </para> - </step> - <step> - <para> + </step> + <step> + <para> To set permissions for a portlet: </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> Click the <emphasis role="bold">Add Permission</emphasis> button to add access permissions to more groups . </para> - </step> - <step> - <para> + </step> + <step> + <para> Or select the <emphasis role="bold">Make it public</emphasis> check box to allow everyone to access. </para> - </step> - </procedure> - </step> - </procedure> - </section> - + </step> + </procedure> + </step> + </procedure> + </section> </section> - - Modified: epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/User_Management.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/User_Management.xml 2013-05-08 05:35:04 UTC (rev 9273) +++ epp/docs/JPP/trunk/User_Guide/en-US/modules/portal/User_Management.xml 2013-05-08 05:35:47 UTC (rev 9274) @@ -1,55 +1,53 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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 "../../User_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-User_Guide-User_management"> - <title>Manage Users and Groups</title> - - <para> + <title>Manage Users and Groups</title> + <para> Several tools are offered to assist Administrators manage users, groups and memberships easily and effectively. </para> - -  - <xi:include href="EPP_Roles.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <section id="sect-User_Guide-User_Management-Manage_users"> - <title>Manage users</title> - <para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="EPP_Roles.xml"/> + <section id="sect-User_Guide-User_Management-Manage_users"> + <title>Manage users</title> + <para> Mouse over <emphasis role="bold">Group</emphasis> in the Toolbar. Highlight <emphasis role="bold">Organization</emphasis> and select <emphasis role="bold">Users and Groups Management</emphasis> </para> - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/UserManage.png" format="PNG" align="center" scale="100" /> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/UserManage.png" format="PNG" align="center" contentwidth="150mm" /> - </imageobject> - </mediaobject> - <para> - Administrators can see all existing registered users and search, edit or even delete them. Each user's groups and memberships (roles) in these groups are also available. + <mediaobject> + <imageobject role="html"> + <imagedata align="center" scale="100" fileref="images/UserManage.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The <menuchoice> + <guimenu>Group</guimenu> + <guimenu>Organization</guimenu> + <guimenu>Users and Groups Management</guimenu> + </menuchoice> User Management window with the default portal user profiles displayed. </phrase> + </textobject> + </mediaobject> + <para> + Administrators can see all existing registered users and search, edit or even delete them. Each user's groups and memberships (roles) in these groups are also available. </para> - - - <section id="sect-User_Guide-User_Management-Add_a_user"> - <title>Add a user</title> - <para> + <section id="sect-User_Guide-User_Management-Add_a_user"> + <title>Add a user</title> + <para> To add a new user to the portal user lists follow these steps: </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> Mouse over <emphasis role="bold">Group</emphasis> in the <emphasis role="bold">Toolbar</emphasis>. </para> - </step> - <step> - <para> + </step> + <step> + <para> Highlight <emphasis role="bold">Organization</emphasis> and then click on <emphasis role="bold">New Staff</emphasis>. </para> - <para> + <para> The <emphasis role="bold">New Staff</emphasis> window will open: </para> -  - <para> + --> <para> This window has two tabs; <emphasis role="bold">Account Setting</emphasis> and <emphasis role="bold">User Profile</emphasis>. </para> - </step> - <step> - <para> + </step> + <step> + <para> To create a new user, all fields on the <emphasis role="bold">Account Settings</emphasis> tab that are marked with an asterisk must be filled in. The <emphasis role="bold">Display Name</emphasis> field is optional and when left blank, a value in format <emphasis><First Name> <Last Name></emphasis> is used. </para> - <para> + <para> Further information about the user (such as nickname and birthday) can be added in the <emphasis role="bold">User Profile</emphasis> tab. This information is not required for the creation of the account. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click either <emphasis role="bold">Save</emphasis> or <emphasis role="bold">Reset</emphasis> to create or discard the new account. </para> - </step> - </procedure> - </section> - - <section id="sect-User_Guide-User_Management-Search_a_user"> - <title>Search for users</title> - <para> + </step> + </procedure> + </section> + <section id="sect-User_Guide-User_Management-Search_a_user"> + <title>Search for users</title> + <para> The Administrator can search for specific users by username, first name, last name or email address. </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> Mouse over <guilabel>Group</guilabel> in the Toolbar. Highlight <guilabel>Organization</guilabel> and select <guilabel>Users and Groups Management</guilabel>. </para> - </step> - <step> - <para> + </step> + <step> + <para> Select the information type (name, email, etc) to search against </para> - </step> - <step> - <para> + </step> + <step> + <para> Type in a partial/full string which identifies the user record being searched. The <emphasis role="bold">*</emphasis> character can be used as a wild-card. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click the magnifying glass icon to begin the search. </para> - </step> - </procedure> - </section> - - <section id="sect-User_Guide-User_Management-Edit_a_user"> - <title>Edit a user</title> - <procedure> - <step> - <para> + </step> + </procedure> + </section> + <section id="sect-User_Guide-User_Management-Edit_a_user"> + <title>Edit a user</title> + <procedure> + <step> + <para> Locate the user you wish to edit. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click the edit icon (next to the trash icon). </para> - </step> - <step> - <para> + </step> + <step> + <para> Select the <emphasis role="bold">Account Info</emphasis> tab to edit the main user information set including first name, last name or email address. </para> - <variablelist> - <varlistentry> - <term>User Name</term> - <listitem> - <para> - The <emphasis role="bold">User Name</emphasis> field cannot be changed. Other fields — <emphasis role="bold">First Name</emphasis>, <emphasis role="bold">Last Name</emphasis>, <emphasis role="bold">Display Name</emphasis> and <emphasis role="bold">Email Address</emphasis> — can be changed. + <variablelist> + <varlistentry> + <term>User Name</term> + <listitem> + <para> + The <emphasis role="bold">User Name</emphasis> field cannot be changed. Other fields — <emphasis role="bold">First Name</emphasis>, <emphasis role="bold">Last Name</emphasis>, <emphasis role="bold">Display Name</emphasis> and <emphasis role="bold">Email Address</emphasis> — can be changed. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Change Password</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>Change Password</term> + <listitem> + <para> The <emphasis role="bold">Change Password</emphasis> option allows an administrator to set a new password for a user. When the <emphasis role="bold">Change Password</emphasis> option is unchecked, <emphasis role="bold">New Password</emphasis> and <emphasis role="bold">Confirm Password</emphasis> are hidden. Passwords must contain between 6 and 30 characters. </para> - </listitem> - </varlistentry> - </variablelist> - </step> - <step> - <para> - Select the <emphasis role="bold">User Profile</emphasis> tab to edit additional information about the user's profile such as the birthdate or the job title as well as some home and business metadata. You may also switch the default display language for that user. + </listitem> + </varlistentry> + </variablelist> + </step> + <step> + <para> + Select the <emphasis role="bold">User Profile</emphasis> tab to edit additional information about the user's profile such as the birthdate or the job title as well as some home and business metadata. You may also switch the default display language for that user. </para> - </step> - <step> - <para> - Select the <emphasis role="bold">User Membership</emphasis> tab to see a user's group membership information. + </step> + <step> + <para> + Select the <emphasis role="bold">User Membership</emphasis> tab to see a user's group membership information. </para> - <variablelist> - <varlistentry> - <term>User Membership</term> - <listitem> - <para> - The <emphasis role="bold">User Membership</emphasis> tab displays which group(s) the selected user belongs to. In the above figure, the user "demo" is a member of two groups: "guests" and "users". The parent group of both is "platform". + <variablelist> + <varlistentry> + <term>User Membership</term> + <listitem> + <para> + The <emphasis role="bold">User Membership</emphasis> tab displays which group(s) the selected user belongs to. In the above figure, the user "demo" is a member of two groups: "guests" and "users". The parent group of both is "platform". </para> - <para> + <para> To remove the user from a group, click the trash can icon. </para> - </listitem> - </varlistentry> - </variablelist> - </step> - <step> - <para> + </listitem> + </varlistentry> + </variablelist> + </step> + <step> + <para> Click the <emphasis role="bold">Save</emphasis>. </para> - </step> - </procedure> - </section> - - <section id="sect-User_Guide-User_Management-Delete_a_user"> - <title>Delete a user</title> - <procedure> - <step> - <para> + </step> + </procedure> + </section> + <section id="sect-User_Guide-User_Management-Delete_a_user"> + <title>Delete a user</title> + <procedure> + <step> + <para> Locate the user you wish to delete - </para> - <para> + </para> + <para> Click the trash icon in the Action column </para> - </step> - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">OK</emphasis> to confirm. </para> - </step> - </procedure> - </section> - + </step> + </procedure> </section> - - <section id="sect-User_Guide-User_Management-Manage_groups"> - <title>Manage groups</title> - <para> + </section> + <section id="sect-User_Guide-User_Management-Manage_groups"> + <title>Manage groups</title> + <para> Mouse over <emphasis role="bold">Group</emphasis> on the Toolbar. Highlight <emphasis role="bold">Organization</emphasis> and select <emphasis role="bold">Users and Groups Management</emphasis> </para> - <para>Select the tab <emphasis role="bold">Group Management</emphasis></para> - <para> + <para>Select the tab <emphasis role="bold">Group Management</emphasis></para> + <para> By default, all existing groups will be displayed on the left pane. This tab is used to add new, edit or delete a group. The right pane shows information about the selected group including information about the members in the specific group along with a small form to add a new user to a group. </para> - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/GroupManage.png" format="PNG" align="center" scale="100" /> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/GroupManage.png" format="PNG" align="center" contentwidth="150mm" /> - </imageobject> - </mediaobject> - <section id="sect-User_Guide-User_Management-Add_a_new_group"> - <title>Add a New Group</title> - <procedure> - <step> - <para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" scale="100" fileref="images/GroupManage.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The <menuchoice> + <guimenu>Group</guimenu> + <guimenu>Organization</guimenu> + <guimenu>Users and Groups Management</guimenu> + </menuchoice> Groups Management window displayed.</phrase> + </textobject> + </mediaobject> + <section id="sect-User_Guide-User_Management-Add_a_new_group"> + <title>Add a New Group</title> + <procedure> + <step> + <para> First choose where in the existing group structure you want the new group to be created. You may navigate up the tree by clicking on the green vertical little arrow at the top of the tree. The current path is displayed in the path bar. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">Add New Group</emphasis>. </para> - <variablelist> - <varlistentry> - <term><emphasis role="bold">Group Name</emphasis></term> - <listitem> - <para> + <variablelist> + <varlistentry> + <term> + <emphasis role="bold">Group Name</emphasis> + </term> + <listitem> + <para> The name of the new group. This field is required and any length from 3 to 30 characters is allowed. Once saved this name cannot be edited. </para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis role="bold">Label</emphasis></term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis role="bold">Label</emphasis> + </term> + <listitem> + <para> The display name of the group. Any length from 3 to 30 characters is allowed. </para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis role="bold">Description</emphasis></term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis role="bold">Description</emphasis> + </term> + <listitem> + <para> A description of the group. Any length from 0 to 255 characters is allowed. </para> - </listitem> - </varlistentry> - </variablelist> - </step> - <step> - <para> + </listitem> + </varlistentry> + </variablelist> + </step> + <step> + <para> Fill in the required fields. Only letters, numbers, dash and underscore characters are allowed for the <guilabel>Group Name</guilabel> field. The name must be unique within the portal. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">Save</emphasis> </para> - </step> - </procedure> - </section> - - <section id="sect-User_Guide-User_Management-Edit-a-group"> - <title>Edit a group</title> - <procedure> - <step> - <para> + </step> + </procedure> + </section> + <section id="sect-User_Guide-User_Management-Edit-a-group"> + <title>Edit a group</title> + <procedure> + <step> + <para> Find the group in the existing tree and click on the label </para> - </step> - <step> - <para> + </step> + <step> + <para> Click the edit icon to display the <emphasis role="bold">Edit Selected Group</emphasis> window. </para> - </step> - <step> - <para> + </step> + <step> + <para> Make the desired changes in the appropriate fields. You can not change the Group Name, however you may change to the <emphasis role="bold">Label</emphasis> field. You are also able to edit the <emphasis role="bold">Description</emphasis> field. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">Save</emphasis> </para> - </step> - </procedure> - </section> - - <section id="sect-User_Guide-User_Management-Add_a_new_user_to_a_group"> - <title>Add a new user to a group</title> - <procedure> - <step> - <para> + </step> + </procedure> + </section> + <section id="sect-User_Guide-User_Management-Add_a_new_user_to_a_group"> + <title>Add a new user to a group</title> + <procedure> + <step> + <para> Find the group in the existing tree and click on its label. Existing group memberships are listed on the right hand side along with the <emphasis role="bold">Add Member</emphasis> window. </para> - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/AddMember1.png" format="PNG" align="center" scale="100" /> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/AddMember1.png" format="PNG" align="center" contentwidth="150mm" /> - </imageobject> - </mediaobject> - </step> - <step> - <para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" scale="100" fileref="images/AddMember1.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The Add member modal window displayed over the Group Management window.</phrase> + </textobject> + </mediaobject> + </step> + <step> + <para> Click on the magnify glass to open up the User selector. </para> - <para> - Refer to <xref linkend="sect-User_Guide-User_Management-Search_a_user" /> for instructions on how to locate a user. + <para> + Refer to <xref linkend="sect-User_Guide-User_Management-Search_a_user"/> for instructions on how to locate a user. </para> - <para> + <para> Check the box next to the user name then click <emphasis role="bold">Add</emphasis> </para> - </step> - <step> - <para> + </step> + <step> + <para> Select the membership appropriate for this user. If the desired membership does not appear you may try to click on the refresh icon to get the latest list. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">Save</emphasis> </para> - </step> - </procedure> - </section> - - <section id="sect-User_Guide-User_Management-Edit_the_user_membership_in_a_group"> - <title>Edit the user membership in a group</title> - <procedure> - <step> - <para> + </step> + </procedure> + </section> + <section id="sect-User_Guide-User_Management-Edit_the_user_membership_in_a_group"> + <title>Edit the user membership in a group</title> + <procedure> + <step> + <para> Click the edit icon in the Action column. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Select another membership. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">Save</emphasis>. </para> - </step> - </procedure> - </section> - - <section id="sect-User_Guide-User_Management-Delete_a_group"> - <title>Delete a group</title> - <procedure> - <step> - <para> + </step> + </procedure> + </section> + <section id="sect-User_Guide-User_Management-Delete_a_group"> + <title>Delete a group</title> + <procedure> + <step> + <para> Find the group in the tree </para> - </step> - <step> - <para> + </step> + <step> + <para> Click the trash icon. </para> - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/DeleteGroup.png" format="PNG" align="center" scale="100" /> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/DeleteGroup.png" format="PNG" align="center" contentwidth="150mm" /> - </imageobject> - </mediaobject> - </step> - <step> - <para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" scale="100" fileref="images/DeleteGroup.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The Group Management window, with the mouse pointer hovering over the Delete Selected Group button. The Partners group is highlighted.</phrase> + </textobject> + </mediaobject> + </step> + <step> + <para> Click <emphasis role="bold">OK</emphasis>. </para> - </step> - </procedure> - </section> - + </step> + </procedure> </section> - - <section id="sect-User_Guide-User_Management-Manage_memberships"> - <title>Manage memberships</title> - <para> + </section> + <section id="sect-User_Guide-User_Management-Manage_memberships"> + <title>Manage memberships</title> + <para> The role of a user in a specific group is managed using memberships. </para> - <para> + <para> By default three membership types are available: <emphasis>Manager</emphasis>, <emphasis>Member</emphasis> and <emphasis>Validator</emphasis>. By definition, Manager has got the highest rights in a group. </para> - <para> + <para> Mouse over <emphasis role="bold">Group</emphasis> on the Toolbar. Highlight <emphasis role="bold">Organization</emphasis> and select <emphasis role="bold">Users and Groups Management</emphasis>. Select the <emphasis role="bold">Membership Management</emphasis> tab. </para> - <para> + <para> This tab remembers the last action taken by a user in this page. Clicking <emphasis role="bold">Reset</emphasis> will clear any legacy details. </para> - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/MembershipManage1.png" format="PNG" align="center" scale="100" /> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/MembershipManage1.png" format="PNG" align="center" contentwidth="110mm"/> - </imageobject> - </mediaobject> - - <section id="sect-User_Guide-User_Management-Add_a_new_membership_type"> - <title>Add a new membership type</title> - <procedure> - <step> - <para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" scale="100" fileref="images/MembershipManage1.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The <menuchoice> + <guimenu>Group</guimenu> + <guimenu>Organization</guimenu> + <guimenu>Users and Groups Management</guimenu> + </menuchoice> Membership Management window, with the Add/Edit Membership fields displayed. </phrase> + </textobject> + </mediaobject> + <section id="sect-User_Guide-User_Management-Add_a_new_membership_type"> + <title>Add a new membership type</title> + <procedure> + <step> + <para> In the <emphasis role="bold">Add/Edit Membership</emphasis> form, enter the values for the membership name field (required) and the description field (optional). Only letters, digits, dots, dashes and underscores are allowed for the membership name and it must be between 3 and 30 characters. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click the <emphasis role="bold">Save</emphasis> </para> - </step> - </procedure> - </section> - - <section id="sect-User_Guide-User_Management-Edit_a_membership_type"> - <title>Edit a membership type</title> - <procedure> - <step> - <para> + </step> + </procedure> + </section> + <section id="sect-User_Guide-User_Management-Edit_a_membership_type"> + <title>Edit a membership type</title> + <procedure> + <step> + <para> Click the edit icon in the Action column. </para> - </step> - <step> - <para> + </step> + <step> + <para> Make the desired changes to the description. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">Save</emphasis> </para> - </step> - </procedure> - </section> - - <section id="sect-User_Guide-User_Management-Delete_a_membership_type"> - <title>Delete a membership type</title> - <procedure> - <step> - <para> + </step> + </procedure> + </section> + <section id="sect-User_Guide-User_Management-Delete_a_membership_type"> + <title>Delete a membership type</title> + <procedure> + <step> + <para> Click the trash icon in the Action column. </para> - </step> - <step> - <para> + </step> + <step> + <para> Click <emphasis role="bold">OK</emphasis> </para> - </step> - </procedure> - </section> + </step> + </procedure> </section> - + </section> </section>

11 years, 7 months

1
0
0 / 0

gatein SVN: r9273 - in epp/docs/JPP/trunk/Reference_Guide/en-US: modules and 1 other directory.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-05-08 01:35:04 -0400 (Wed, 08 May 2013) New Revision: 9273 Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/Reference_Guide.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/eXoJCR.xml Log: eXo JCR portion commented out of the guide Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/Reference_Guide.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/Reference_Guide.xml 2013-05-08 04:22:10 UTC (rev 9272) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/Reference_Guide.xml 2013-05-08 05:35:04 UTC (rev 9273) @@ -8,14 +8,11 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/Introduction.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/ServerIntegration.xml"/> -  - - <part> + <part> <title>Web Services for Remote Portlets (WSRP)</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/WSRP.xml"/> </part> -  - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/eXoJCR.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/eXoJCR.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/> </book> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/eXoJCR.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/eXoJCR.xml 2013-05-08 04:22:10 UTC (rev 9272) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/eXoJCR.xml 2013-05-08 05:35:04 UTC (rev 9273) @@ -5,29 +5,5629 @@ ]> <part id="part-Reference_Guide-The_Java_Content_Repository_"> <title>The Java Content Repository (JCR)</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/intro.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/concepts/jcr-exo-implementation.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/exo-jcr-configuration.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/multilanguage-support.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/search-configuration.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/jdbc-data-container-config.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/external-value-storages.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/workspace-persistence-storage.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/cluster-config.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/jbosscache-configuration-templates.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/lock-manager-config.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/query-handler-config.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/jbossts-transaction-service.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/searching/jcr-query-usecases.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/searching/searching-repository-content.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/searching/fulltext-search-and-settings.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/protocols/webdav.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/protocols/ftp.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/backup/use-external-backup-tool.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/statistics.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/repository-check-controller.xml"/> + <chapter xmlns="" id="chap-Reference_Guide-eXoJCR-Introduction"> + <title>Introduction</title> + <warning> + <title>eXo JCR usage</title> + <para> + The JBoss Portal Platform is using a JCR API to store its information for internal usage. We do not support usage of the JCR to store application information. + </para> + <para> + The information below is intended to assist users to understand particular low level details on how the JBoss Portal Platform works and how it can be fine-tuned. + </para> + </warning> + <para> + The term <emphasis role="bold">JCR</emphasis> refers to the Java Content Repository. The JCR is the data store of JBoss Portal Platform. All content is stored and managed via the JCR. + </para> + <para> + The eXo JCR included with JBoss Portal Platform &VY; is a (<ulink url="http://www.jcp.org/en/jsr/detail?id=170" type="http">JSR-170</ulink>) compliant implementation of the JCR 1.0 specification. The JCR provides versioning, textual search, access control, content event monitoring, and is used to storing text and binary data for the portal internal usage. The back-end storage of the JCR is configurable and can be a file system or a database. + </para> + <section id="sect-Reference_Guide-Introduction-Concepts"> + <title>Concepts</title> + <variablelist> + <varlistentry> + <term>Repository</term> + <listitem> + <para> + A repository is a form of data storage device. A 'repository' differs from a 'database' in the nature of the information contained. While a database holds hard data in rigid tables, a repository may access the data on a database by using less rigid <emphasis>meta</emphasis>-data. In this sense a repository operates as an 'interpreter' between the database(s) and the user. + </para> + <note> + <para> + The data model for the interface (the repository) is rarely the same as the data model used by the repository's underlying storage subsystems (such as a database), however the repository is able to make persistent data changes in the storage subsystem. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term>Workspace</term> + <listitem> + <para> + The eXo JCR uses 'workspaces' as the main data abstraction in its data model. The content is stored in a workspace as a hierarchy of <emphasis>items</emphasis> and each workspace has its own hierarchy of items. + </para> + <para> + Repositories access one or more workspaces. Persistent JCR workspaces consist of a directed acyclic graph of <emphasis>items</emphasis> where the edges represent the parent-child relation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Items</term> + <listitem> + <para> + An <emphasis>item</emphasis> is either a <emphasis>node</emphasis> or a <emphasis>property</emphasis>. Properties contain the data (either simple values or binary data). The nodes of a workspace give it its structure while the properties hold the data itself. + </para> + <variablelist> + <varlistentry> + <term>Nodes</term> + <listitem> + <para> + Nodes are identified using accepted <emphasis>namespacing</emphasis> conventions. Changed nodes may be versioned through an associated version graph to preserve data integrity. + </para> + <para> + Nodes can have various properties or child nodes associated to them. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Properties</term> + <listitem> + <para> + Properties hold data as values of predefined types, such as: <emphasis role="bold">String</emphasis>, <emphasis role="bold">Binary</emphasis>, <emphasis role="bold">Long</emphasis>, <emphasis role="bold">Boolean</emphasis>, <emphasis role="bold">Double</emphasis>, <emphasis role="bold">Date</emphasis>, <emphasis role="bold">Reference</emphasis> and <emphasis role="bold">Path</emphasis>. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>The Data Model</term> + <listitem> + <para> + The core of any Content Repository is the data model. The data model defines the 'data elements' (fields, columns, attributes, etc.) that are stored in the CR and the relationships between these elements. + </para> + <para> + Data elements can be singular pieces of information (the value 3.14, for example), or compound values ('<emphasis>pi</emphasis>' = 3.14). A data model uses concepts like 'nodes', 'arrays' and 'links' to define relationships between data elements. + </para> + <para> + The use and structure of these elements forms the content repository's 'data model'. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Data Abstraction</term> + <listitem> + <para> + Data abstraction describes the separation between <emphasis>abstract</emphasis> and <emphasis>concrete</emphasis> properties of data stored in a repository. The <emphasis>concrete</emphasis> properties of the data refer to its implementation details. + </para> + <para> + The <emphasis>concrete</emphasis> properties of the data implementation may be changed without affecting the <emphasis>abstract</emphasis> properties of the data itself, which are read by the data client. + </para> + <para> + Consider the presentation of data in a list, graph or table. While the information <emphasis>implementation</emphasis> may change, the data itself is unaffected, and readers to whom the data is presented can perform a mental abstraction to interpret it correctly, regardless of the implementation. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-Implementation"> + <title>Implementation</title> + <para> + The relationships between the eXo Repository Service components are illustrated below: + </para> + <figure> + <title id="exojcr">Exo JCR</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/eXoJCR/concepts/exojcr.gif"/> + </imageobject> + </mediaobject> + </figure> + <variablelist id="vari-Reference_Guide-Implementation-Definitions"> + <title>Definitions</title> + <varlistentry> + <term>eXo Container:</term> + <listitem> + <para> + A subclass of <parameter>org.exoplatform.container.ExoContainer</parameter> (<parameter>org.exoplatform.container.PortalContainer</parameter>) holds a reference to the Repository Service. + </para> + <variablelist> + <title/> + <varlistentry> + <term>Repository Service</term> + <listitem> + <para> + This contains information about repositories. eXo JCR is able to manage many Repositories. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Repository</term> + <listitem> + <para> + An implementation of <literal>javax.jcr.Repository</literal>. It holds references to one or more Workspace(s). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Workspace</term> + <listitem> + <para> + Container of a single rooted tree of Items. + </para> + <note> + <title>Note:</title> + <para> + That here it is not exactly the same as <literal>javax.jcr.Workspace</literal> as it is not a per Session object. + </para> + </note> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + <para> + The usual JCR application usecase includes two initial steps: + </para> + <procedure> + <step> + <para> + Obtaining Repository object by getting <emphasis role="bold">Repository Service</emphasis> via JNDI lookup if eXo repository is bound to the naming context using (see <xref linkend="chap-Reference_Guide-JCR_configuration"/> for details). + </para> + </step> + <step> + <para> + Creating a <parameter>javax.jcr.Session object</parameter> that calls <parameter>Repository.login(..)</parameter>. + </para> + </step> + </procedure> + <section id="sect-Reference_Guide-Implementation-Workspace_Data_Model"> + <title>Workspace Data Model</title> + <para> + The following diagram explains which components of a eXo JCR implementation are used in a data flow to perform operations specified in the JCR API. + </para> + <figure> + <title id="wsdatamodel">Workspace Data Model</title> + <mediaobject> + <imageobject> + <imagedata width="444" fileref="images/eXoJCR/concepts/wsdatamodel.gif"/> + </imageobject> + </mediaobject> + </figure> + <para> + The Workspace Data Model can be split into four levels by data isolation and value from the JCR model point of view. + </para> + <itemizedlist> + <listitem> + <para> + The eXo JCR core implements <emphasis role="bold">JCR API</emphasis> interfaces, such as Item, Node, Property. It contains JCR "<emphasis>logical</emphasis>" view on stored data. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Session Level</emphasis>: isolates transient data viewable inside one JCR Session and interacts with API level using eXo JCR internal API. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Session Data Manager</emphasis>: maintains transient session data. With data access/ modification/ validation logic, it contains Modified Items Storage to hold the data changed between subsequent save() calling and Session Items Cache. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Transaction Data Manager</emphasis>: maintains session data between save() and transaction commit/ rollback if the current session is part of a transaction. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Workspace Level</emphasis>: operates for particular workspace shared data. It contains per-Workspace objects + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Workspace Storage Data Manager:</emphasis> maintains workspace data, including final validation, events firing, caching. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Workspace Data Container</emphasis>: implements physical data storage. It allows different types of backend (like RDB, FS files, etc) to be used as a storage for JCR data. With the main Data Container, other storages for persisted Property Values can be configured and used. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Indexer:</emphasis> maintains workspace data indexing for further queries. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Storage Level</emphasis>: Persistent storages for: + </para> + <itemizedlist> + <listitem> + <para> + JCR Data + </para> + </listitem> + <listitem> + <para> + Indexes (Apache Lucene) + </para> + </listitem> + <listitem> + <para> + Values (e.g., for BLOBs) if different from the main Data Container + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-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="XML" role="XML"><!ELEMENT repository-service (repositories)> +<!ATTLIST repository-service default-repository NMTOKEN #REQUIRED> +<!ELEMENT repositories (repository)> +<!ELEMENT repository (security-domain,access-control,session-max-age,authentication-policy,workspaces)> +<!ATTLIST repository + default-workspace NMTOKEN #REQUIRED + name NMTOKEN #REQUIRED + system-workspace NMTOKEN #REQUIRED +> +<!ELEMENT security-domain (#PCDATA)> +<!ELEMENT access-control (#PCDATA)> +<!ELEMENT session-max-age (#PCDATA)> +<!ELEMENT authentication-policy (#PCDATA)> +<!ELEMENT workspaces (workspace+)> +<!ELEMENT workspace (container,initializer,cache,query-handler)> +<!ATTLIST workspace name NMTOKEN #REQUIRED> +<!ELEMENT container (properties,value-storages)> +<!ATTLIST container class NMTOKEN #REQUIRED> +<!ELEMENT value-storages (value-storage+)> +<!ELEMENT value-storage (properties,filters)> +<!ATTLIST value-storage class NMTOKEN #REQUIRED> +<!ELEMENT filters (filter+)> +<!ELEMENT filter EMPTY> +<!ATTLIST filter property-type NMTOKEN #REQUIRED> +<!ELEMENT initializer (properties)> +<!ATTLIST initializer class NMTOKEN #REQUIRED> +<!ELEMENT cache (properties)> +<!ATTLIST cache + enabled NMTOKEN #REQUIRED + class NMTOKEN #REQUIRED +> +<!ELEMENT query-handler (properties)> +<!ATTLIST query-handler class NMTOKEN #REQUIRED> +<!ELEMENT access-manager (properties)> +<!ATTLIST access-manager class NMTOKEN #REQUIRED> +<!ELEMENT lock-manager (time-out,persister)> +<!ELEMENT time-out (#PCDATA)> +<!ELEMENT persister (properties)> +<!ELEMENT properties (property+)> +<!ELEMENT property EMPTY></programlisting> + <section id="sect-Reference_Guide-JCR_configuration-Portal_configuration"> + <title><remark>BZ#812412 </remark>Portal configuration</title> + <para> + JCR services are registered in the Portal container. + </para> + <remark>NEEDINFO - FILE PATHS - The path needs to be updated with the equivalent path for JBoss Portal Platform instead of gatein, please see below para. New info required?</remark> + <para> + Below is an example configuration from the <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/jcr-configuration.xml</filename> file. + </para> + <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/jcr-configuration.xml" parse="text"/></programlisting> + <section id="sect-Reference_Guide-Portal_configuration-JCR_Configuration"> + <title>JCR Configuration</title> + <para> + The JCR Service can use multiple <emphasis>Repositories</emphasis> and each repository can have multiple <emphasis>Workspaces</emphasis>. + <remark>NEEDINFO - FILE PATHS - The path needs to be updated with the equivalent path for JBoss Portal Platform instead of gatein, please see below para. New info required?</remark> </para> + <para> + Configure the workspaces by locating the workspace you need to modify in <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.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> + <emphasis role="bold">M</emphasis> or <emphasis role="bold">MB</emphasis> for megabytes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">G</emphasis> or <emphasis role="bold">GB</emphasis> for gigabytes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">T</emphasis> or <emphasis role="bold">TB</emphasis> for terabytes. + </para> + </listitem> + <listitem> + <para> + Examples: 200K or 200KB; 4M or 4MB; 1.4G or 1.4GB; 10T or 10TB. + </para> + </listitem> + </itemizedlist> + + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Time formats:</term> + <listitem> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">ms</emphasis> for milliseconds. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">s</emphasis> for seconds. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">m</emphasis> for minutes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">h</emphasis> for hours. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">d</emphasis> for days. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">w</emphasis> for weeks. + </para> + </listitem> + <listitem> + <para> + The default time format is seconds if no other format is specified. + </para> + </listitem> + <listitem> + <para> + Examples: 500ms or 500 milliseconds; 20, 20s or 20 seconds; 30m or 30 minutes; 12h or 12 hours; 5d or 5 days; 4w or 4 weeks. + </para> + </listitem> + </itemizedlist> + + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Repository_service_configuration_JCR_repositories_configuration"> + <title>Repository service configuration (JCR repositories configuration)</title> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/orig.xml" parse="text"/></programlisting> + <note> + <title> + <parameter> session-max-age </parameter> + </title> + <para> + <emphasis>session-max-age</emphasis>: This parameter is not shown in the example 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> + <para> + <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> + <section id="sect-Reference_Guide-Portal_configuration-Workspace_configuration"> + <title>Workspace configuration:</title> + <variablelist> + <title/> + <varlistentry> + <term>name</term> + <listitem> + <para> + The name of a workspace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>auto-init-root-nodetype</term> + <listitem> + <para> + DEPRECATED in JCR 1.9 (use initializer). The node type for root node initialization. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>container</term> + <listitem> + <para> + Workspace data container (physical storage) configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>initializer</term> + <listitem> + <para> + Workspace initializer configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>cache</term> + <listitem> + <para> + Workspace storage cache configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>query-handler</term> + <listitem> + <para> + Query handler configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>auto-init-permissions</term> + <listitem> + <para> + 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 and the type of permission. + </para> + <para> + For example, any read; <literal>:/admin read;</literal>:/admin add_node; <literal>:/admin set_property;</literal>:/admin remove means that users from group <literal>admin</literal> have all permissions and other users have only a 'read' permission. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Workspace_data_container_configuration"> + <title>Workspace data container configuration:</title> + <variablelist> + <title/> + <varlistentry> + <term>class</term> + <listitem> + <para> + A workspace data container class name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> + The list of properties (name-value pairs) for the concrete Workspace data container. + </para> + </listitem> + </varlistentry> + </variablelist> + <table id="tabl-Reference_Guide-Workspace_data_container_configuration-Parameter_Descriptions"> + <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 descendants on rename or not. It allows to increase performance on rename operation but in same time Observation is 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> + <variablelist> + <title/> + <varlistentry> + <term>value-storage</term> + <listitem> + <para> + The list of value storage plug-ins. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Value_Storage_plugin_configuration_for_data_container"> + <title>Value Storage plug-in configuration (for data container):</title> + <note> + <para> + The value-storage element is optional. If you do not include it, the values will be stored as BLOBs inside the database. + </para> + </note> + <variablelist> + <title/> + <varlistentry> + <term>value-storage</term> + <listitem> + <para> + Optional value Storage plug-in definition. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>class</term> + <listitem> + <para> + A value storage plug-in class name (attribute). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> + The list of properties (name-value pairs) for a concrete Value Storage plug-in. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>filters</term> + <listitem> + <para> + The list of filters defining conditions when this plug-in is applicable. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Initializer_configuration_optional"> + <title>Initializer configuration (optional):</title> + <variablelist> + <title/> + <varlistentry> + <term>class</term> + <listitem> + <para> + Initializer implementation class. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> + The list of properties (name-value pairs). Properties are supported. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>root-nodetype</term> + <listitem> + <para> + The node type for root node initialization. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>root-permissions</term> + <listitem> + <para> + Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities (user, group etc, see Organization service documentation for details) and the type of permission. For example any read; <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> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Cache_configuration"> + <title>Cache configuration:</title> + <variablelist> + <title/> + <varlistentry> + <term>enabled</term> + <listitem> + <para> + If workspace cache is enabled or not. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>class</term> + <listitem> + <para> + Cache implementation class, optional from 1.9. Default value is. <literal>org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl</literal>. + </para> + <para> + Cache can be configured to use concrete implementation of WorkspaceStorageCache interface. JCR core has two implementation to use: + </para> + <itemizedlist> + <listitem> + <para> + LinkedWorkspaceStorageCacheImpl - default, with configurable read behavior and statistic. + </para> + </listitem> + <listitem> + <para> + WorkspaceStorageCacheImpl - pre 1.9, still can be used. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> + The list of properties (name-value pairs) for Workspace cache. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>max-size</term> + <listitem> + <para> + Cache maximum size (maxSize prior to v.1.9). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>live-time</term> + <listitem> + <para> + Cached item live time (liveTime prior to v.1.9). + </para> + <para> + From 1.9 <literal>LinkedWorkspaceStorageCacheImpl</literal> supports additional optional parameters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>statistic-period</term> + <listitem> + <para> + Period (time format) of cache statistic thread execution, 5 minutes by default. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>statistic-log</term> + <listitem> + <para> + If true cache statistic will be printed to default logger (log.info), false by default or not. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>statistic-clean</term> + <listitem> + <para> + If true cache statistic will be cleaned after was gathered, false by default or not. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>cleaner-period</term> + <listitem> + <para> + Period of the eldest items remover execution, 20 minutes by default. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>blocking-users-count</term> + <listitem> + <para> + Number of concurrent users allowed to read cache storage, 0 - unlimited by default. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Query_Handler_configuration"> + <title>Query Handler configuration:</title> + <variablelist> + <title/> + <varlistentry> + <term>class</term> + <listitem> + <para> + A Query Handler class name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> + The list of properties (name-value pairs) for a Query Handler (indexDir). + </para> + <para> + Properties and advanced features described in Search Configuration. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Lock_Manager_configuration"> + <title>Lock Manager configuration:</title> + <variablelist> + <title/> + <varlistentry> + <term>time-out</term> + <listitem> + <para> + Time after which the unused global lock will be removed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>persister</term> + <listitem> + <para> + A class for storing lock information for future use. For example, remove lock after jcr restart. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>path</term> + <listitem> + <para> + A lock folder. Each workspace has its own one. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-Multi_language_Support_the_JCR_RDB"> + <title>Multi-language Support</title> + <para> + Whenever a relational database is used to store multilingual text data in the eXo Java Content Repository the configuration must be adapted to support UTF-8 encoding. Dialect is automatically detected for certified database. You can still enforce it in case of failure, see below. + </para> + <para> + The following sections describe enabling UTF-8 support with various databases. + </para> + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-Oracle"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-DB2"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-MySQL"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-PostgreSQL"/> + </para> + </listitem> + </itemizedlist> + <note> + <itemizedlist> + <listitem> + <remark>NEEDINFO - FILE PATHS - The path needs to be updated with the equivalent path for JBoss Portal Platform instead of gatein, please see below para. New info required?</remark> + <para> + The configuration file to be modified for these changes is <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + </para> + </listitem> + <listitem> + <para> + The datasource <parameter>jdbcjcr</parameter> used in the following examples can be configured via the <literal>InitialContextInitializer</literal> component. + </para> + </listitem> + </itemizedlist> + </note> + <section id="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-Oracle"> + <title>Oracle</title> + <para> + In order to run multilanguage JCR on an Oracle backend Unicode encoding for characters set should be applied to the database. Other Oracle globalization parameters do not have any effect. The property to modify is <literal>NLS_CHARACTERSET</literal>. + </para> + <para> + The <literal>NLS_CHARACTERSET = AL32UTF8</literal> entry has been successfully tested with many European and Asian languages. + </para> + <para> + Example of database configuration: + </para> + <programlisting>NLS_LANGUAGE AMERICAN +NLS_TERRITORY AMERICA +NLS_CURRENCY $ +NLS_ISO_CURRENCY AMERICA +NLS_NUMERIC_CHARACTERS ., +NLS_CHARACTERSET AL32UTF8 +NLS_CALENDAR GREGORIAN +NLS_DATE_FORMAT DD-MON-RR +NLS_DATE_LANGUAGE AMERICAN +NLS_SORT BINARY +NLS_TIME_FORMAT HH.MI.SSXFF AM +NLS_TIMESTAMP_FORMAT DD-MON-RR HH.MI.SSXFF AM +NLS_TIME_TZ_FORMAT HH.MI.SSXFF AM TZR +NLS_TIMESTAMP_TZ_FORMAT DD-MON-RR HH.MI.SSXFF AM TZR +NLS_DUAL_CURRENCY $ +NLS_COMP BINARY +NLS_LENGTH_SEMANTICS BYTE +NLS_NCHAR_CONV_EXCP FALSE +NLS_NCHAR_CHARACTERSET AL16UTF16</programlisting> + <para> + Create database with Unicode encoding and use Oracle dialect for the Workspace Container: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_multilanguage-support/default54.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-DB2"> + <title>DB2</title> + <para> + DB2 Universal Database (DB2 UDB) supports <ulink url="http://publib.boulder.ibm.com/infocenter/db2luw/v9/index.jsp?topic=/com.i...">UTF-8 and UTF-16/UCS-2</ulink>. When a Unicode database is created, <parameter>CHAR</parameter>, <parameter>VARCHAR</parameter> and <parameter>LONG VARCHAR</parameter> data are stored in UTF-8 form. + </para> + <para> + This enables JCR multi-lingual support. + </para> + <para> + Below is an example of creating a UTF-8 database using the <parameter>db2</parameter> dialect for a workspace container with DB2 version 9 and higher: + </para> + <programlisting>DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US +</programlisting> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_multilanguage-support/default56.xml" parse="text"/></programlisting> + <note> + <para> + For DB2 version 8.<replaceable>x</replaceable> support change the property "dialect" to db2v8. + </para> + </note> + </section> + <section id="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-MySQL"> + <title>MySQL</title> + <para> + Using JCR with a MySQL-back end requires a special dialect <ulink url="http://jira.exoplatform.org/browse/JCR-375">MySQL-UTF8</ulink> to be used for internationalization support. + </para> + <para> + The database default charset should be <parameter>latin1</parameter> so as to use limited index space effectively (767 for <literal>InnoDB</literal>). + </para> + <para> + If the database default charset is multibyte, a JCR database initialization error is encountered concerning index creation failure. + </para> + <para> + JCR can work on any single byte default charset of database, with UTF8 supported by MySQL server. However it has only been tested using the <parameter>latin1</parameter> charset. + </para> + <para> + An example entry: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_multilanguage-support/default57.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Multi_language_Support_the_JCR_RDB-PostgreSQL"> + <title>PostgreSQL</title> + <para> + Multilingual support can be enabled with a PostgreSQL-back end in <ulink url="http://www.postgresql.org/docs/8.3/interactive/charset.html">different ways</ulink>: + </para> + <orderedlist> + <listitem> + <para> + Using the locale features of the operating system to provide locale-specific collation order, number formatting, translated messages, and other aspects. + </para> + <para> + UTF-8 is widely used on Linux distributions by default, so it can be useful in such cases. + </para> + </listitem> + <listitem> + <para> + Providing a number of different character sets defined in the PostgreSQL server, including multiple-byte character sets, to support storing text any language, and providing character set translation between client and server. + </para> + <para> + Using UTF-8 database charset is recommended as it will allow any-to-any conversations and make this issue transparent for the JCR. + </para> + </listitem> + </orderedlist> + <para> + Example of a database with UTF-8 encoding using PgSQL dialect for the Workspace Container: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_multilanguage-support/default58.xml" parse="text"/></programlisting> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-Search_Configuration"> + <title>Configuring Search</title> + <para> + The search function in JCR can be configured to perform in specific ways. This section will discuss configuring the search function to improve search performance and results. + </para> + <para> + Below is an example of the configuration file that governs search behaviors. Refer to <xref linkend="sect-Reference_Guide-Search_Configuration-Global_Search_Index"/> for how searching operates in JCR and information about customized searches. + </para> + <para> + The JCR index configuration file is located at <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + </para> + <para> + A code example is included below with a list of the configuration parameters shown below that. + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default61.xml" parse="text"/></programlisting> + <para> + The table below outlines <emphasis role="bold">some</emphasis> of the Configuration Parameters available, their default setting, which version of eXo JCR they were implemented in and other useful information (further parameters are explained in <xref linkend="sect-Reference_Guide-JBoss_Cache_configuration-Indexer_lock_manager_and_data_container_configuration"/>): + </para> + <table id="tabl-Reference_Guide-Search_Configuration-Configuration_parameters"> + <title>Configuration parameters</title> + <tgroup cols="4"> + <colspec colname="1" colwidth="90pt"/> + <colspec colname="2" colwidth="90pt"/> + <colspec colname="3" colwidth="150pt"/> + <colspec colname="4" colwidth="50pt"/> + <thead> + <row> + <entry> + <para> + Parameter + </para> + </entry> + <entry> + <para> + Default + </para> + </entry> + <entry> + <para> + Description + </para> + </entry> + <entry> Implemented in Version </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + index-dir + </para> + </entry> + <entry> + <para> + none + </para> + </entry> + <entry> + <para> + The location of the index directory. This parameter is mandatory. It is called "<literal>indexDir</literal>" in versions prior to eXo JCR version 1.9. + </para> + </entry> + <entry> 1.0 </entry> + </row> + <row> + <entry> + <para> + use-compoundfile + </para> + </entry> + <entry> + <para> + true + </para> + </entry> + <entry> + <para> + Advises lucene to use compound files for the index files. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + min-merge-docs + </para> + </entry> + <entry> + <para> + 100 + </para> + </entry> + <entry> + <para> + The minimum number of nodes in an index until segments are merged. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + volatile-idle-time + </para> + </entry> + <entry> 3 </entry> + <entry> + <para> + Idle time in seconds until the volatile index part is moved to a persistent index even though <literal>minMergeDocs</literal> is not reached. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + max-merge-docs + </para> + </entry> + <entry> + <para> + Integer.MAX_VALUE + </para> + </entry> + <entry> + <para> + The maximum number of nodes in segments that will be merged. The default value changed to <literal>Integer.MAX_VALUE</literal> in eXo JCR version 1.9. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + merge-factor + </para> + </entry> + <entry> + <para> + 10 + </para> + </entry> + <entry> + <para> + Determines how often segment indices are merged. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + max-field-length + </para> + </entry> + <entry> + <para> + 10000 + </para> + </entry> + <entry> + <para> + The number of words that are full-text indexed at most per property. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + cache-size + </para> + </entry> + <entry> + <para> + 1000 + </para> + </entry> + <entry> + <para> + Size of the document number cache. This cache maps UUID to lucene document numbers + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + force-consistencycheck + </para> + </entry> + <entry> + <para> + false + </para> + </entry> + <entry> + <para> + Runs a consistency check on every start up. If false, a consistency check is only performed when the search index detects a prior forced shutdown. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + auto-repair + </para> + </entry> + <entry> + <para> + true + </para> + </entry> + <entry> + <para> + Errors detected by a consistency check are automatically repaired. If false, errors are only written to the log. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> query-class </entry> + <entry> QueryImpl </entry> + <entry> + <para> + Classname that implements the javax.jcr.query.Query interface. + </para> + <para> + This class must also extend from the class: <literal>org.exoplatform.services.jcr.impl.core. query.AbstractQueryImpl</literal>. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + document-order + </para> + </entry> + <entry> + <para> + true + </para> + </entry> + <entry> + <para> + If true and the query does not contain an 'order by' clause, result nodes will be in document order. For better performance set to 'false' when queries return many nodes. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + result-fetch-size + </para> + </entry> + <entry> + <para> + Integer.MAX_VALUE + </para> + </entry> + <entry> + <para> + The number of results when a query is executed. Default value: <literal>Integer.MAX_VALUE</literal>. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + excerptprovider-class + </para> + </entry> + <entry> + <para> + DefaultXMLExcerpt + </para> + </entry> + <entry> + <para> + The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.ExcerptProvider</literal>. + </para> + <para> + This should be used for the <literal>rep:excerpt()</literal> function in a query. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + support-highlighting + </para> + </entry> + <entry> + <para> + false + </para> + </entry> + <entry> + <para> + If set to true additional information is stored in the index to support highlighting using the <literal>rep:excerpt()</literal> function. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + synonymprovider-class + </para> + </entry> + <entry> + <para> + none + </para> + </entry> + <entry> + <para> + The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.SynonymProvider</literal>. + </para> + <para> + The default value is null. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + synonymprovider-config-path + </para> + </entry> + <entry> + <para> + none + </para> + </entry> + <entry> + <para> + The path to the synonym provider configuration file. This path is interpreted relative to the path parameter. If there is a path element inside the <literal>SearchIndex</literal> element, then this path is interpreted relative to the root path of the path. Whether this parameter is mandatory depends on the synonym provider implementation. The default value is null. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + indexing-configuration-path + </para> + </entry> + <entry> + <para> + none + </para> + </entry> + <entry> + <para> + The path to the indexing configuration file. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + indexing-configuration-class + </para> + </entry> + <entry> + <para> + IndexingConfigurationImpl + </para> + </entry> + <entry> + <para> + The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.IndexingConfiguration</literal>. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + force-consistencycheck + </para> + </entry> + <entry> + <para> + false + </para> + </entry> + <entry> + <para> + If set to true a consistency check is performed depending on the parameter <literal>forceConsistencyCheck</literal>. If set to false no consistency check is performed on start up, even if a redo log had been applied. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + spellchecker-class + </para> + </entry> + <entry> + <para> + none + </para> + </entry> + <entry> + <para> + The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.SpellChecker</literal>. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + errorlog-size + </para> + </entry> + <entry> + <para> + 50(KB) + </para> + </entry> + <entry> + <para> + The default size of error log file in KB. + </para> + </entry> + <entry> 1.9 </entry> + </row> + <row> + <entry> + <para> + upgrade-index + </para> + </entry> + <entry> + <para> + false + </para> + </entry> + <entry> + <para> + Allows JCR to convert an existing index into the new format. It is also possible to set this property via system property. + </para> + <para> + Indexes prior to eXo JCR 1.12 will not run with eXo JCR 1.12. You must run an automatic migration. + </para> + <para> + Start eXo JCR with: + </para> + <programlisting><command> -Dupgrade-index=true</command></programlisting> + <para> + The old index format is then converted in the new index format. After the conversion the new format is used. + </para> + <para> + On subsequent starts this option is no longer needed. The old index is replaced and a back conversion is not possible + </para> + <para> + It is recommended that a backup of the index be made before conversion. (Only for migrations from JCR 1.9 and later.) + </para> + </entry> + <entry> 1.12 </entry> + </row> + <row> + <entry> + <para> + analyzer + </para> + </entry> + <entry> + <para> + org.apache.lucene.analysis. standard.StandardAnalyzer + </para> + </entry> + <entry> + <para> + Class name of a lucene analyzer to use for full-text indexing of text. + </para> + </entry> + <entry> 1.12 </entry> + </row> + </tbody> + </tgroup> + </table> + <section id="sect-Reference_Guide-Search_Configuration-Global_Search_Index"> + <title>Global Search Index</title> + <para> + By default eXo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content + </para> + <example> + <title>Standard Analyzed Filters</title> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default62.java" parse="text"/></programlisting> + <para> + Comment #1: The first filter (StandardFilter) removes possessive apostrophes (<emphasis role="bold">'s</emphasis>) from the end of words and removes periods (<emphasis role="bold">.</emphasis>) from acronyms. + </para> + <para> + Comment #2: The second filter (LowerCaseFilter) normalizes token text to lower case. + </para> + <para> + Comment #3: The last filter (StopFilter) removes stop words from a token stream. The stop set is defined in the analyzer. + </para> + </example> + <para> + The global search index is configured in the <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the "query-handler" tag. + </para> + <programlisting language="XML" role="XML"><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> +</programlisting> + <para> + The same analyzer should always be used for indexing and for querying in lucene otherwise results may be unpredictable. eXo JCR does this automatically. The StandardAnalyzer (configured by default) can, however, be replaced with another. + </para> + <para> + A customized QueryHandler can also be easily created. + </para> + <formalpara id="form-Reference_Guide-Global_Search_Index-Customized_Search_Indexes_and_Analyzers"> + <title>Customized Search Indexes and Analyzers</title> + <para> + By default Exo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content: + </para> + </formalpara> + <programlisting language="Java" role="Java">public TokenStream tokenStream(String fieldName, Reader reader) { + StandardTokenizer tokenStream = new StandardTokenizer(reader, replaceInvalidAcronym); + tokenStream.setMaxTokenLength(maxTokenLength); + TokenStream result = new StandardFilter(tokenStream); + result = new LowerCaseFilter(result); + result = new StopFilter(result, stopSet); + return result; + }</programlisting> + <itemizedlist> + <listitem> + <para> + The first one (StandardFilter) removes 's (as 's in "Peter's") from the end of words and removes dots from acronyms. + </para> + </listitem> + <listitem> + <para> + The second one (LowerCaseFilter) normalizes token text to lower case. + </para> + </listitem> + <listitem> + <para> + The last one (StopFilter) removes stop words from a token stream. The stop set is defined in the analyzer. + </para> + </listitem> + </itemizedlist> + <para> + Additional filters can be used in specific cases. The <phrase>ISOLatin1AccentFilter</phrase> filter, for example, which replaces accented characters in the ISO Latin 1 character set (ISO-8859-1) by their unaccented equivalents. + </para> + <para> + The <phrase>ISOLatin1AccentFilter</phrase> is not present in the current lucene version used by eXo. + </para> + <para> + In order to use a different filter, a new analyzer must be created, as well as new search index to use the analyzer. These are packaged into a jar file, which is then deployed with the application. + </para> + <procedure id="proc-Reference_Guide-Global_Search_Index-Create_a_new_filter_analyzer_and_search_index"> + <title>Create a new filter, analyzer and search index</title> + <step> + <para> + Create a new filter with the method: + </para> + <programlisting language="Java" role="JAVA">public final Token next(final Token reusableToken) throws java.io.IOException +</programlisting> + <para> + This defines how characters are read and used by the filter. + </para> + </step> + <step> + <para> + Create the analyzer. + </para> + <para> + The analyzer must extend <literal>org.apache.lucene.analysis.standard.StandardAnalyzer</literal> and overload the method. + </para> + <para> + Use the following to use new filters. + </para> + <programlisting language="Java" role="JAVA">public TokenStream tokenStream(String fieldName, Reader reader) +</programlisting> + </step> + <step> + <para> + To create the new search index, extend <literal>org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex</literal> and write the constructor to set the correct analyzer. + </para> + <para> + Use the method below to return your analyzer: + </para> + <programlisting language="Java" role="JAVA">public Analyzer getAnalyzer() { +return MyAnalyzer; +} +</programlisting> + </step> + </procedure> + <note> + <para> + In eXo JCR version 1.12 (and later) the analyzer can be directly set in the configuration. For users with this version the creation of a new SearchIndex for new analyzers is redundant. + </para> + </note> + <para> + To configure an application to use a new <literal>SearchIndex</literal>, replace the following code: + </para> + <programlisting language="XML" role="XML"><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + +</programlisting> + <para> + in <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> with the new class: + </para> + <programlisting language="XML" role="XML"><query-handler class="mypackage.indexation.MySearchIndex> + +</programlisting> + <para> + To configure an application to use a new analyzer, add the <parameter>analyzer</parameter> parameter to each query-handler configuration in <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default69.xml" parse="text"/></programlisting> + <para> + The new <literal>SearchIndex</literal> will start to index contents with the specified filters when the JCR is next started. + </para> + </section> + <section id="sect-Reference_Guide-Search_Configuration-IndexingConfiguration"> + <title>IndexingConfiguration</title> + <para> + From version 1.9, the default search index implementation in JCR allows user control over which properties of a node are indexed. Different analyzers can also be set for different nodes. + </para> + <para> + The configuration parameter is called <literal>indexingConfiguration</literal> and is not set by default. This means all properties of a node are indexed. + </para> + <para> + To configure the indexing behavior add a parameter to the query-handler element in your configuration file. + </para> + <programlisting language="XML" role="XML"><param name="indexing-configuration-path" value="/indexing_configuration.xml"/> + +</programlisting> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Node_Scope_Limit"> + <title>Node Scope Limit</title> + <para> + The node scope can be limited so that only certain properties of a node type are indexed. This can optimize the index size. + </para> + </formalpara> + <para> + With the configuration below only properties named <parameter>Text</parameter> are indexed for <parameter>nt:unstructured</parameter> node types. This configuration also applies to all nodes whose type extends from <parameter>nt:unstructured</parameter>. + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default71.xml" parse="text"/></programlisting> + <note> + <title>Namespace Prefixes</title> + <para> + The <phrase>namespace prefixes</phrase> must be declared throughout the XML file in the configuration element that is being used. + </para> + </note> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Indexing_Boost_Value"> + <title>Indexing Boost Value</title> + <para> + It is also possible to configure a <phrase>boost value</phrase> for the nodes that match the index rule. The default boost value is 1.0. Higher boost values (a reasonable range is 1.0 - 5.0) will yield a higher score value and appear as more relevant. + </para> + </formalpara> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default72.xml" parse="text"/></programlisting> + <para> + If you do not wish to boost the complete node, but only certain properties, you can also provide a boost value for the listed properties: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default73.xml" parse="text"/></programlisting> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Conditional_Index_Rules"> + <title>Conditional Index Rules</title> + <para> + You may also add a <phrase>condition</phrase> to the index rule and have multiple rules with the same nodeType. The first index rule that matches will apply and all remaining ones are ignored: + </para> + </formalpara> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default74.xml" parse="text"/></programlisting> + <para> + In the above example the first rule only applies if the <parameter>nt:unstructured</parameter> node has a priority property with a value <parameter>high</parameter>. The condition syntax only supports the equals operator and a string literal. + </para> + <para> + Properties may also be referenced on the condition that are not on the current node: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default75.xml" parse="text"/></programlisting> + <para> + The indexing configuration allows the type of a node in the condition to be specified. Please note however that the type match must be exact. It does not consider sub types of the specified node type. + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default76.xml" parse="text"/></programlisting> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Exclusion_from_the_Node_Scope_Index"> + <title>Exclusion from the Node Scope Index</title> + <para> + All configured properties are full-text indexed by default (if they are of type STRING and included in the node scope index). + </para> + </formalpara> + <para> + A node scope search normally finds all nodes of an index. That is to say; <literal>jcr:contains(., 'foo')</literal> returns all nodes that have a string property containing the word '<replaceable>foo</replaceable>'. + </para> + <para> + Properties can be explicitly excluded from the node scope index with: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default77.xml" parse="text"/></programlisting> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Index_Aggregates"> + <title>Index Aggregates</title> + <para> + Sometimes it is useful to include the contents of descendant nodes into a single node to more easily search on content that is scattered across multiple nodes. + </para> + </formalpara> + <para> + JCR allows the definition of index aggregates based on relative path patterns and primary node types. + </para> + <para> + The following example creates an index aggregate on <literal>nt:file</literal> that includes the content of the jcr:content node: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default78.xml" parse="text"/></programlisting> + <para> + Included nodes can also be restricted to a certain type: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default79.xml" parse="text"/></programlisting> + <para> + The <emphasis role="bold">*</emphasis> wild-card can be used to match all child nodes: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default80.xml" parse="text"/></programlisting> + <para> + Nodes to a certain depth below the current node can be included by adding multiple include elements. The <parameter>nt:file</parameter> node may contain a complete XML document under jcr:content for example: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default81.xml" parse="text"/></programlisting> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Property_Level_Analyzers"> + <title>Property-Level Analyzers</title> + <para> + How a property has to be analyzed can be defined in the following configuration section. If there is an analyzer configuration for a property, this analyzer is used for indexing and searching of this property. For example: + </para> + </formalpara> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default82.xml" parse="text"/></programlisting> + <para> + The configuration above sets lucene <emphasis role="bold">KeywordAnalyzer</emphasis> to index and search the property "<replaceable>mytext</replaceable>" across the entire workspace while the "<replaceable>mytext2</replaceable>" property is searched with the <emphasis role="bold">WhitespaceAnalyzer</emphasis>. + </para> + <para> + The <emphasis role="bold">WhitespaceAnalyzer</emphasis> tokenizes a property, the <emphasis role="bold">KeywordAnalyzer</emphasis> takes the property as a whole. + </para> + <para> + Using different analyzers for different languages can be particularly useful. + </para> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Characteristics_of_Node_Scope_Searches"> + <title>Characteristics of Node Scope Searches</title> + <para> + Unexpected behavior may be encountered when using analyzers to search within a <emphasis>property</emphasis> compared to searching within a <emphasis>node scope</emphasis>. This is because the node scope always uses the global analyzer. + </para> + </formalpara> + <para> + For example: the property "<parameter>mytext</parameter>" contains the text; "<emphasis>testing my analyzers</emphasis>" but no analyzers have been configured for this property (and the default analyzer in SearchIndex has not been changed). + </para> + <para> + If the query is: + </para> + <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(mytext,'analyzer')]" +</programlisting> + <para> + The <literal>xpath</literal> does not return a result in the node with the property above and default analyzers. + </para> + <para> + Also, if a search is done on the node scope as follows: + </para> + <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(.,'analyzer')]" +</programlisting> + <para> + No result will be returned. + </para> + <para> + Only specific analyzers can be set on a node property, and the node scope indexing and analyzing is always done with the globally defined analyzer in the SearchIndex element. + </para> + <para> + If the analyzer used to index the "mytext" property above is changed to: + </para> + <programlisting language="XML" role="XML"><analyzer class="org.apache.lucene.analysis.Analyzer.GermanAnalyzer"> +<property>mytext</property> +</analyzer> +</programlisting> + <para> + The search below would return a result because of the word stemming (analyzers - analyzer). + </para> + <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(mytext,'analyzer')]" +</programlisting> + <para> + The second search in the example: + </para> + <programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(.,'analyzer')]" +</programlisting> + <para> + Would still not give a result, since the node scope is indexed with the global analyzer, which in this case does not take into account any word stemming. + </para> + <para> + Be aware that when using analyzers for specific properties, a result may be found in a property for certain search text, but the same search text in the node scope of the property may not find a result. + </para> + <note> + <para> + Both index rules and index aggregates influence how content is indexed in JCR. If the configuration is changed, the existing content is not automatically re-indexed according to the new rules. + </para> + <para> + Content must be manually re-indexed when the configuration is changed. + </para> + </note> + </section> + <section id="sect-Reference_Guide-Search_Configuration-Advanced_features"> + <title>Advanced features</title> + <para> + eXo JCR supports some advanced features, which are not specified in JSR 170: + </para> + <itemizedlist> + <listitem> + <para> + Get a text excerpt with <emphasis role="bold">highlighted words</emphasis> that matches the query: <xref linkend="sect-Reference_Guide-Highlighting-DefaultXMLExcerpt"/>>. + </para> + </listitem> + <listitem> + <para> + Search a term and its <emphasis role="bold">synonyms</emphasis>: <xref linkend="sect-Reference_Guide-Searching_Repository_Content-SynonymSearch"/>. + </para> + </listitem> + <listitem> + <para> + Search <emphasis role="bold">similar</emphasis> nodes: <xref linkend="sect-Reference_Guide-Searching_Repository_Content-Similarity"/>. + </para> + </listitem> + <listitem> + <para> + Check <emphasis role="bold">spelling</emphasis> of a full text query statement: <xref linkend="sect-Reference_Guide-Searching_Repository_Content-SpellChecker"/>. + </para> + </listitem> + <listitem> + <para> + Define index <emphasis role="bold">aggregates and rules</emphasis>: IndexingConfiguration. + </para> + </listitem> + </itemizedlist> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-JDBC_Data_Container_Config"> + <title>Configuring the JDBC Data Container</title> + <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Introduction"> + <title>Introduction</title> + <para> + eXo JCR persistent data container can work in two configuration modes: + </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> + <para> + Currently the data container is tested with the following RDBMS: + </para> + <table id="tabl-Reference_Guide-Introduction-Supported-databases"> + <title>Supported databases</title> + <tgroup cols="2"> + <thead> + <row> + <entry> Database </entry> + <entry> Driver Version </entry> + </row> + </thead> + <tbody> + <row> + <entry> IBM DB2 9.7 (FP5) </entry> + <entry> IBM DB2 JDBC Universal Driver Architecture 4.13.80 </entry> + </row> + <row> + <entry> Oracle 11g R1 (11.1.0.7.0) </entry> + <entry> Oracle JDBC Driver 11.1.0.7 </entry> + </row> + <row> + <entry> Oracle 11g R1 RAC (11.1.0.7.0) </entry> + <entry> Oracle JDBC Driver 11.1.0.7 </entry> + </row> + <row> + <entry> Oracle 11g R2 (11.2.0.3.0) </entry> + <entry> Oracle JDBC Driver v11.2.0.3.0 </entry> + </row> + <row> + <entry> Oracle 11g R2 RAC (11.2.0.3.0) </entry> + <entry> Oracle JDBC Driver v11.2.0.3.0 </entry> + </row> + <row> + <entry> MySQL 5.1 </entry> + <entry> MySQL Connector/J 5.1.21 </entry> + </row> + <row> + <entry> MySQL 5.5 </entry> + <entry> MySQL Connector/J 5.1.21 </entry> + </row> + <row> + <entry> Microsoft SQL Server 2008 </entry> + <entry> Microsoft SQL Server JDBC Driver 3.0.1301.101, Microsoft SQL Server JDBC Driver 4.0.2206.100 </entry> + </row> + <row> + <entry> Microsoft SQL Server 2008 R2 </entry> + <entry> Microsoft SQL Server JDBC Driver 3.0.1301.101, Microsoft SQL Server JDBC Driver 4.0.2206.100 </entry> + </row> + <row> + <entry> PostgreSQL 8.4.8 </entry> + <entry> JDBC4 Postgresql Driver, Version 8.4-703 </entry> + </row> + <row> + <entry> PostgreSQL 9.1.0 </entry> + <entry> JDBC4 Postgresql Driver, Version 9.1-903 </entry> + </row> + <row> + <entry> Sybase ASE 15.7 </entry> + <entry> Sybase jConnect JDBC driver v7 </entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <title>Isolation Levels</title> + <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">here.</ulink> + </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> + <remark>NEEDINFO - FILE PATHS - The path needs to be updated with the equivalent path for JBoss Portal Platform instead of gatein, please see below para. New info required?</remark> + <para> + You can find SQL-scripts in <filename>conf/storage/</filename> directory of the <filename><replaceable>JPP_HOME</replaceable>/modules/org/gatein/lib/main/exo.jcr.component.core-&JCR_VERSION;.jar</filename> file . + </para> + <para> + The following tables show the correspondence between the scripts and databases: + </para> + <table id="tabl-Reference_Guide-Introduction-Single_database"> + <title>Single-database</title> + <tgroup cols="2"> + <thead> + <row> + <entry> Database </entry> + <entry> Script </entry> + </row> + </thead> + <tbody> + <row> + <entry> MySQL DB </entry> + <entry> + <filename>jcr-sjdbc.mysql.sql</filename> + </entry> + </row> + <row> + <entry> MySQL DB with utf-8 </entry> + <entry> + <filename>jcr-sjdbc.mysql-utf8.sql</filename> + </entry> + </row> + <row> + <entry> PostgresSQL </entry> + <entry> + <filename>jcr-sjdbc.pqsql.sql</filename> + </entry> + </row> + <row> + <entry> Oracle DB </entry> + <entry> + <filename>jcr-sjdbc.ora.sql</filename> + </entry> + </row> + <row> + <entry> DB2 9.7 </entry> + <entry> + <filename>jcr-sjdbc.db2.sql</filename> + </entry> + </row> + <row> + <entry> MS SQL Server </entry> + <entry> + <filename>jcr-sjdbc.mssql.sql</filename> + </entry> + </row> + <row> + <entry> Sybase </entry> + <entry> + <filename>jcr-sjdbc.sybase.sql</filename> + </entry> + </row> + <row> + <entry> HSQLDB </entry> + <entry> + <filename>jcr-sjdbc.sql</filename> + </entry> + </row> + </tbody> + </tgroup> + </table> + <table id="tabl-Reference_Guide-Introduction-Multi_database"> + <title>Multi-database</title> + <tgroup cols="2"> + <thead> + <row> + <entry> Database </entry> + <entry> Script </entry> + </row> + </thead> + <tbody> + <row> + <entry> MySQL DB </entry> + <entry> + <filename>jcr-mjdbc.mysql.sql</filename> + </entry> + </row> + <row> + <entry> MySQL DB with utf-8 </entry> + <entry> + <filename>jcr-mjdbc.mysql-utf8.sql</filename> + </entry> + </row> + <row> + <entry> PostgresSQL </entry> + <entry> + <filename>jcr-mjdbc.pqsql.sql</filename> + </entry> + </row> + <row> + <entry> Oracle DB </entry> + <entry> + <filename>jcr-mjdbc.ora.sql</filename> + </entry> + </row> + <row> + <entry> DB2 9.7 </entry> + <entry> + <filename>jcr-mjdbc.db2.sql</filename> + </entry> + </row> + <row> + <entry> MS SQL Server </entry> + <entry> + <filename>jcr-mjdbc.mssql.sql</filename> + </entry> + </row> + <row> + <entry> Sybase </entry> + <entry> + <filename>jcr-mjdbc.sybase.sql</filename> + </entry> + </row> + <row> + <entry> HSQLDB </entry> + <entry> + <filename>jcr-mjdbc.sql</filename> + </entry> + </row> + </tbody> + </tgroup> + </table> + <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-&JCR_VERSION;.jar</package> or source-distribution of eXo JCR implementation. + </para> + <example id="exam-Reference_Guide-Introduction-Example_Parameter"> + <title>Example Parameter</title> + <programlisting><code>jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8</code></programlisting> + </example> + <para> + The configuration files are located in service jars <filename>/conf/portal/configuration.xml</filename> (eXo services including JCR Repository Service) and <filename>exo-jcr-config.xml</filename> (repositories configuration) by default. In JBoss Portal Platform, the JCR is configured in portal web application <filename>portal/WEB-INF/conf/jcr/jcr-configuration.xml</filename> (JCR Repository Service and related services) and <filename>repository-configuration.xml</filename> (repositories configuration). + </para> + <para> + Read more about <xref linkend="chap-Reference_Guide-JCR_configuration"/>. + </para> + </section> + <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Multi_database_Configuration"> + <title>Multi-database Configuration</title> + <para> + You need to configure each workspace in a repository as part of multi-database configuration. Databases may reside on remote servers as required. + </para> + <procedure> + <title/> + <step> + <para> + Configure the data containers in the <literal>org.exoplatform.services.naming.InitialContextInitializer</literal> service. It's the JNDI context initializer which registers (binds) naming resources (DataSources) for data containers. + </para> + <para> + For example (two data containers <parameter>jdbcjcr</parameter> - local HSQLDB, <parameter>jdbcjcr1</parameter> - remote MySQL): + </para> + <programlisting language="XML" role="XML"> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/example-1.xml" parse="text"/></programlisting> + <substeps> + <step> + <para> + Configure the database connection parameters: + </para> + <itemizedlist> + <listitem> + <para> + <parameter>driverClassName</parameter>, e.g. "org.hsqldb.jdbcDriver", "com.mysql.jdbc.Driver", "org.postgresql.Driver" + </para> + </listitem> + <listitem> + <para> + <parameter>url</parameter>, e.g. "jdbc:hsqldb:file:target/temp/data/portal", "jdbc:mysql://exoua.dnsalias.net/jcr" + </para> + </listitem> + <listitem> + <para> + <parameter>username</parameter>, e.g. "sa", "exoadmin" + </para> + </listitem> + <listitem> + <para> + <parameter>password</parameter>, e.g. "", "exo12321" + </para> + </listitem> + </itemizedlist> + </step> + </substeps> + <para> + There can be connection pool configuration parameters (org.apache.commons.dbcp.BasicDataSourceFactory): + </para> + <itemizedlist> + <listitem> + <para> + <parameter>maxActive</parameter>, e.g. 50 + </para> + </listitem> + <listitem> + <para> + <parameter>maxIdle</parameter>, e.g. 5 + </para> + </listitem> + <listitem> + <para> + <parameter>initialSize</parameter>, e.g. 5 + </para> + </listitem> + <listitem> + <para> + and other according to <ulink url="http://jakarta.apache.org/commons/dbcp/configuration.html">Apache DBCP configuration</ulink> + </para> + </listitem> + </itemizedlist> + </step> + <step> + <para> + Configure the repository service. Each workspace will be configured for its own data container. + </para> + <para> + For example (two workspaces <parameter>ws</parameter> - jdbcjcr, <parameter>ws1</parameter> - jdbcjcr1): + </para> + <programlisting language="XML" role="XML"> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/example-2.xml" parse="text"/></programlisting> + <itemizedlist> + <listitem> + <para> + <parameter>source-name</parameter>: A javax.sql.DataSource name configured in InitialContextInitializer component (was <parameter>sourceName</parameter> prior JCR 1.9); + </para> + </listitem> + <listitem> + <para> + <parameter>dialect</parameter>: A database dialect, one of <literal>hsqldb</literal>, <literal>mysql</literal>, <literal>mysql-utf8</literal>, <literal>pgsql</literal>, <literal>oracle</literal>, <literal>oracle-oci</literal>, <literal>mssql</literal>, <literal>sybase</literal>, <literal>derby</literal>, <literal>db2</literal>, <literal>db2v8</literal> or <literal>auto</literal> for dialect autodetection; + </para> + </listitem> + <listitem> + <para> + <parameter>multi-db</parameter>: Enable multi-database container with this parameter (set value "true"); + </para> + </listitem> + <listitem> + <para> + <parameter>max-buffer-size: A</parameter> a threshold (in bytes) after which a <literal>javax.jcr.Value</literal> content will be swapped to a file in a temporary storage. A swap for pending changes, for example. + </para> + </listitem> + <listitem> + <para> + <parameter>swap-directory</parameter>: A path in the file system used to swap the pending changes. + </para> + </listitem> + </itemizedlist> + </step> + </procedure> + <para> + This procedure configures two workspace which will be persistent in two different databases (<emphasis>ws</emphasis> in HSQLDB and <emphasis>ws1</emphasis> in MySQL). + </para> + </section> + <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Single_database_Configuration"> + <title>Single-database Configuration</title> + <para> + Configuring a single-database data container is easier than configuring a multi-database data container as only one naming resource must be configured. + </para> + <example id="exam-Reference_Guide-Single_database_Configuration-jdbcjcr_Data_Container"> + <title><parameter>jdbcjcr</parameter> Data Container</title> + <programlisting language="XML" role="XML"> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/example-3.xml" parse="text"/></programlisting> + </example> + <para> + Configure repository workspaces with this one database. The <parameter>multi-db</parameter> parameter must be set as <literal>false</literal>. + </para> + <para> + For example (two workspaces <parameter>ws</parameter> - <literal>jdbcjcr</literal>, <parameter>ws1</parameter> - <literal>jdbcjcr</literal>): + </para> + <example id="exam-Reference_Guide-Single_database_Configuration-Example"> + <title>Example</title> + <programlisting language="XML" role="XML"> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/example-4.xml" parse="text"/></programlisting> + </example> + <para> + This configures two persistent workspaces in one database (PostgreSQL). + </para> + <section id="sect-Reference_Guide-Single_database_Configuration-Configuration_without_DataSource"> + <title>Configuration without DataSource</title> + <para> + It is possible to configure the repository without binding <literal>javax.sql.DataSource</literal> in the JNDI service if you have a dedicated JDBC driver implementation with special features like XA transactions, statements/connections pooling etc: + </para> + <procedure> + <title/> + <step> + <para> + Remove the configuration in <literal>InitialContextInitializer</literal> for your database and configure a new one directly in the workspace container. + </para> + </step> + <step> + <para> + Remove parameter <parameter>source-name</parameter> and add next lines instead. Describe your values for a JDBC driver, database URL and username. + </para> + </step> + </procedure> + <warning> + <title>Connection Pooling</title> + <para> + Ensure the JDBC driver provides connection pooling. Connection pooling is strongly recommended for use with the JCR to prevent a database overload. + </para> + </warning> + <programlisting language="XML" role="XML"><workspace name="ws" auto-init-root-nodetype="nt:unstructured"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="dialect" value="hsqldb"/> + <property name="driverliteral" value="org.hsqldb.jdbcDriver"/> + <property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/> + <property name="username" value="su"/> + <property name="password" value=""/> + ......</programlisting> + </section> + <section id="sect-Reference_Guide-Single_database_Configuration-Dynamic_Workspace_Creation"> + <title>Dynamic Workspace Creation</title> + <para> + Workspaces can be added dynamically during runtime. + </para> + <para> + This can be performed in two steps: + </para> + <procedure> + <title/> + <step> + <para> + <literal>ManageableRepository.configWorkspace(WorkspaceEntry wsConfig)</literal>: Register a new configuration in RepositoryContainer and create a WorkspaceContainer. + </para> + </step> + <step> + <para> + <literal>ManageableRepository.createWorkspace(String workspaceName)</literal>: Creation a new workspace. + </para> + </step> + </procedure> + </section> + </section> + <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Simple_and_Complex_queries"> + <title>Simple and Complex queries</title> + <para> + eXo JCR provides two ways to interact with the database; + </para> + <variablelist> + <title/> + <varlistentry> + <term> + <literal>JDBCStorageConnection</literal> + </term> + <listitem> + <para> + Which uses simple queries. Simple queries do not use sub queries, left or right joins. They are implemented in such a way as to support as many database dialects as possible. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>CQJDBCStorageConection</literal> + </term> + <listitem> + <para> + Which uses complex queries. Complex queries are optimized to reduce the number of database calls. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Simple queries will be used if you chose <literal>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</literal>: + </para> + <programlisting language="XML" role="XML"><workspaces> + <workspace name="ws" auto-init-root-nodetype="nt:unstructured"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + ... + </workspace> +</worksapces> +</programlisting> + <para> + Complex queries will be used if you chose <literal>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</literal>: + </para> + <programlisting language="XML" role="XML"><workspaces> + <workspace name="ws" auto-init-root-nodetype="nt:unstructured"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"> + ... + </workspace> +</worksapces></programlisting> + </section> + <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Force_Query_Hints"> + <title>Force Query Hints</title> + <para> + Some databases, such as Oracle and MySQL, support hints to increase query performance. The eXo JCR has separate Complex Query implementations for the Orcale database dialect, which uses query hints to increase performance for few important queries. + </para> + <para> + To enable this option, use the following configuration property: + </para> + <programlisting language="XML" role="XML"><workspace name="ws" auto-init-root-nodetype="nt:unstructured"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="dialect" value="oracle"/> + <property name="force.query.hints" value="true" /> + ......</programlisting> + <para> + Query hints are only used for Complex Queries with the Oracle dialect. For all other dialects this parameter is ignored. + </para> + </section> + <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Notes_for_Microsoft_Windows_users"> + <title>Notes for Microsoft Windows users</title> + <para> + The current configuration of eXo JCR uses <ulink url="http://commons.apache.org/dbcp/">Apache DBCP</ulink> connection pool (<literal>org.apache.commons.dbcp.BasicDataSourceFactory</literal>). + </para> + <para> + It is possible to set a high value for the <parameter>maxActive</parameter> parameter in the <filename>configuration.xml</filename> file. This creates a high use of TCP/IP ports from a client machine inside the pool (the JDBC driver, for example). As a result, the data container can throw exceptions like "<emphasis>Address already in use</emphasis>". + </para> + <para> + To solve this problem, you must configure the client's machine networking software to use shorter timeouts for open TCP/IP ports. + </para> + <para> + This is done by editing two registry keys within the <parameter>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters</parameter> node. Both of these keys are unset by default. To set the keys as required: + </para> + <procedure> + <title/> + <step> + <para> + Set the <parameter>MaxUserPort</parameter> registry key to <parameter>=dword:00001b58</parameter>. This sets the maximum of open ports to 7000 or higher (the default is 5000). + </para> + </step> + <step> + <para> + Set <parameter>TcpTimedWaitDelay</parameter> to <parameter>=dword:0000001e</parameter>. This sets <parameter>TIME_WAIT</parameter> parameter to 30 seconds (the default is 240). + </para> + </step> + </procedure> + <example id="exam-Reference_Guide-Notes_for_Microsoft_Windows_users-Sample_Registry_File"> + <title>Sample Registry File</title> + <programlisting>Windows Registry Editor Version 5.00 + +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters] +"MaxUserPort"=dword:00001b58 +"TcpTimedWaitDelay"=dword:0000001e</programlisting> + </example> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-External_Value_Storages"> + <title>External Value Storages</title> + <section id="sect-Reference_Guide-External_Value_Storages-Introduction"> + <title>Introduction</title> + <para> + JCR values are stored in the Workspace Data container by default. 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> + Tree-based storage is recommended in most cases. + </para> + </section> + <section id="sect-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage"> + <title>Tree File Value Storage</title> + <para> + Tree File Value Storage holds values in tree-like file system files. <property>Path</property> property points to the root directory to store the files. + </para> + <para> + This is a recommended type of external storage because it can contain large amount of files limited only by disk/volume free space. + </para> + <para> + However, using Tree File Value Storage can result in a higher time on value deletion, due to the removal of unused tree-nodes. + </para> + <example> + <title>Tree File Value Storage Configuration</title> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_external-value-storages/default25.xml" parse="text"/></programlisting> + <para> + Comment #1: The <emphasis role="bold">id</emphasis> is the value storage unique identifier, used for linking with properties stored in a workspace container. + </para> + <para> + Comment #2: the <emphasis role="bold">path</emphasis> is a location where value files will be stored. + </para> + </example> + <para> + Each file value storage can have the <function>filters</function> for incoming values. A filter can match values by <property>property-type</property>, <property>property-name</property>, <property>ancestor-path</property>. It can also match the size of values stored (<property>min-value-size</property>) in bytes. + </para> + <para> + In the previous example a filter with <property>property-type</property> and <property>min-value-size</property> has been used. This results in storage for binary values with size greater of 1MB. + </para> + <para> + It is recommended that properties with large values are stored in file value storage only. + </para> + <para> + The example below shows a value storage with different locations for large files (<property>min-value-size</property> a 20Mb-sized filter). + </para> + <para> + A value storage uses ORed logic in the process of filter selection. This means the first filter in the list will be called first and if it is not matched the next will be called, and so on. + </para> + <para> + In this example a value matches the 20MB filter <property>min-value-size</property> and will be stored in the path "<literal>data/20Mvalues</literal>". All other filters will be stored in "<literal>data/values</literal>". + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_external-value-storages/default26.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-External_Value_Storages-Disabling_value_storage"> + <title>Disabling value storage</title> + <para> + The JCR allows you to disable value storage by adding the following property into its configuration. + </para> + <programlisting language="XML"><property name="enabled" value="false" /></programlisting> + <warning> + <title>Warning</title> + <para> + It is recommended that this functionality be used for internal and testing purpose only, and with caution, as all stored values will be inaccessible. + </para> + </warning> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-Workspace_Data_Container"> + <title>Workspace Data Container</title> + <para> + Each Workspace of the JCR has its own persistent storage to hold that workspace's items data. The eXo JCR can be configured so that it can use one or more workspaces that are logical units of the repository content. + </para> + <para> + The physical data storage mechanism is configured using mandatory element <emphasis role="bold">container</emphasis>. The type of container is described in the attribute <parameter>class = <replaceable>fully_qualified_name_of_org.exoplatform.services.jcr.storage.WorkspaceDataContainer_subclass</replaceable></parameter>. + </para> + <example> + <title>Physical Data Storage Configuration</title> + <programlisting language="XML" role="XML"><container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> + <properties> + <property name="source-name" value="jdbcjcr1"/> + <property name="dialect" value="hsqldb"/> + <property name="multi-db" value="true"/> + <property name="max-buffer-size" value="200K"/> + <property name="swap-directory" value="target/temp/swap/ws"/> + <property name="lazy-node-iterator-page-size" value="50"/> + <property name="acl-bloomfilter-false-positive-probability" value="0.1d"/> + <property name="acl-bloomfilter-elements-number" value="1000000"/> + </properties></programlisting> + <para> + <literal>source-name</literal>: The JDBC data source name which is registered in JDNI by InitialContextInitializer. This was known as <literal>sourceName</literal> in versions prior to 1.9. + </para> + <para> + <literal>dialect</literal>: The database dialect. Must be one of the following: <literal>hsqldb</literal>, <literal>mysql</literal>, <literal>mysql-utf8</literal>, <literal>pgsql</literal>, <literal>oracle</literal>, <literal>oracle-oci</literal>, <literal>mssql</literal>, <literal>sybase</literal>, <literal>derby</literal>, <literal>db2</literal> or <literal>db2v8</literal>). + </para> + <para> + <literal>multi-db</literal>: This parameter, if <literal>true</literal>, enables multi-database container. + </para> + <para> + <literal>max-buffer-size</literal>: A threshold in bytes. If a value size is greater than this setting, then it will be spooled to a temporary file. + </para> + <para> + <literal>swap-directory</literal>: A location where the value will be spooled if no value storage is configured but a <literal>max-buffer-size</literal> is exceeded. + </para> + <para> + <literal>lazy-node-iterator-page-size</literal>: "Lazy" child nodes iterator settings. Defines size of page, the number of nodes that are retrieved from persistent storage at once. + </para> + <para> + <literal>acl-bloomfilter-false-positive-probability</literal>: ACL Bloom-filter settings. ACL Bloom-filter desired false positive probability. Range [0..1]. Default value 0.1d. + </para> + <para> + <literal>acl-bloomfilter-elements-number</literal>: ACL Bloom-filter settings. Expected number of ACL-elements in the Bloom-filter. Default value 1000000. + </para> + </example> + <note> + <para> + Bloom filters are not supported by all the cache implementations so far only the inplementation for infinispan supports it. + </para> + <para> + Bloom-filter used to avoid read nodes that definitely do not have ACL. <emphasis role="bold">acl-bloomfilter-false-positive-probability</emphasis> and <emphasis role="bold">acl-bloomfilter-elements-number</emphasis> used to configure such filters. Bloom filters are not supported by all the cache implementations so far only the inplementation for infinispan supports it. + </para> + <para> + More about Bloom filters you can read here <ulink url="http://en.wikipedia.org/wiki/Bloom_filter">http://en.wikipedia.org/wiki/Bloom_filter</ulink>. + </para> + </note> + <para> + The eXo JCR has a JDBC-based, relational database, production ready <emphasis role="bold">Workspace Data Container</emphasis>. + </para> + <para> + Workspace Data Container <emphasis>may</emphasis> support external storages for <literal>javax.jcr.Value</literal> (which can be the case for BLOB values for example) using the optional element <literal>value-storages</literal>. + </para> + <para> + The Data Container will try to read or write a Value using the underlying value storage plug-in if the filter criteria (see below) match the current property. + </para> + <example> + <title>External Value Storage Configuration</title> + <programlisting language="XML" role="XML"><value-storages> + <value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> + <properties> + <property name="path" value="data/values"/> + </properties> + <filters> + <filter property-type="Binary" min-value-size="1M"/> + </filters> +......... +</value-storages></programlisting> + <para> + <literal>value-storage</literal> is the subclass of <literal>org.exoplatform.services.jcr.storage.value.ValueStoragePlugin</literal> and <literal>properties</literal> are optional plug-in specific parameters. + </para> + <para> + <literal>filters</literal>: Each file value storage can have the filter(s) for incoming values. If there are several filter criteria, they all have to match (AND-Condition). + </para> + </example> + <para> + A filter can match values by property type (property-type), property name (property-name), ancestor path (ancestor-path) and/or the size of values stored (min-value-size, e.g. 1M, 4.2G, 100 (bytes)). + </para> + <para> + In a code sample, we use a filter with property-type and min-value-size only. That means that the storage is only for binary values whose size is greater than 1Mbyte. + </para> + <para> + It is recommended that you store properties with large values in a file value storage only. + </para> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-Cluster_Configuration"> + <title>Configuring Cluster</title> + <section id="sect-Reference_Guide-Cluster_Configuration-Launching_Cluster"> + <title>Launching Cluster</title> + <section id="sect-Reference_Guide-Launching_Cluster-Configuring_JCR_to_use_external_configuration"> + <title>Configuring JCR to use external configuration</title> + <itemizedlist> + <listitem> + <para> + To manually configure a repository, create a new configuration file (<filename>exo-jcr-configuration.xml</filename> for example). For details, see <xref linkend="chap-Reference_Guide-JCR_configuration"/>. + </para> + <para> + The configuration file must be formatted as follows: + </para> + <example> + <title>External Configuration</title> + <programlisting language="XML" role="XML"><repository-service default-repository="repository1"> + <repositories> + <repository name="repository1" system-workspace="ws1" default-workspace="ws1"> + <security-domain>exo-domain</security-domain> + <access-control>optional</access-control> + <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy> + <workspaces> + <workspace name="ws1"> + <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"> + <properties> + <property name="source-name" value="jdbcjcr" /> + <property name="dialect" value="oracle" /> + <property name="multi-db" value="false" /> + <property name="update-storage" value="false" /> + <property name="max-buffer-size" value="200k" /> + <property name="swap-directory" value="../temp/swap/production" /> + </properties> + <value-storages> + <![CDATA[]]> + </value-storages> + </container> + <initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"> + <properties> + <property name="root-nodetype" value="nt:unstructured" /> + </properties> + </initializer> + <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"> + <![CDATA[]]> + </cache> + <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <![CDATA[]]> + </query-handler> + <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"> + <![CDATA[]]> + </lock-manager> + </workspace> + <workspace name="ws2"> + ... + </workspace> + <workspace name="wsN"> + ... + </workspace> + </workspaces> + </repository> + </repositories> +</repository-service></programlisting> + <para> + Comment #1: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Value_Storage_configuration"/>. + </para> + <para> + Comment #2: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Cache_configuration"/>. + </para> + <para> + Comment #3: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Indexer_configuration"/>. + </para> + <para> + Comment #4: Refer to <xref linkend="exam-Reference_Guide-Configuration_requirements-Lock_Manager_configuration"/>. + </para> + </example> + </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"><component> + <key>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</key> + <type>org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl</type> + <init-params> + <value-param> + <name>conf-path</name> + <description>JCR configuration file</description> + <value>exo-jcr-configuration.xml</value> + </value-param> + </init-params> +</component></programlisting> + </listitem> + </itemizedlist> + </section> + </section> + <section id="sect-Reference_Guide-Cluster_Configuration-Requirements"> + <title>Requirements</title> + <section id="sect-Reference_Guide-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-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> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-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-Configuration_requirements-Value_Storage_configuration"> + <title>Value Storage configuration</title> + <programlisting language="XML" role="XML"><value-storages> + <value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> + <properties> + <property name="path" value="/mnt/tornado/temp/values/production" />  + </properties> + <filters> + <filter property-type="Binary" /> + </filters> + </value-storage> +</value-storages></programlisting> + </example> + <example id="exam-Reference_Guide-Configuration_requirements-Cache_configuration"> + <title>Cache configuration</title> + <programlisting language="XML" role="XML"><cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"> + <properties> + <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-data.xml" />  + <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />  + <property name="jbosscache-cluster-name" value="JCR_Cluster_cache_production" />  + <property name="jgroups-multiplexer-stack" value="true" /> + </properties> +</cache></programlisting> + </example> + <example id="exam-Reference_Guide-Configuration_requirements-Indexer_configuration"> + <title>Indexer configuration</title> + <programlisting language="XML" role="XML"><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <properties> + <property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /> + <property name="index-dir" value="/mnt/tornado/temp/jcrlucenedb/production" />  + <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-indexer.xml" />  + <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />  + <property name="jbosscache-cluster-name" value="JCR_Cluster_indexer_production" />  + <property name="jgroups-multiplexer-stack" value="true" /> + </properties> +</query-handler></programlisting> + </example> + <example id="exam-Reference_Guide-Configuration_requirements-Lock_Manager_configuration"> + <title>Lock Manager configuration</title> + <programlisting language="XML" role="XML"><lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl"> + <properties> + <property name="time-out" value="15m" /> + <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-lock.xml" />  + <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />  + <property name="jgroups-multiplexer-stack" value="true" /> + <property name="jbosscache-cluster-name" value="JCR_Cluster_lock_production" />  + + <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_production"/>  + <property name="jbosscache-cl-cache.jdbc.table.create" value="true"/> + <property name="jbosscache-cl-cache.jdbc.table.drop" value="false"/> + <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_production_pk"/> + <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn"/> + <property name="jbosscache-cl-cache.jdbc.node.column" value="node"/> + <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent"/> + <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr"/> + </properties> +</lock-manager></programlisting> + </example> + </section> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-JBoss_Cache_configuration"> + <title>Configuring JBoss Cache</title> + <section id="sect-Reference_Guide-JBoss_Cache_configuration-Indexer_lock_manager_and_data_container_configuration"> + <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"><property name="jbosscache-configuration" value="conf/standalone + /test-jbosscache-lock-db1-ws1.xml" /></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-<parameter name>} 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">... +<clustering mode="replication" clusterName="${jbosscache-cluster-name}"> + <stateRetrieval timeout="20000" fetchInMemoryState="false" /> +...</programlisting> + <para> + and JCR configuration file: + </para> + <programlisting language="XML" role="XML">... +<property name="jbosscache-configuration" value="jar:/conf/portal/jbosscache-lock.xml" /> +<property name="jbosscache-cluster-name" value="JCR-cluster-locks-db1-ws" /> +...</programlisting> + </section> + <section id="sect-Reference_Guide-JBoss_Cache_configuration-JGroups_configuration"> + <title>JGroups configuration</title> + <para> + JGroups is used by JBoss Cache for network communications and transport in 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"><property name="jgroups-configuration" value="your/path/to/modified-udp.xml" /></programlisting> + <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"><property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> +<property name="jgroups-multiplexer-stack" value="true" /></programlisting> + </section> + <section id="sect-Reference_Guide-JBoss_Cache_configuration-Sharing_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"><property name="jbosscache-shareable" value="true" /></programlisting> + <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><PARAM_NAME></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-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 <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/jbosscache</filename> directory, inside either the <filename>cluster</filename> or <filename>local</filename> directory. + </para> + <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Data_container_template"> + <title>Data container template</title> + <para> + The data container template is <filename>config.xml</filename>: + </para> + <programlisting language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?> +<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"> + + <locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" + lockAcquisitionTimeout="20000" /> + + <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> + <stateRetrieval timeout="20000" fetchInMemoryState="false" /> + <jgroupsConfig multiplexerStack="jcr.stack" /> + <sync /> + </clustering> + +  + <eviction wakeUpInterval="5000"> + <default algorithmClass="org.jboss.cache.eviction.LRUAlgorithm" + actionPolicyClass="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.ParentNodeEvictionActionPolicy" + eventQueueSize="1000000"> + <property name="maxNodes" value="1000000" /> + <property name="timeToLive" value="120000" /> + </default> + </eviction> +</jbosscache></programlisting> + </section> + <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template"> + <title>Lock manager template</title> + <para> + The lock manager template is <filename>lock-config.xml</filename>: + </para> + <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../extras/Advanced_Development_JCR_lock-manager-config/lock-config.xml_code"/></programlisting> + </section> + <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Query_handler_indexer_template"> + <title>Query handler (indexer) template</title> + <para> + The query handler template is called <filename>indexer-config.xml</filename>: + </para> + <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../extras/Advanced_Development_JCR_cluster-config/indexer-config.xml_code"/></programlisting> + </section> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-LockManager"> + <title>LockManager</title> + <para> + The LockManager stores lock objects. It can lock or release objects as required. It is also responsible for removing stale locks. + </para> + <para> + The LockManager in JBoss Portal Platform is implemented with <classname>org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl</classname>. + </para> + <para> + It is enabled by adding <literal>lock-manager-configuration</literal> to <literal>workspace-configuration</literal>. + </para> + <para> + For example: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../extras/default47.xml" parse="text"/></programlisting> + <section id="sect-Reference_Guide-LockManager-CacheableLockManagerImpl"> + <title>CacheableLockManagerImpl</title> + <para> + <classname>CacheableLockManagerImpl</classname> stores lock objects in JBoss-cache (which implements JDBCCacheLoader to store locks in a database). This means its locks are replicable and can affect an entire cluster rather than just a single node. + </para> + <para> + The length of time LockManager allows a lock to remain in place can be configured with the "<literal>time-out</literal>" property. + </para> + <para> + The LockRemover thread periodically polls LockManager for locks that have passed the time-out limit and must be removed. + </para> + <para> + The time-out for LockRemover is set as follows (the default value is 30m): + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default48.xml" parse="text"/></programlisting> + <para> + There are a number of ways to configure <classname>CacheableLockManagerImpl</classname>. Each involves configuring JBoss Cache and JDBCCacheLoader. + </para> + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"/> + </para> + </listitem> + </itemizedlist> + <para> + Refer to <ulink url="http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader">http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader</ulink> for more information about JBoss Cache and JDBCCacheLoader. + </para> + <section id="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration"> + <title>Simple JBoss Cache Configuration</title> + <para> + One method to configure the LockManager is to put a JBoss Cache configuration file path into <classname>CacheableLockManagerImpl</classname>. + </para> + <note> + <para> + This is not the most efficient method for configuring the LockManager as it requires a JBoss Cache configuration file for each LockManager configuration in each workspace of each repository. The configuration set up can subsequently become quite difficult to manage. + </para> + <para> + This method is useful, however, if a single, specially configured LockManager is required. + </para> + </note> + <para> + The required configuration is shown in the example below: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default49.xml" parse="text"/></programlisting> + <para> + Sample content of the <replaceable>jbosscache-lock-config.xml</replaceable> file specified in the <replaceable>jbosscache-configuration</replaceable> property is shown in the code example below. + </para> + <example> + <title>Sample Content of the jbosscache-lock-config.xml File</title> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default50.xml" parse="text"/></programlisting> + <para> + Comment #1: The cluster name at <parameter>clustering mode="replication" clusterName="JBoss-Cache-Lock-Cluster_Name"</parameter> must be unique; + </para> + <para> + Comment #2: The <parameter>cache.jdbc.table.name</parameter> must be unique per datasource. + </para> + <para> + Comment #3: The <parameter>cache.jdbc.node.type</parameter> and <parameter>cache.jdbc.fqn.type</parameter> parameters must be configured according to the database in use. Refer to the table below for information about data types. + </para> + </example> + <table id="tabl-Reference_Guide-Simple_JBoss_Cache_Configuration-Data_Types_in_Different_Databases"> + <title>Data Types in Different Databases</title> + <tgroup cols="3"> + <thead> + <row> + <entry> DataBase name </entry> + <entry> Node data type </entry> + <entry> FQN data type </entry> + </row> + </thead> + <tbody> + <row> + <entry> default </entry> + <entry> BLOB </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> HSSQL </entry> + <entry> OBJECT </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> MySQL </entry> + <entry> LONGBLOB </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> ORACLE </entry> + <entry> BLOB </entry> + <entry> VARCHAR2(512) </entry> + </row> + <row> + <entry> PostgreSQL </entry> + <entry> bytea </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> MSSQL </entry> + <entry> VARBINARY(MAX) </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> DB2 </entry> + <entry> BLOB </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> Sybase </entry> + <entry> IMAGE </entry> + <entry> VARCHAR(512) </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section id="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"> + <title>Template JBoss Cache Configuration</title> + <para> + Another method to configure LockManager is to use a JBoss Cache configuration template for all LockManagers. + </para> + <para> + Below is an example <filename>test-jbosscache-lock.xml</filename> template file: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/you.xml" parse="text"/></programlisting> + <para> + The parameters that will populate the above file are shown below: + </para> + <example> + <title>JBoss Cache Configuration Parameters</title> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default51.xml" parse="text"/></programlisting> + <para> + Comment #1: The <literal>jgroups-configuration</literal> has been moved to a separate configuration file (<filename>udp-mux.xml</filename>, shown below). In this case the <filename>udp-mux.xml</filename> is a common configuration for all JGroup components (QueryHandler, cache, LockManager), but this is not a requirement of the configuration method. + </para> + <para> + Comment #2: The <parameter>jbosscache-cl-cache.jdbc.fqn.column</parameter> and <parameter>jbosscache-cl-cache.jdbc.node.type</parameter> parameters are not explicitly defined as <parameter>cache.jdbc.fqn.type</parameter> and <parameter>cache.jdbc.node.type</parameter> are defined in the JBoss Cache configuration. + </para> + </example> + <para> + Refer to <xref linkend="tabl-Reference_Guide-Simple_JBoss_Cache_Configuration-Data_Types_in_Different_Databases"/> for information about setting these parameters or set them as <parameter>AUTO</parameter> and the data type will by detected automatically. + </para> + <para> + <filename>udp-mux.xml</filename>: + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default52.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-CacheableLockManagerImpl-Lock_migration_from_1.12.x"> + <title>Lock Migration</title> + <para> + There are three options available: + </para> + <variablelist id="vari-Reference_Guide-Lock_migration_from_1.12.x-Lock_Migration_Options"> + <title>Lock Migration Options</title> + <varlistentry> + <term>When new Shareable Cache feature is not going to be used and all locks should be kept after migration.</term> + <listitem> + <procedure> + <title/> + <step> + <para> + Ensure that the same lock tables are used in configuration + </para> + </step> + <step> + <para> + Start the server + </para> + </step> + </procedure> + </listitem> + </varlistentry> + <varlistentry> + <term>When new Shareable Cache feature is not going to be used and all locks should be removed after migration.</term> + <listitem> + <procedure> + <title/> + <step> + <para> + Ensure that the same lock tables used in configuration + </para> + </step> + <step> + <para> + Start the sever WITH system property: + </para> + <programlisting>-Dorg.exoplatform.jcr.locks.force.remove=true +</programlisting> + </step> + <step> + <para> + Stop the server + </para> + </step> + <step> + <para> + Start the server WITHOUT system property: + </para> + <programlisting>-Dorg.exoplatform.jcr.locks.force.remove +</programlisting> + </step> + </procedure> + </listitem> + </varlistentry> + <varlistentry> + <term>When new Shareable Cache feature will be used (in this case all locks are removed after migration).</term> + <listitem> + <procedure> + <title/> + <step> + <para> + Start the sever WITH system property: + </para> + <programlisting>-Dorg.exoplatform.jcr.locks.force.remove=true +</programlisting> + </step> + <step> + <para> + Stop the server. + </para> + </step> + <step> + <para> + Start the server WITHOUT system property: + </para> + <programlisting>-Dorg.exoplatform.jcr.locks.force.remove +</programlisting> + </step> + <step> + <title>Optional:</title> + <para> + Manually remove old tables for lock. + </para> + </step> + </procedure> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-QueryHandler_configuration"> + <title>Configuring QueryHandler</title> + <section id="sect-Reference_Guide-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> + <figure> + <title id="diagramlocalindez">Local Index Diagram</title> + <mediaobject> + <imageobject> + <imagedata width="444" align="center" fileref="images/eXoJCR/diagram-local-index.png"/> + </imageobject> + </mediaobject> + </figure> + <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 scenarios. 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> + <figure> + <title id="diagramsharedindex">Shared Index Diagram</title> + <mediaobject> + <imageobject> + <imagedata width="444" align="center" fileref="images/eXoJCR/diagram-shared-index.png"/> + </imageobject> + </mediaobject> + </figure> + <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="chap-Reference_Guide-Search_Configuration"/> . + </para> + </section> + <section id="sect-Reference_Guide-QueryHandler_configuration-Configuration"> + <title>Configuration</title> + <section id="sect-Reference_Guide-Configuration-Query_handler_configuration_overview"> + <title>Query-handler configuration overview</title> + <para> + Configuration example: + </para> + <programlisting language="XML" role="XML"><workspace name="ws"> + <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <properties> + <property name="index-dir" value="shareddir/index/db1/ws" /> + <property name="changesfilter-class" + value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /> + <property name="jbosscache-configuration" value="jbosscache-indexer.xml" /> + <property name="jgroups-configuration" value="udp-mux.xml" /> + <property name="jgroups-multiplexer-stack" value="true" /> + <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /> + <property name="max-volatile-time" value="60" /> + <property name="rdbms-reindexing" value="true" /> + <property name="reindexing-page-size" value="1000" /> + <property name="index-recovery-mode" value="from-coordinator" /> + <property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /> + </properties> + </query-handler> +</workspace> +</programlisting> + <table id="tabl-Reference_Guide-Query_handler_configuration_overview-Configuration_properties"> + <title>Configuration properties</title> + <tgroup cols="2"> + <thead> + <row> + <entry> Property name </entry> + <entry> Description </entry> + </row> + </thead> + <tbody> + <row> + <entry> index-dir </entry> + <entry> path to index </entry> + </row> + <row> + <entry> 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> jgroups-configuration </entry> + <entry> jgroups-configuration is template configuration for all components (search, cache, locks) [Add link to document describing template configurations] </entry> + </row> + <row> + <entry> jgroups-multiplexer-stack </entry> + <entry> [TODO about jgroups-multiplexer-stack - add link to JBoss doc] </entry> + </row> + <row> + <entry> jbosscache-cluster-name </entry> + <entry> cluster name (must be unique) </entry> + </row> + <row> + <entry> max-volatile-time </entry> + <entry> max time to live for Volatile Index </entry> + </row> + <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> 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-filter </entry> + <entry> Defines implementation class or classes of RecoveryFilters, the mechanism of index synchronization for Local Index strategy. </entry> + </row> + <row> + <entry> async-reindexing </entry> + <entry> Controls the process of re-indexing on JCR's startup. If this flag is set, indexing will be launched asynchronously, without blocking the JCR. Default is "<literal>false</literal>". </entry> + </row> + </tbody> + </tgroup> + </table> + <formalpara id="form-Reference_Guide-Query_handler_configuration_overview-Improving_Query_Performance_With_postgreSQL_and_rdbms_reindexing"> + <title>Improving Query Performance With <literal>postgreSQL</literal> and <parameter>rdbms-reindexing</parameter></title> + <para> + If you use <literal>postgreSQL</literal> and <parameter>rdbms-reindexing</parameter> is set to <literal>true</literal>, the performance of the queries used while indexing can be improved by: + </para> + </formalpara> + <procedure> + <title/> + <step> + <para> + Set the parameter "<parameter>enable_seqscan</parameter>" to "<literal>off</literal>" + </para> + <para> + <emphasis role="bold">OR</emphasis> + </para> + <para> + Set "<parameter>default_statistics_target</parameter>" to at least "<literal>50</literal>". + </para> + </step> + <step> + <para> + Restart DB server and make analyze of the JCR_SVALUE (or JCR_MVALUE) table. + </para> + </step> + </procedure> + <formalpara id="form-Reference_Guide-Query_handler_configuration_overview-Improving_Query_Performance_With_DB2_and_rdbms_reindexing"> + <title>Improving Query Performance With <literal>DB2</literal> and <parameter>rdbms-reindexing</parameter></title> + <para> + If you use <literal>DB2</literal> and <parameter>rdbms-reindexing</parameter> is set to <literal>true</literal>, the performance of the queries used while indexing can be improved by: + </para> + </formalpara> + <procedure> + <title/> + <step> + <para> + Make statistics on tables by running the following for <literal>JCR_SITEM</literal> (or <literal>JCR_MITEM</literal>) and <literal>JCR_SVALUE</literal> (or <literal>JCR_MVALUE</literal>) tables: + </para> + <programlisting><code>RUNSTATS ON TABLE <scheme>.<table> WITH DISTRIBUTION AND INDEXES ALL</code></programlisting> + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-Configuration-Cluster_ready_indexing"> + <title>Cluster-ready indexing</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"><workspace name="ws"> + <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <properties> + <property name="index-dir" value="/mnt/nfs_drive/index/db1/ws" /> + <property name="changesfilter-class" + value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /> + <property name="jbosscache-configuration" value="jbosscache-indexer.xml" /> + <property name="jgroups-configuration" value="udp-mux.xml" /> + <property name="jgroups-multiplexer-stack" value="true" /> + <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /> + <property name="max-volatile-time" value="60" /> + <property name="rdbms-reindexing" value="true" /> + <property name="reindexing-page-size" value="1000" /> + <property name="index-recovery-mode" value="from-coordinator" /> + </properties> + </query-handler> +</workspace></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> + <programlisting language="XML" role="XML"><workspace name="ws"> + <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + <properties> + <property name="index-dir" value="/mnt/nfs_drive/index/db1/ws" /> + <property name="changesfilter-class" + value="org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter" /> + <property name="jbosscache-configuration" value="jbosscache-indexer.xml" /> + <property name="jgroups-configuration" value="udp-mux.xml" /> + <property name="jgroups-multiplexer-stack" value="true" /> + <property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /> + <property name="max-volatile-time" value="60" /> + <property name="rdbms-reindexing" value="true" /> + <property name="reindexing-page-size" value="1000" /> + <property name="index-recovery-mode" value="from-coordinator" /> + </properties> + </query-handler> +</workspace> +</programlisting> + </section> + <section id="sect-Reference_Guide-Configuration-Local_Index_Recovery_Filters"> + <title>Local Index Recovery Filters</title> + <para> + A common usecase for all cluster-ready applications is a hot joining and leaving of processing units. All nodes that are joining a cluster for the first time or nodes joining after some downtime, must be in a synchronized state. + </para> + <para> + When using shared value storages, databases and indexes, cluster nodes are synchronized at any given time. But is not the case when a local index strategy is used. + </para> + <para> + If a new node joins a cluster, without an index it is retrieved or recreated. Nodes can be also be restarted and thus the index is not empty. By default, even though the existing index is thought to be up to date, it can be outdated. + </para> + <para> + The JBoss Portal Platform JCR offers a mechanism called <literal>RecoveryFilters</literal> that will automatically retrieve index for the joining node on start up. This feature is a set of filters that can be defined via <literal>QueryHandler</literal> configuration: + </para> + <programlisting language="XML"><property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /></programlisting> + <para> + Filter numbers are not limited so they can be combined: + </para> + <programlisting language="XML"><property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /> + <property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.SystemPropertyRecoveryFilter" /> +</programlisting> + <para> + If any one returns fires, the index is re-synchronized. This feature uses standard index recovery mode defined by previously described parameter (can be "from-indexing" (default) or "from-coordinator") + </para> + <programlisting language="XML"><property name="index-recovery-mode" value="from-coordinator" /> +</programlisting> + <para> + There are multiple filter implementations: + </para> + <variablelist id="vari-Reference_Guide-Local_Index_Recovery_Filters-org.exoplatform.services.jcr.impl.core.query.lucene.DummyRecoveryFilter"> + <title>org.exoplatform.services.jcr.impl.core.query.lucene.DummyRecoveryFilter</title> + <varlistentry> + <term/> + <listitem> + <para> + Always returns true, for cases when index must be force resynchronized (recovered) each time. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>org.exoplatform.services.jcr.impl.core.query.lucene.SystemPropertyRecoveryFilter</term> + <listitem> + <para> + Returns value of system property "<literal>org.exoplatform.jcr.recoveryfilter.forcereindexing</literal>". So index recovery can be controlled from the top without changing documentation using system properties. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>org.exoplatform.services.jcr.impl.core.query.lucene.ConfigurationPropertyRecoveryFilter</term> + <listitem> + <para> + Returns value of <literal>QueryHandler</literal> configuration property "<literal>index-recovery-filter-forcereindexing</literal>". So index recovery can be controlled from configuration separately for each workspace. For example: + </para> + <programlisting language="XML"><property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.ConfigurationPropertyRecoveryFilter" /> + <property name="index-recovery-filter-forcereindexing" value="true" /> +</programlisting> + </listitem> + </varlistentry> + <varlistentry> + <term>org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter</term> + <listitem> + <para> + Checks the number of documents in index on coordinator side and self-side. It returns <literal>true</literal> if the count differs. + </para> + <para> + The advantage of this filter compared to others, is that it will skip reindexing for workspaces where the index was not modified. + </para> + <para> + For example; if there is ten repositories with three workspaces in each and only one is heavily used in the cluster, this filter will only reindex those workspaces that have been changed, without affecting other indexes. + </para> + <para> + This greatly reduces start up time. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-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 id="exam-Reference_Guide-JBoss_Cache_template_configuration-jbosscache_indexer.xml"> + <title>jbosscache-indexer.xml</title> + <programlisting language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?> +<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"> + <locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" + lockAcquisitionTimeout="20000" /> +  + <transaction transactionManagerLookupClass="org.jboss.cache.transaction.JBossStandalone + JTAManagerLookup" /> + <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> + <stateRetrieval timeout="20000" fetchInMemoryState="false" /> + <jgroupsConfig multiplexerStack="jcr.stack" /> + <sync /> + </clustering> +  + <eviction wakeUpInterval="5000"> + <default algorithmClass="org.jboss.cache.eviction.FIFOAlgorithm" eventQueueSize="1000000"> + <property name="maxNodes" value="10000" /> + <property name="minTimeToLive" value="60000" /> + </default> + </eviction> +</jbosscache></programlisting> + </example> + <para> + Read more about template configurations <xref linkend="chap-Reference_Guide-JBoss_Cache_configuration"/>. + </para> + </section> + </section> + <section id="sect-Reference_Guide-QueryHandler_configuration-Asynchronous_Reindexing"> + <title>Asynchronous Re-indexing</title> + <para> + Managing a large data set using a JCR in a production environment at times requires special operations with Indexes, stored on File System. One of those maintenance operations is a recreation of it. Also called "re-indexing". There are various usecases when it's important to do. They include hardware faults, hard restarts, data-corruption, migrations and JCR updates that brings new features related to index. Usually index re-creation requested on server's startup or in runtime. + </para> + <section id="sect-Reference_Guide-Asynchronous_Reindexing-On_startup_indexing"> + <title>On startup indexing</title> + <para> + A common usecase for updating and re-creating the index is to stop the server and manually remove indexes for workspaces requiring it. When the server is re-started, the missing indexes are automatically recovered by re-indexing. + </para> + <para> + The eXo JCR Supports direct RDBMS re-indexing, which can be faster than ordinary and can be configured via <literal>QueryHandler</literal> parameter <parameter>rdbms-reindexing</parameter> set to <literal>true</literal>. + </para> + <para> + A new feature is asynchronous indexing on startup. Usually startup is blocked until the indexing process is finished. This block can take any period of time, depending on amount of data persisted in repositories. But this can be resolved by using an asynchronous approaches of startup indexation. + </para> + <para> + Essentially, all indexing operations are performed in the background without blocking the repository. This is controlled by the value of the <parameter>async-reindexing</parameter> parameter in <literal>QueryHandler</literal> configuration. + </para> + <para> + With asynchronous indexation active, the JCR starts with no active indexes present. Queries on JCR still can be executed without exceptions, but no results will be returned until index creation completed. + </para> + <para> + The index state check is accomplished via <literal>QueryManagerImpl</literal>: + </para> + <para> + +<programlisting lang="java">boolean online = ((QueryManagerImpl)Workspace.getQueryManager()).getQueryHandeler().isOnline();</programlisting> + + </para> + <para> + The <emphasis role="bold">OFFLINE</emphasis> state means that the index is currently re-creating. When the state is changed, a corresponding log event is printed. When the background index task starts the index is switched to <emphasis role="bold">OFFLINE</emphasis>, with following log event : + </para> + <programlisting>[INFO] Setting index OFFLINE (repository/production[system]).</programlisting> + <para> + When the indexing process is finished, the following two events are logged : + </para> + <programlisting>[INFO] Created initial index for 143018 nodes (repository/production[system]). +[INFO] Setting index ONLINE (repository/production[system]).</programlisting> + <para> + Those two log lines indicates the end of process for workspace given in brackets. Calling isOnline() as mentioned above, will also return true. + </para> + </section> + <section id="sect-Reference_Guide-Asynchronous_Reindexing-Hot_Asynchronous_Workspace_Reindexing_via_JMX"> + <title>Hot Asynchronous Workspace Re-indexing using JMX</title> + <para> + Some hard system faults, errors during upgrades, migration issues and some other factors may corrupt the index. Current versions of JCR supports <emphasis role="bold">Hot Asynchronous Workspace Reindexing</emphasis> feature. It allows Service Administrators to launch the process in background without stopping or blocking the whole application by using any JMX-compatible console. + </para> + <figure> + <title id="jmx-jconsole">JMX Jconsole</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/eXoJCR/jmx-jconsole.png"/> + </imageobject> + </mediaobject> + </figure> + <para> + The server can continue working as expected while the index is recreated. + </para> + <para> + This depends on the flag <parameter>allow queries</parameter> being passed via JMX interface to the reindex operation invocation. If the flag is set, the application continues working. + </para> + <para> + However, there is one critical limitation users must be aware of; <emphasis>the index is frozen while the background task is running</emphasis>. + </para> + <para> + This means that queries are performed on a version of the index present at the moment the indexing task is started, and that data written into the repository after startup will not be available through the search until process completes. + </para> + <para> + Data added during re-indexation is also indexed, but will be available only when reindexing is complete. The JCR makes a snapshot of indexes at the invocation of the asynchronous indexing task and uses that snapshot for searches. + </para> + <para> + When the operation is finished, the stale index is replaced by the newly created index, which included any newly added data. + </para> + <para> + If the <parameter>allow queries</parameter> flag is set to <literal>false</literal>, then all queries will throw an exception while task is running. The current state can be acquired using the following JMX operation: + </para> + <itemizedlist> + <listitem> + <para> + getHotReindexingState() - returns information about latest invocation: start time, if in progress or finish time if done. + </para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-Asynchronous_Reindexing-Notices"> + <title>Notices</title> + <para> + Hot re-indexing via JMX cannot be launched if the index is already in offline mode. This means that the index is currently involved in some other operations, such as re-indexing at startup, copying in cluster to another node or whatever. + </para> + <para> + Also; <emphasis>Hot Asynchronous Reindexing via JMX</emphasis> and <literal>on startup</literal> reindexing are different features. So you can't get the state of startup reindexing using command <code>getHotReindexingState</code> in JMX interface, but there are some common JMX operations: + </para> + <itemizedlist> + <listitem> + <para> + getIOMode - returns current index IO mode (READ_ONLY / READ_WRITE), belongs to clustered configuration states; + </para> + </listitem> + <listitem> + <para> + getState - returns current state: ONLINE / OFFLINE. + </para> + </listitem> + </itemizedlist> + </section> + </section> + <section id="sect-Reference_Guide-QueryHandler_configuration-Advanced_tuning"> + <title>Advanced tuning</title> + <section id="sect-Reference_Guide-Advanced_tuning-Lucene_tuning"> + <title>Lucene tuning</title> + <para> + As mentioned, JCR Indexing is based on the Lucene indexing library as the underlying search engine. It uses Directories to store index and manages access to index by Lock Factories. + </para> + <para> + By default, the JCR implementation uses optimal combination of Directory implementation and Lock Factory implementation. + </para> + <para> + The <literal>SimpleFSDirectory</literal> is used in Windows environments and the <literal>NIOFSDirectory</literal> implementation is used in non-Windows systems. + </para> + <para> + <literal>NativeFSLockFactory</literal> is an optimal solution for a wide variety of cases including clustered environment with NFS shared resources. + </para> + <para> + But those defaults can be overridden in the system properties. + </para> + <para> + Two properties: <literal>org.exoplatform.jcr.lucene.store.FSDirectoryLockFactoryClass</literal> and <literal>org.exoplatform.jcr.lucene.FSDirectory.class</literal> control (and change) the default behavior. + </para> + <para> + The first defines the implementation of abstract Lucene <literal>LockFactory</literal> class and the second sets implementation class for <literal>FSDirectory</literal> instances. + </para> + <para> + For more information, refer to the Lucene documentation. But be careful, for while the JCR allows users to change implementation classes of Lucene internals, it does not guarantee the stability and functionality of those changes. + </para> + </section> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-JBossTransactionsService"> + <title>JBossTransactionsService</title> + <section id="sect-Reference_Guide-JBossTransactionsService-Introduction"> + <title>Introduction</title> + <para> + JBossTransactionsService implements eXo TransactionService and provides access to <ulink url="http://www.jboss.org/jbosstm/">JBoss Transaction Service (JBossTS)</ulink> JTA implementation via eXo container dependency. + </para> + <para> + TransactionService used in JCR cache <emphasis>org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache</emphasis> implementation. + </para> + </section> + <section id="sect-Reference_Guide-JBossTransactionsService-Configuration"> + <title>Configuration</title> + <para> + Example configuration: + </para> + <programlisting language="XML" role="XML"> <component> + <key>org.exoplatform.services.transaction.TransactionService</key> + <type>org.exoplatform.services.transaction.jbosscache.JBossTransactionsService</type> + <init-params> + <value-param> + <name>timeout</name> + <value>3000</value> + </value-param> + </init-params> + </component></programlisting> + <para> + timeout - XA transaction timeout in seconds + </para> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-JCR_Query_Usecases"> + <title>JCR Query Use-cases</title> + <section id="sect-Reference_Guide-JCR_Query_Usecases-Introduction"> + <title>Introduction</title> + <para> + The JCR supports two query languages; JCR and XPath. A query, whether XPath or SQL, specifies a subset of nodes within a workspace, called the result set. The result set constitutes all the nodes in the workspace that meet the constraints stated in the query. + </para> + </section> + <section id="sect-Reference_Guide-JCR_Query_Usecases-Query_Lifecycle"> + <title>Query Lifecycle</title> + <section id="sect-Reference_Guide-Query_Lifecycle-Query_Creation_and_Execution"> + <title>Query Creation and Execution</title> + <example id="exam-Reference_Guide-Query_Lifecycle-Query_Creation_and_Execution-SQL"> + <title>SQL</title> + <programlisting language="Java" role="Java">// get QueryManager +QueryManager queryManager = workspace.getQueryManager();  +// make SQL query +Query query = queryManager.createQuery("SELECT * FROM nt:base ", Query.SQL); +// execute query +QueryResult result = query.execute();</programlisting> + </example> + <example id="exam-Reference_Guide-Query_Lifecycle-Query_Creation_and_Execution-XPath"> + <title>XPath</title> + <programlisting language="Java" role="Java">// get QueryManager +QueryManager queryManager = workspace.getQueryManager(); +// make XPath query +Query query = queryManager.createQuery("//element(*,nt:base)", Query.XPATH); +// execute query +QueryResult result = query.execute();</programlisting> + </example> + </section> + <section id="sect-Reference_Guide-Query_Lifecycle-Query_Result_Processing"> + <title>Query Result Processing</title> + <programlisting language="Java" role="Java">// fetch query result +QueryResult result = query.execute();</programlisting> + <para> + To fetch the nodes: + </para> + <programlisting language="Java" role="Java">NodeIterator it = result.getNodes();</programlisting> + <para> + The results can be formatted in a table: + </para> + <programlisting language="Java" role="Java">// get column names +String[] columnNames = result.getColumnNames(); +// get column rows +RowIterator rowIterator = result.getRows(); +while(rowIterator.hasNext()){ + // get next row + Row row = rowIterator.nextRow(); + // get all values of row + Value[] values = row.getValues(); +}</programlisting> + </section> + <section id="sect-Reference_Guide-Query_Lifecycle-Scoring"> + <title>Scoring</title> + <para> + The result returns a score for each row in the result set. The score contains a value that indicates a rating of how well the result node matches the query. A high value means a better matching than a low value. This score can be used for ordering the result. + </para> + <para> + eXo JCR Scoring is a mapping of Lucene scoring. For a more in-depth understanding, please study <ulink url="http://lucene.apache.org/java/2_4_1/scoring.html">Lucene documentation</ulink>. + </para> + <para> + The <literal>jcr:score</literal> is calculated as; <literal>(lucene score)*1000f</literal>. + </para> + </section> + </section> + <section id="sect-Reference_Guide-JCR_Query_Usecases-Tips_and_tricks"> + <title>Tips and tricks</title> + <section xmlns="" id="sect-Reference_Guide-XPath_queries_containing_node_names_starting_with_a_number"> + <title>XPath queries containing node names starting with a number</title> + <para> + If you execute an XPath request like this... + </para> + <programlisting language="Java" role="Java">// get QueryManager +QueryManager queryManager = workspace.getQueryManager(); +// make XPath query +Query query = queryManager.createQuery("/jcr:root/Documents/Publie/2010//element(*, exo:article)", Query.XPATH);</programlisting> + <para> + ...you will receive an <code>Invalid request</code> error. This is because XML (and thus XPath) does not allow names starting with a number. + </para> + <para> + Therefore, XPath requests using a node name that starts with a number are invalid. + </para> + <para> + Some possible alternatives are: + </para> + <itemizedlist> + <listitem> + <para> + Use an SQL request. + </para> + </listitem> + <listitem> + <para> + Use escaping: + </para> + <programlisting language="Java" role="Java">// get QueryManager +QueryManager queryManager = workspace.getQueryManager(); +// make XPath query +Query query = queryManager.createQuery("/jcr:root/Documents/Publie/_x0032_010//element(*, exo:article)", Query.XPATH);</programlisting> + </listitem> + </itemizedlist> + </section> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-Searching_Repository_Content"> + <title>Searching Repository Content</title> + <section id="sect-Reference_Guide-Searching_Repository_Content-Introduction"> + <title>Introduction</title> + <para> + You can find the JCR configuration file here: <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + </para> + <para> + Please refer to <xref linkend="chap-Reference_Guide-Search_Configuration"/> for more information about index configuration. + </para> + </section> + <section id="sect-Reference_Guide-Searching_Repository_Content-Bi_directional_RangeIterator"> + <title>Bi-directional RangeIterator</title> + <para> + <literal>QueryResult.getNodes()</literal> will return bi-directional <literal>NodeIterator</literal> implementation. + </para> + <note> + <para> + Bi-directional NodeIterator is <emphasis role="bold">not supported</emphasis> in two cases: + </para> + <orderedlist> + <listitem> + <para> + SQL query: select * from nt:base + </para> + </listitem> + <listitem> + <para> + XPath query: //* . + </para> + </listitem> + </orderedlist> + </note> + <para> + <literal>TwoWayRangeIterator</literal> interface: + </para> + <programlisting language="Java" role="Java">/** + * Skip a number of elements in the iterator. + * + * @param skipNum the non-negative number of elements to skip + * @throws java.util.NoSuchElementException if skipped past the first element + * in the iterator. + */ +public void skipBack(long skipNum);</programlisting> + <para> + Usage: + </para> + <programlisting language="Java" role="Java">NodeIterator iter = queryResult.getNodes(); +while (iter.hasNext()) { + if (skipForward) { + iter.skip(10); // Skip 10 nodes in forward direction + } else if (skipBack) { + TwoWayRangeIterator backIter = (TwoWayRangeIterator) iter; + backIter.skipBack(10); // Skip 10 nodes back + } + ....... +}</programlisting> + </section> + <section id="sect-Reference_Guide-Searching_Repository_Content-Fuzzy_Searches"> + <title>Fuzzy Searches</title> + <para> + The JBoss Portal Platform JCR supports features such as Lucene Fuzzy Searches. To perform a fuzzy search, form your query like the one below: + </para> + <programlisting language="Java" role="Java">QueryManager qman = session.getWorkspace().getQueryManager(); +Query q = qman.createQuery("select * from nt:base where contains(field, 'ccccc~')", Query.SQL); +QueryResult res = q.execute();</programlisting> + </section> + <section id="sect-Reference_Guide-Searching_Repository_Content-SynonymSearch"> + <title>SynonymSearch</title> + <para> + Searching with synonyms is integrated in the <literal>jcr:contains()</literal> function and uses the same syntax as synonym searches in web search engines (Google, for example). If a search term is prefixed by a tilde symbol ( ~ ), synonyms of the search term are taken into consideration. For example: + </para> + <programlisting>SQL: select * from nt:resource where contains(., '~parameter') + +XPath: //element(*, nt:resource)[jcr:contains(., '~parameter')</programlisting> + <para> + This feature is disabled by default and you need to add a configuration parameter to the query-handler element in your JCR configuration file to enable it. + </para> + <programlisting language="XML" role="XML"><param name="synonymprovider-config-path" value="..you path to configuration file....."/> +<param name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider"/></programlisting> + <programlisting language="XML" role="XML">/** + * <code>SynonymProvider</code> defines an interface for a component that + * returns synonyms for a given term. + */ +public interface SynonymProvider { + + /** + * Initializes the synonym provider and passes the file system resource to + * the synonym provider configuration defined by the configuration value of + * the <code>synonymProviderConfigPath</code> parameter. The resource may be + * <code>null</code> if the configuration parameter is not set. + * + * @param fsr the file system resource to the synonym provider + * configuration. + * @throws IOException if an error occurs while initializing the synonym + * provider. + */ + public void initialize(InputStream fsr) throws IOException; + + /** + * Returns an array of terms that are considered synonyms for the given + * <code>term</code>. + * + * @param term a search term. + * @return an array of synonyms for the given <code>term</code> or an empty + * array if no synonyms are known. + */ + public String[] getSynonyms(String term); +}</programlisting> + </section> + <section id="sect-Reference_Guide-Searching_Repository_Content-Highlighting"> + <title>Highlighting</title> + <para> + An <literal>ExcerptProvider</literal> retrieves text excerpts for a node in the query result and marks up the words in the text that match the query terms. + </para> + <para> + By default, match highlighting is disabled because as it requires that additional information is written to the search index. + </para> + <para> + To enable this feature, you need to add a configuration parameter to the <parameter>query-handler</parameter> element in your JCR configuration file: + </para> + <programlisting language="XML" role="XML"><param name="support-highlighting" value="true"/></programlisting> + <para> + Additionally, there is a parameter that controls the format of the excerpt created. In JCR 1.9, the default is set to <literal>org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt</literal>. The configuration parameter for this setting is: + </para> + <programlisting language="XML" role="XML"><param name="excerptprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.DefaultXMLExcerpt"/></programlisting> + <section id="sect-Reference_Guide-Highlighting-DefaultXMLExcerpt"> + <title>DefaultXMLExcerpt</title> + <para> + This excerpt provider creates an XML fragment of the following form: + </para> + <programlisting language="XML" role="XML"><excerpt> + <fragment> + <highlight>exoplatform</highlight> implements both the mandatory + XPath and optional SQL <highlight>query</highlight> syntax. + </fragment> + <fragment> + Before parsing the XPath <highlight>query</highlight> in + <highlight>exoplatform</highlight>, the statement is surrounded + </fragment> +</excerpt></programlisting> + </section> + <section id="sect-Reference_Guide-Highlighting-DefaultHTMLExcerpt"> + <title>DefaultHTMLExcerpt</title> + <para> + This excerpt provider creates an HTML fragment of the following form: + </para> + <programlisting language="HTML" role="HTML"><div> + <span> + <strong>exoplatform</strong> implements both the mandatory XPath + and optional SQL <strong>query</strong> syntax. + </span> + <span> + Before parsing the XPath <strong>query</strong> in + <strong>exoplatform</strong>, the statement is surrounded + </span> +</div></programlisting> + </section> + <section id="sect-Reference_Guide-Highlighting-Usage"> + <title>Usage</title> + <para> + If you are using XPath, you must use the <code>rep:excerpt()</code> function in the last location step, just like you would select properties: + </para> + <programlisting language="Java" role="Java">QueryManager qm = session.getWorkspace().getQueryManager(); +Query q = qm.createQuery("//*[jcr:contains(., 'exoplatform')]/(@Title|rep:excerpt(.))", Query.XPATH); +QueryResult result = q.execute(); +for (RowIterator it = result.getRows(); it.hasNext(); ) { + Row r = it.nextRow(); + Value title = r.getValue("Title"); + Value excerpt = r.getValue("rep:excerpt(.)"); +}</programlisting> + <para> + The above code searches for nodes that contain the word <emphasis>exoplatform</emphasis> and then gets the value of the <parameter>Title</parameter> property and an excerpt for each resultant node. + </para> + <para> + It is also possible to use a relative path in the call <code>Row.getValue()</code> while the query statement still remains the same. Also, you may use a relative path to a string property. The returned value will then be an excerpt based on string value of the property. + </para> + <para> + Both available excerpt providers will create fragments of about 150 characters and up to three fragments. + </para> + <para> + In SQL, the function is called <code>excerpt()</code> without the rep prefix, but the column in the <literal>RowIterator</literal> will nonetheless be labelled <code>rep:excerpt(.)</code>. + </para> + <programlisting language="Java" role="Java">QueryManager qm = session.getWorkspace().getQueryManager(); +Query q = qm.createQuery("select excerpt(.) from nt:resource where contains(., 'exoplatform')", Query.SQL); +QueryResult result = q.execute(); +for (RowIterator it = result.getRows(); it.hasNext(); ) { + Row r = it.nextRow(); + Value excerpt = r.getValue("rep:excerpt(.)"); +}</programlisting> + </section> + </section> + <section id="sect-Reference_Guide-Searching_Repository_Content-SpellChecker"> + <title>SpellChecker</title> + <para> + The lucene based query handler implementation supports a pluggable spell-checker mechanism. By default, spell checking is not available, it must be configured first. + </para> + <para> + Information about the <parameter>spellCheckerClass</parameter> parameter is available in <xref linkend="chap-Reference_Guide-Search_Configuration"/>. + </para> + <para> + The JCR currently provides an implementation class which uses the <ulink url="http://wiki.apache.org/jakarta-lucene/SpellChecker">lucene-spellchecker</ulink>. + </para> + <para> + The dictionary is derived from the fulltext, indexed content of the workspace and updated periodically. You can configure the refresh interval by picking one of the available inner classes of <literal>org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker</literal>: + </para> + <itemizedlist> + <listitem> + <para> + <literal>OneMinuteRefreshInterval</literal> + </para> + </listitem> + <listitem> + <para> + <literal>FiveMinutesRefreshInterval</literal> + </para> + </listitem> + <listitem> + <para> + <literal>ThirtyMinutesRefreshInterval</literal> + </para> + </listitem> + <listitem> + <para> + <literal>OneHourRefreshInterval</literal> + </para> + </listitem> + <listitem> + <para> + <literal>SixHoursRefreshInterval</literal> + </para> + </listitem> + <listitem> + <para> + <literal>TwelveHoursRefreshInterval</literal> + </para> + </listitem> + <listitem> + <para> + <literal>OneDayRefreshInterval</literal> + </para> + </listitem> + </itemizedlist> + <para> + For example, if you want a refresh interval of six hours, the class name would be; <literal>org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$SixHoursRefreshInterval</literal>. + </para> + <para> + If you use <literal>org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker</literal>, the refresh interval will be one hour. + </para> + <para> + The spell checker dictionary is stored as a lucene index under <filename><index-dir>/spellchecker</filename>. If this index does not exist, a background thread will create it on start up. Similarly, the dictionary refresh is also done in a background thread so as not to block regular queries. + </para> + <section id="sect-Reference_Guide-SpellChecker-Usage"> + <title>Usage</title> + <para> + You can spell check a fulltext statement either with an XPath or a SQL query: + </para> + <programlisting language="Java" role="Java">// rep:spellcheck('explatform') will always evaluate to true +Query query = qm.createQuery("/jcr:root[rep:spellcheck('explatform')]/(rep:spellcheck())", Query.XPATH); +RowIterator rows = query.execute().getRows(); +// the above query will always return the root node no matter what string we check +Row r = rows.nextRow(); +// get the result of the spell checking +Value v = r.getValue("rep:spellcheck()"); +if (v == null) { + // no suggestion returned, the spelling is correct or the spell checker + // does not know how to correct it. +} else { + String suggestion = v.getString(); +}</programlisting> + <para> + And the same using SQL: + </para> + <programlisting language="Java" role="Java">// SPELLCHECK('exoplatform') will always evaluate to true +Query query = qm.createQuery("SELECT rep:spellcheck() FROM nt:base WHERE jcr:path = '/' AND SPELLCHECK('explatform')", Query.SQL); +RowIterator rows = query.execute().getRows(); +// the above query will always return the root node no matter what string we check +Row r = rows.nextRow(); +// get the result of the spell checking +Value v = r.getValue("rep:spellcheck()"); +if (v == null) { + // no suggestion returned, the spelling is correct or the spell checker + // does not know how to correct it. +} else { + String suggestion = v.getString(); +}</programlisting> + </section> + </section> + <section id="sect-Reference_Guide-Searching_Repository_Content-Similarity"> + <title>Similarity</title> + <para> + Starting with version, 1.12 JCR allows you to search for nodes that are similar to an existing node. + </para> + <para> + Similarity is determined by looking up terms that are common to nodes. There are some conditions that must be met for a term to be considered. This is required to limit the number possibly relevant terms. + </para> + <para> + To be considered, terms must: + </para> + <itemizedlist> + <listitem> + <para> + Be at least four characters long. + </para> + </listitem> + <listitem> + <para> + Occur at least twice in the source node. + </para> + </listitem> + <listitem> + <para> + Occur in at least five other nodes. + </para> + </listitem> + </itemizedlist> + <note> + <title>Note</title> + <para> + The similarity function requires that the support Hightlighting is enabled. Please make sure that you have the following parameter set for the query handler in your <filename>workspace.xml</filename>. + </para> + <programlisting language="XML" role="XML"><param name="support-highlighting" value="true"/></programlisting> + </note> + <para> + The functions (<code>rep:similar()</code> in XPath and <code>similar()</code> in SQL) have two arguments: + </para> + <variablelist> + <title/> + <varlistentry> + <term>relativePath</term> + <listitem> + <para> + A relative path to a descendant node or a period (<literal>.</literal>) for the current node. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>absoluteStringPath</term> + <listitem> + <para> + A string literal that contains the path to the node for which to find similar nodes. + </para> + </listitem> + </varlistentry> + </variablelist> + <warning> + <title>Warning</title> + <para> + Relative path is not supported yet. + </para> + </warning> + <example id="exam-Reference_Guide-Similarity-Example"> + <title>Example</title> + <programlisting>//element(*, nt:resource)[rep:similar(., '/parentnode/node.txt/jcr:content')]</programlisting> + <para> + Finds <literal>nt:resource</literal> nodes, which are similar to node by path <filename>/parentnode/node.txt/jcr:content</filename>. + </para> + </example> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-Fulltext_Search_And_Affecting_Settings"> + <title>Full Text Search And Affecting Settings</title> + <formalpara id="form-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Property_content_indexing"> + <title>Property content indexing</title> + <para> + Each property of a node (if it is indexable) is processed with the Lucene analyzer and stored in the Lucene index. This is called indexing of a property. It allows fulltext searching of these indexed properties. + </para> + </formalpara> + <section id="sect-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Lucene_Analyzers"> + <title>Lucene Analyzers</title> + <para> + The purpose of analyzers is to transform all strings stored in the index into a well-defined condition. The same analyzer(s) is/are used when searching in order to adapt the query string to the index reality. + </para> + <para> + Therefore, performing the same query using different analyzers can return different results. + </para> + <para> + The example below illustrates how the same string is transformed by different analyzers. + </para> + <table id="tabl-Reference_Guide-Lucene_Analyzers-The_quick_brown_fox_jumped_over_the_lazy_dogs"> + <title>"The quick brown fox jumped over the lazy dogs"</title> + <tgroup cols="2"> + <thead> + <row> + <entry> Analyzer </entry> + <entry> Parsed </entry> + </row> + </thead> + <tbody> + <row> + <entry> org.apache.lucene.analysis.WhitespaceAnalyzer </entry> + <entry> [The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.SimpleAnalyzer </entry> + <entry> [the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.StopAnalyzer </entry> + <entry> [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.standard.StandardAnalyzer </entry> + <entry> [quick] [brown] [fox] [jumped] [over] [lazy] [dogs] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.snowball.SnowballAnalyzer </entry> + <entry> [quick] [brown] [fox] [jump] [over] [lazi] [dog] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.standard.StandardAnalyzer (configured without stop word - jcr default analyzer) </entry> + <entry> [the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] </entry> + </row> + </tbody> + </tgroup> + </table> + <table id="tabl-Reference_Guide-Lucene_Analyzers-XYampZ_Corporation_xyzexample.com"> + <title>"XY&Z Corporation - xyz(a)example.com"</title> + <tgroup cols="2"> + <thead> + <row> + <entry> Analyzer </entry> + <entry> Parsed </entry> + </row> + </thead> + <tbody> + <row> + <entry> org.apache.lucene.analysis.WhitespaceAnalyzer </entry> + <entry> [XY&Z] [Corporation] [-] [xyz(a)example.com] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.SimpleAnalyzer </entry> + <entry> [xy] [z] [corporation] [xyz] [example] [com] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.StopAnalyzer </entry> + <entry> [xy] [z] [corporation] [xyz] [example] [com] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.standard.StandardAnalyzer </entry> + <entry> [xy&z] [corporation] [xyz@example] [com] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.snowball.SnowballAnalyzer </entry> + <entry> [xy&z] [corpor] [xyz@exampl] [com] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.standard.StandardAnalyzer (configured without stop word - jcr default analyzer) </entry> + <entry> [xy&z] [corporation] [xyz@example] [com] </entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <para> + <literal>StandardAnalyzer</literal> is the default analyzer in the JBoss Portal Platform JCR search engine. But it does not use stop words. + </para> + </note> + <para> + You can assign your analyzer as described in <xref linkend="chap-Reference_Guide-Search_Configuration"/>. + </para> + </section> + <section id="sect-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Property_Indexing"> + <title>Property Indexing</title> + <para> + Different properties are indexed in different ways and this affects whether it can be searched via fulltext by property or not. + </para> + <para> + Only two property types are indexed as fulltext searcheable: <parameter>STRING</parameter> and <parameter>BINARY</parameter>. + </para> + <table id="tabl-Reference_Guide-Property_Indexing-Fulltext_search_by_different_properties"> + <title>Fulltext search by different properties</title> + <tgroup cols="3"> + <thead> + <row> + <entry> Property Type </entry> + <entry> Fulltext search by all properties </entry> + <entry> Fulltext search by exact property </entry> + </row> + </thead> + <tbody> + <row> + <entry> STRING </entry> + <entry> YES </entry> + <entry> YES </entry> + </row> + <row> + <entry> BINARY </entry> + <entry> YES </entry> + <entry> NO </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + For example, the <literal>jcr:data</literal> property (which is <parameter>BINARY</parameter>) will not be found with a query structured as: + </para> + <programlisting>SELECT * FROM nt:resource WHERE CONTAINS(jcr:data, 'some string')</programlisting> + <para> + This is because, <parameter>BINARY</parameter> is not searchable by fulltext search by exact property. + </para> + <para> + However, the following query <emphasis>will</emphasis> return some results (provided, of course they node contains the targeted data): + </para> + <programlisting>SELECT * FROM nt:resource WHERE CONTAINS( * , 'some string')</programlisting> + </section> + <section id="sect-Reference_Guide-Fulltext_Search_And_Affecting_Settings-Different_Analyzers"> + <title>Different Analyzers</title> + <para> + First of all, we will fill repository by nodes with mixin type 'mix:title' and different values of 'jcr:description' property. + </para> + <programlisting>root + ├── document1 (mix:title) jcr:description = "The quick brown fox jumped over the lazy dogs" + ├── document2 (mix:title) jcr:description = "Brown fox live in forest." + └── document3 (mix:title) jcr:description = "Fox is a nice animal." +</programlisting> + <para> + The example below shows different Analyzers in action. The first instance uses base JCR settings, so the string; "<emphasis>The quick brown fox jumped over the lazy dogs</emphasis>" will be transformed to the set; <emphasis role="bold">{[the] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dogs] }</emphasis>. + </para> + <programlisting language="Java" role="Java">// make SQL query +QueryManager queryManager = workspace.getQueryManager(); +String sqlStatement = "SELECT * FROM mix:title WHERE CONTAINS(jcr:description, 'the')"; +// create query +Query query = queryManager.createQuery(sqlStatement, Query.SQL); +// execute query and fetch result +QueryResult result = query.execute();</programlisting> + <para> + The <literal>NodeIterator</literal> will return <emphasis>document1</emphasis>. + </para> + <para> + However, if the default analyzer is changed to <literal>org.apache.lucene.analysis.StopAnalyzer</literal>, the repository populated again (the new Analyzer must process node properties) and the same query run, it will return nothing, because stop words like "<emphasis>the</emphasis>" will be excluded from parsed string set. + </para> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-WebDAV"> + <title>WebDAV</title> + <section id="sect-Reference_Guide-WebDAV-Introduction"> + <title>Introduction</title> + <para> + The <application>WebDAV</application> protocol enables you to use third party tools to communicate with hierarchical content servers via the HTTP protocol. It is possible to add and remove documents or a set of documents from a path on the server. + </para> + <para> + <application>DeltaV</application> is an extension of the WebDav protocol that allows managing document versioning. The <emphasis>Locking</emphasis> feature guarantees protection against multiple access when writing resources. The ordering support allows changing the position of the resource in the list and sort the directory to make the directory tree viewed conveniently. The full-text search makes it easy to find the necessary documents. You can search by using two languages: SQL and XPATH. + </para> + <para> + In the eXo JCR, the WebDAV layer (based on the code taken from the extension modules of the reference implementation) is plugged in on top of our JCR implementation. This makes it possible to browse a workspace using the third party tools regardless of operating system environments. You can use a Java WebDAV client, such as <application>DAVExplorer</application> or <application>Internet Explorer</application> using <menuchoice> + <guimenu>File</guimenu> + <guimenuitem>Open as a Web Folder</guimenuitem> + </menuchoice>. + </para> + <para> + WebDav is an extension of the REST service. To get the WebDav server ready, you must deploy the REST application. Then, you can access any workspaces of your repository by using the following URL: + </para> + <para> + <ulink url="http://host:port/portal/rest/private/jcr/{RepositoryName}/{WorkspaceName}..." type="http"/> + </para> + <para> + When accessing the WebDAV server via <ulink url="http://localhost:8080/rest/jcr/repository/production" type="http"/>, you can substitute <ulink url="http://localhost:8080/rest/jcr/repository/production" type="http">production</ulink> with <ulink url="http://localhost:8080/rest/jcr/repository/collaboration" type="http">collaboration</ulink>. + </para> + <para> + You will be asked to enter your login credentials. These will then be checked by using the organization service that can be implemented thanks to an InMemory (dummy) module or a DB module or an LDAP one and the JCR user session will be created with the correct JCR Credentials. + </para> + <note> + <title>Note:</title> + <para> + If you try the "in ECM" option, add "@ecm" to the user's password. Alternatively, you may modify jaas.conf by adding the <emphasis role="bold">domain=ecm</emphasis> option as follows: + </para> + <programlisting>exo-domain { + org.exoplatform.services.security.jaas.BasicLoginModule required domain=ecm; +};</programlisting> + </note> + </section> + <section id="sect-Reference_Guide-WebDAV-WebDAV_Configuration"> + <title>WebDAV Configuration</title> + <para> + The WebDAV configuration file: + </para> + <programlisting language="XML" role="XML"><component> + <key>org.exoplatform.services.webdav.WebDavServiceImpl</key> + <type>org.exoplatform.services.webdav.WebDavServiceImpl</type> + <init-params> + +  +  + +  + <value-param> + <name>auth-header</name> + <value>Basic realm="eXo-Platform Webdav Server 1.6.1"</value> + </value-param> + +  + <value-param> + <name>def-folder-node-type</name> + <value>nt:folder</value> + </value-param> + +  + <value-param> + <name>def-file-node-type</name> + <value>nt:file</value> + </value-param> + +  + <value-param> + <name>def-file-mimetype</name> + <value>application/octet-stream</value> + </value-param> + +  + + <value-param> + <name>update-policy</name> + <value>create-version</value> +  +  + </value-param> + +  + <value-param> + <name>auto-version</name> + <value>checkout-checkin</value> +  + </value-param> + +  + <value-param> + <name>cache-control</name> + <value>text/xml,text/html:max-age=3600;image/png,image/jpg:max-age=1800;*/*:no-cache;</value> + </value-param> + +  + <value-param> + <name>folder-icon-path</name> + <value>/absolute/path/to/file</value> + </value-param> + + </init-params> +</component></programlisting> + </section> + <section id="sect-Reference_Guide-WebDAV-Corresponding_WebDav_and_JCR_actions"> + <title>Corresponding WebDAV and JCR actions</title> + <table> + <title/> + <tgroup cols="2"> + <thead> + <row> + <entry> WebDav </entry> + <entry> JCR </entry> + </row> + </thead> + <tbody> + <row> + <entry> COPY </entry> + <entry> Workspace.copy(...) </entry> + </row> + <row> + <entry> DELETE </entry> + <entry> Node.remove() </entry> + </row> + <row> + <entry> GET </entry> + <entry> Node.getProperty(...); Property.getValue() </entry> + </row> + <row> + <entry> HEAD </entry> + <entry> Node.getProperty(...); Property.getLength() </entry> + </row> + <row> + <entry> MKCOL </entry> + <entry> Node.addNode(...) </entry> + </row> + <row> + <entry> MOVE </entry> + <entry> Session.move(...) or Workspace.move(...) </entry> + </row> + <row> + <entry> PROPFIND </entry> + <entry> Session.getNode(...); Node.getNode(...); Node.getNodes(...); Node.getProperties() </entry> + </row> + <row> + <entry> PROPPATCH </entry> + <entry> Node.setProperty(...); Node.getProperty(...).remove() </entry> + </row> + <row> + <entry> PUT </entry> + <entry> Node.addNode("node","nt:file"); Node.setProperty("jcr:data", "data") </entry> + </row> + <row> + <entry> CHECKIN </entry> + <entry> Node.checkin() </entry> + </row> + <row> + <entry> CHECKOUT </entry> + <entry> Node.checkout() </entry> + </row> + <row> + <entry> REPORT </entry> + <entry> Node.getVersionHistory(); VersionHistory.getAllVersions(); Version.getProperties() </entry> + </row> + <row> + <entry> RESTORE </entry> + <entry> Node.restore(...) </entry> + </row> + <row> + <entry> UNCHECKOUT </entry> + <entry> Node.restore(...) </entry> + </row> + <row> + <entry> VERSION-CONTROL </entry> + <entry> Node.addMixin("mix:versionable") </entry> + </row> + <row> + <entry> LOCK </entry> + <entry> Node.lock(...) </entry> + </row> + <row> + <entry> UNLOCK </entry> + <entry> Node.unlock() </entry> + </row> + <row> + <entry> ORDERPATCH </entry> + <entry> Node.orderBefore(...) </entry> + </row> + <row> + <entry> SEARCH </entry> + <entry> Workspace.getQueryManager(); QueryManager.createQuery(); Query.execute() </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section id="sect-Reference_Guide-WebDAV-WebDAV_Considerations"> + <title>WebDAV Considerations</title> + <para> + There are some restrictions for WebDAV in different operating systems. + </para> + <formalpara id="form-Reference_Guide-WebDAV_Considerations-Windows_7"> + <title>Windows 7</title> + <para> + When attempting to set up a web folder through <guilabel>Add a Network Location</guilabel> or <guilabel>Map a Network Drive</guilabel> through <guilabel>My Computer</guilabel>, an error message stating <guilabel>The folder you entered does not appear to be valid. Please choose another</guilabel> or <guilabel>Windows cannot access … Check the spelling of the name. Otherwise, there might be …</guilabel> may be encountered. These errors may appear when you are using SSL or non-SSL. + </para> + </formalpara> + <para> + To fix this, do as follows: + </para> + <procedure> + <step> + <para> + Go to Windows Registry Editor. + </para> + </step> + <step> + <para> + Find a key: \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlset\services\WebClient\Parameters\BasicAuthLevel . + </para> + </step> + <step> + <para> + Change the value to 2. + </para> + </step> + </procedure> + <formalpara id="form-Reference_Guide-WebDAV_Considerations-Microsoft_Office_2010"> + <title>Microsoft Office 2010</title> + <para> + If you have: + </para> + </formalpara> + <itemizedlist> + <listitem> + <para> + Microsoft Office 2007/2010 applications installed on a client computer AND... + </para> + </listitem> + <listitem> + <para> + The client computer is connected to a web server configured for Basic authentication VIA... + </para> + </listitem> + <listitem> + <para> + A connection that does not use Secure Sockets Layer (SSL) AND... + </para> + </listitem> + <listitem> + <para> + You try to access an Office file that is stored on the remote server... + </para> + </listitem> + <listitem> + <para> + You might experience the following symptoms when you try to open or to download the file: + </para> + <itemizedlist> + <listitem> + <para> + The Office file does not open or download. + </para> + </listitem> + <listitem> + <para> + You do not receive a Basic authentication password prompt when you try to open or to download the file. + </para> + </listitem> + <listitem> + <para> + You do not receive an error message when you try to open the file. The associated Office application starts. However, the selected file does not open. + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <para> + These outcomes can be circumvented by enabling Basic authentication on the client machine. + </para> + <para> + To enable Basic authentication on the client computer, follow these steps: + </para> + <procedure> + <step> + <para> + Click Start, type <literal>regedit</literal> in the Start Search box, and then press Enter. + </para> + </step> + <step> + <para> + Locate and then click the following registry subkey: + </para> + <para> + <envar>HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Common\Internet</envar> + </para> + </step> + <step> + <para> + On the <guilabel>Edit</guilabel> menu, point to <guilabel>New</guilabel>, and then click <guilabel>DWORD Value</guilabel>. + </para> + </step> + <step> + <para> + Type <literal>BasicAuthLevel</literal>, and then press <keycap>Enter</keycap>. + </para> + </step> + <step> + <para> + Right-click <literal>BasicAuthLevel</literal>, and then click <guilabel>Modify</guilabel>. + </para> + </step> + <step> + <para> + In the Value data box, type <literal>2</literal>, and then click <guilabel>OK</guilabel>. + </para> + </step> + </procedure> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-FTP"> + <title>FTP</title> + <section id="sect-Reference_Guide-FTP-Introduction"> + <title>Introduction</title> + <para> + The JCR-FTP Server operates as an FTP server with access to a content stored in JCR repositories in the form of <literal>nt:file/nt:folder</literal> nodes or their successors. The client of an executed Server can be any FTP client. The FTP server is supported by a standard configuration which can be changed as required. + </para> + </section> + <section id="sect-Reference_Guide-FTP-Configuration_Parameters"> + <title>Configuration Parameters</title> + <variablelist id="vari-Reference_Guide-Configuration_Parameters-Parameters"> + <title>Parameters</title> + <varlistentry> + <term>command-port:</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>command-port</name> + <value>21</value> +</value-param></programlisting> + <para> + The value of the command channel port. The value '<literal>21</literal>' is default. + </para> + <para> + If you have already other FTP server installed in your system, this parameter needs to be changed (to <literal>2121</literal>, for example) to avoid conflicts or if the port is protected. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>data-min-port and data-max-port</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>data-min-port</name> + <value>52000</value> +</value-param></programlisting> + <programlisting language="XML" role="XML"><value-param> + <name>data-max-port</name> + <value>53000</value> +</value-param></programlisting> + <para> + These two parameters indicate the minimum and maximum values of the range of ports, used by the server. The usage of the additional data channel is required by the FTP protocol, which is used to transfer the contents of files and the listing of catalogues. This range of ports should be free from listening by other server-programs. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>system</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>system</name> + + <value>Windows_NT</value> + or + <value>UNIX Type: L8</value> +</value-param></programlisting> + <para> + Types of formats of listing of catalogues which are supported. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>client-side-encoding</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>client-side-encoding</name> + + <value>windows-1251</value> + or + <value>KOI8-R</value> + +</value-param></programlisting> + <para> + This parameter specifies the coding which is used for dialogue with the client. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>def-folder-node-type</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>def-folder-node-type</name> + <value>nt:folder</value> +</value-param></programlisting> + <para> + This parameter specifies the type of a node, when an FTP-folder is created. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>def-file-node-type</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>def-file-node-type</name> + <value>nt:file</value> +</value-param></programlisting> + <para> + This parameter specifies the type of a node, when an FTP-file is created. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>def-file-mime-type</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>def-file-mime-type</name> + <value>application/zip</value> +</value-param></programlisting> + <para> + The mime type of a created file is chosen by using its file extension. In case, a server cannot find the corresponding mime type, this value is used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>cache-folder-name</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>cache-folder-name</name> + <value>../temp/ftp_cache</value> +</value-param></programlisting> + <para> + The Path of the cache folder. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>upload-speed-limit</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>upload-speed-limit</name> + <value>20480</value> +</value-param></programlisting> + <para> + Restriction of the upload speed. It is measured in bytes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>download-speed-limit</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>download-speed-limit</name> + <value>20480</value> +</value-param></programlisting> + <para> + Restriction of the download speed. It is measured in bytes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>timeout</term> + <listitem> + <programlisting language="XML" role="XML"><value-param> + <name>timeout</name> + <value>60</value> +</value-param></programlisting> + <para> + Defines the value of a timeout. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-Use_External_Backup_Tool"> + <title>Use External Backup Tool</title> + <section id="sect-Reference_Guide-Use_External_Backup_Tool-Repository_Suspending"> + <title>Repository Suspending</title> + <para> + To have the repository content consistent with the search index and value storage, the repository should be suspended. This means all working threads are suspended until a resume operation is performed. The index will be flushed. + </para> + <para> + JCR provides ability to suspend repository via JMX. + </para> + <figure> + <title id="repositorysuspendcontroller">Repository Suspend Controller</title> + <mediaobject> + <imageobject> + <imagedata width="444" fileref="images/eXoJCR/repository-suspend-controller.png"/> + </imageobject> + </mediaobject> + </figure> + <para> + To suspend repository you need to invoke the <literal>suspend()</literal> operation. The returned result will be "<emphasis>suspended</emphasis>" if everything passed successfully. + </para> + <figure> + <title id="repository-suspend-controller-suspended.">Repository Suspend Controller Suspended</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/eXoJCR/repository-suspend-controller-suspended.png"/> + </imageobject> + </mediaobject> + </figure> + <para> + An "<emphasis>undefined</emphasis>" result means not all components were successfully suspended. Check the console to review the stack traces. + </para> + </section> + <section id="sect-Reference_Guide-Use_External_Backup_Tool-Backup"> + <title>Backup</title> + <para> + You can backup your content manually or by using third part software. You should back up: + </para> + <itemizedlist> + <listitem> + <para> + Database. + </para> + </listitem> + <listitem> + <para> + Lucene index. + </para> + </listitem> + <listitem> + <para> + Value storage (if configured). + </para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-Use_External_Backup_Tool-Repository_Resuming"> + <title>Repository Resuming</title> + <para> + Once a backup is done you need to invoke the <literal>resume()</literal> operation to switch the repository back to on-line. The returned result will be "<emphasis>on-line</emphasis>". + </para> + <figure> + <title id="repository-suspend-controller-online.">Repository Suspend Controller Online</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/eXoJCR/repository-suspend-controller-online.png"/> + </imageobject> + </mediaobject> + </figure> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-eXo_JCR_statistics"> + <title>eXo JCR statistics</title> + <section id="sect-Reference_Guide-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 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 the method has been called. + </para> + </listitem> + </itemizedlist> + <para> + Those figures are also available globally 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-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> 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> 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> 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> 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> 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> 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> 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> 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> close </entry> + <entry> This is the alias for the method <emphasis>close().</emphasis></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section id="sect-Reference_Guide-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 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="https://repository.jboss.org/nexus/content/groups/public/org/exoplatform/...">https://repository.jboss.org/nexus/content/groups/public/org/exoplatform/...</ulink>. + </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"> + <uri>http://repo2.maven.org/maven2/org/aspectj/aspectjrt</uri> + </ulink>. + </para> + </listitem> + </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">http://repo2.maven.org/maven2/org/aspectj/aspectjweaver</ulink>. + </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-configuration.html">http://www.eclipse.org/aspectj/doc/released/devguide/ltw-configuration.html</ulink>. + </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"><configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"> + + <component> + <type>org.exoplatform.services.jcr.statistics.JCRAPIAspectConfig</type> + <init-params> + <values-param> + <name>targetInterfaces</name> + <value>org.exoplatform.services.jcr.core.ExtendedSession</value> + <value>org.exoplatform.services.jcr.core.ExtendedNode</value> + <value>javax.jcr.Property</value> + </values-param> + </init-params> + </component> +</configuration></programlisting> + <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"><aspectj> + <aspects> + <concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect"> + <pointcut name="JCRAPIPointcut" + expression="(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) && call(public * *(..))" /> + </concrete-aspect> + </aspects> + <weaver options="-XnoInline"> + <include within="org.exoplatform..*" /> + </weaver> +</aspectj></programlisting> + <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_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-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> 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> Times </entry> + <entry> The total amount of times the method has been called. </entry> + </row> + </tbody> + </tgroup> + </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-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 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 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 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> + </tbody> + </tgroup> + </table> + The full name of the related MBean is <literal>xo:service=statistic, view=jcr</literal>. + </para> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-Checking_repository_integrity_and_consistency"> + <title>Checking repository integrity and consistency</title> + <section id="sect-Reference_Guide-Checking_repository_integrity_and_consistency-JMX_based_consistency_tool"> + <title>JMX-based consistency tool</title> + <para> + It is important to check the integrity and consistency of system regularly, especially if there is no, or stale, backups. The JBoss Portal Platform JCR implementation offers an innovative JMX-based complex checking tool. + </para> + <para> + During an inspection, the tool checks every major JCR component, such as persistent data layer and the index. The persistent layer includes JDBC Data Container and Value-Storages if they are configured. + </para> + <para> + The database is verified using the set of complex specialized domain-specific queries. The Value Storage tool checks the existence of, and access to, each file. + </para> + <para> + Access to the check tool is exposed via the JMX interface, with the following operations available: + </para> + <table id="tabl-Reference_Guide-JMX_based_consistency_tool-Available_methods"> + <title>Available methods</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> + <code>checkRepositoryDataConsistency()</code> + </entry> + <entry> Inspect full repository data (db, value storage and search index) </entry> + </row> + <row> + <entry> + <code>checkRepositoryDataBaseConsistency()</code> + </entry> + <entry> Inspect only DB </entry> + </row> + <row> + <entry> + <code>checkRepositoryValueStorageConsistency()</code> + </entry> + <entry> Inspect only ValueStorage </entry> + </row> + <row> + <entry> + <code>checkRepositorySearchIndexConsistency()</code> + </entry> + <entry> Inspect only SearchIndex </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + All inspection activities and corrupted data details are stored in a file in the <filename>app</filename> directory and named as per the following convention: <code> report-<replaceable><repository name></replaceable>-<replaceable>dd-MMM-yy-HH-mm</replaceable>.txt </code>. + </para> + <para> + The path to the file will be returned in result message also at the end of the inspection. + </para> + <note> + <para> + There are three types of inconsistency (Warning, Error and Index) and two of them are critical (Errors and Index): + </para> + <itemizedlist> + <listitem> + <para> + Index faults are marked as "Reindex" and can be fixed by re-indexing the workspace. + </para> + </listitem> + <listitem> + <para> + Errors can only be fixed manually. + </para> + </listitem> + <listitem> + <para> + Warnings can be a normal situation in some cases and usually production system will still remain fully functional. + </para> + </listitem> + </itemizedlist> + </note> + </section> + </chapter>  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/performance-tuning-guide.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr-with-gatein.xml"/> + DOC NOTE: Could possibly be moved to a specific Tuning Guide later --> <chapter xmlns="" id="chap-Reference_Guide-JCR_Performance_Tuning_Guide"> + <title>JCR Performance Tuning Guide</title> + <section id="sect-Reference_Guide-JCR_Performance_Tuning_Guide-Introduction"> + <title>Introduction</title> + <para> + This section will show you various ways of improving JCR performance. + </para> + <para> + It is intended for Administrators and others who want to use the JCR features more efficiently. + </para> + </section> + <section id="sect-Reference_Guide-JCR_Performance_Tuning_Guide-JCR_Performance_and_Scalability"> + <title>JCR Performance and Scalability</title> + <section id="sect-Reference_Guide-JCR_Performance_and_Scalability-Cluster_configuration"> + <title>Cluster configuration</title> + <para> + The table below contains details about the configuration of the cluster used in benchmark testing: + </para> + <table id="tabl-Reference_Guide-Cluster_configuration-EC2_network_1Gbit"> + <title>EC2 network: 1Gbit</title> + <tgroup cols="2"> + <colspec colname="1"/> + <colspec colname="2"/> + <spanspec namest="1" nameend="2" spanname="hspan"/> + <thead> + <row> + <entry> Servers hardware </entry> + <entry> Specification </entry> + </row> + </thead> + <tbody> + <row> + <entry> RAM </entry> + <entry> 7.5 GB </entry> + </row> + <row> + <entry> Processors </entry> + <entry> 4 EC2 Compute Units (2 virtual cores with 2 EC2 Compute Units each) </entry> + </row> + <row> + <entry> Storage </entry> + <entry> 850 GB (2×420 GB plus 10 GB root partition) </entry> + </row> + <row> + <entry> Architecture </entry> + <entry> 64-bit </entry> + </row> + <row> + <entry> I/O Performance </entry> + <entry> High </entry> + </row> + <row> + <entry> API name </entry> + <entry> + <literal>m1.large</literal> + </entry> + </row> + <row> + <entry spanname="hspan"> + <emphasis role="bold">Note:</emphasis> + </entry> + </row> + <row> + <entry spanname="hspan"> NFS and statistics (cacti snmp) server were located on one physical server. </entry> + </row> + <row> + <entry spanname="hspan"> + <emphasis role="bold">JBoss Enterprise Application Platform 6 configuration:</emphasis> + </entry> + </row> + <row> + <entry spanname="hspan"> + <code>JAVA_OPTS: -Dprogram.name=run.sh -server -Xms4g -Xmx4g -XX:MaxPermSize=512m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -XX:+UseParallelGC -Djava.net.preferIPv4Stack=true</code> + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section id="sect-Reference_Guide-JCR_Performance_and_Scalability-JCR_Clustered_Performance"> + <title>JCR Clustered Performance</title> + <para> + Benchmark test using WebDAV (Complex read/write load test (benchmark)) with 20K same file. To obtain per-operation results we have used custom output from the test case threads to CSV file. + </para> + <para> + <citetitle>Read operation</citetitle>: + <simplelist> + <member>Warm-up iterations: 100</member> + <member>Run iterations: 2000</member> + <member>Background writing threads: 25</member> + <member>Reading threads: 225</member> + </simplelist> + + </para> + <figure> + <title id="perf_EC2_result">EC2 Performance Results</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/eXoJCR/perf_EC2_results.jpg"/> + </imageobject> + </mediaobject> + </figure> + <table> + <title/> + <tgroup cols="4"> + <thead> + <row> + <entry> Nodes count </entry> + <entry> tps </entry> + <entry> Responses >2s </entry> + <entry> Responses >4s </entry> + </row> + </thead> + <tbody> + <row> + <entry> 1 </entry> + <entry> 523 </entry> + <entry> 6.87% </entry> + <entry> 1.27% </entry> + </row> + <row> + <entry> 2 </entry> + <entry> 1754 </entry> + <entry> 0.64% </entry> + <entry> 0.08% </entry> + </row> + <row> + <entry> 3 </entry> + <entry> 2388 </entry> + <entry> 0.49% </entry> + <entry> 0.09% </entry> + </row> + <row> + <entry> 4 </entry> + <entry> 2706 </entry> + <entry> 0.46% </entry> + <entry> 0.1% </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + <citetitle>Read operation with more threads</citetitle>: + </para> + <simplelist> + <member>Warm-up iterations: 100</member> + <member>Run iterations: 2000</member> + <member>Background writing threads: 50</member> + <member>Reading threads: 450</member> + </simplelist> + <figure> + <title id="perf_EC2_result2">EC2 Performance Results 2</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/eXoJCR/perf_EC2_results_2.jpg"/> + </imageobject> + </mediaobject> + </figure> + <table> + <title/> + <tgroup cols="4"> + <thead> + <row> + <entry> Nodes count </entry> + <entry> tps </entry> + <entry> Responses >2s </entry> + <entry> Responses >4s </entry> + </row> + </thead> + <tbody> + <row> + <entry> 1 </entry> + <entry> 116 </entry> + <entry> ? </entry> + <entry> ? </entry> + </row> + <row> + <entry> 2 </entry> + <entry> 1558 </entry> + <entry> 6.1% </entry> + <entry> 0.6% </entry> + </row> + <row> + <entry> 3 </entry> + <entry> 2242 </entry> + <entry> 3.1% </entry> + <entry> 0.38% </entry> + </row> + <row> + <entry> 4 </entry> + <entry> 2756 </entry> + <entry> 2.2% </entry> + <entry> 0.41% </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + </section> + <section id="sect-Reference_Guide-JCR_Performance_Tuning_Guide-Performance_Tuning_Guide"> + <title>Performance Tuning Guide</title> + <section id="sect-Reference_Guide-Performance_Tuning_Guide-JBoss_AS_Tuning"> + <title>JBoss Enterprise Application Platform 6 Tuning</title> + <para> + You can use <parameter>maxThreads</parameter> parameter to increase maximum amount of threads that can be launched in AS instance. This can improve performance if you need a high level of concurrency. also you can use <code>-XX:+UseParallelGC</code> java directory to use parallel garbage collector. + </para> + <note> + <title>Note</title> + <para> + Beware of setting <parameter>maxThreads</parameter> too big, this can cause <exceptionname>OutOfMemoryError</exceptionname>. We've got it with <code>maxThreads=1250</code> on such machine: + </para> + <simplelist> + <member>7.5 GB memory</member> + <member>4 EC2 Compute Units (2 virtual cores with 2 EC2 Compute Units each)</member> + <member>850 GB instance storage (2×420 GB plus 10 GB root partition)</member> + <member>64-bit platform</member> + <member>I/O Performance: High</member> + <member>API name: m1.large</member> + <member>java -Xmx 4g</member> + </simplelist> + </note> + </section> + <section id="sect-Reference_Guide-Performance_Tuning_Guide-JCR_Cache_Tuning"> + <title>JCR Cache Tuning</title> + <para> + <citetitle>Cache size</citetitle> + </para> + <para> + JCR-cluster implementation is built using JBoss Cache as distributed, replicated cache. But there is one particularity related to remove action in it. Speed of this operation depends on the actual size of cache. As many nodes are currently in cache as much time is needed to remove one particular node (subtree) from it. + </para> + <para> + <citetitle>Eviction</citetitle> + </para> + <para> + Manipulations with eviction <parameter>wakeUpInterval</parameter> value does not affect on performance. Performance results with values from 500 up to 3000 are approximately equal. + </para> + <para> + <citetitle>Transaction Timeout</citetitle> + </para> + <para> + Using short timeout for long transactions such as Export/Import, removing huge subtree defined timeout may cause <exceptionname>TransactionTimeoutException</exceptionname>. + </para> + </section> + <section id="sect-Reference_Guide-Performance_Tuning_Guide-Clustering"> + <title>Clustering</title> + <para> + For performance it is better to have a load-balancer, DB server and shared NFS on different computers. If in some reasons you see that one node gets more load than others you can decrease this load using load value in load balancer. + </para> + <para> + <citetitle>JGroups configuration</citetitle> + </para> + <para> + It's recommended to use "multiplexer stack" feature present in JGroups. It is set by default in eXo JCR and offers higher performance in cluster, using less network connections also. If there are two or more clusters in your network, please check that they use different ports and different cluster names. + </para> + <para> + <citetitle>Write performance in cluster</citetitle> + </para> + <para> + Exo JCR implementation uses Lucene indexing engine to provide search capabilities. But Lucene brings some limitations for write operations: it can perform indexing only in one thread. That is why write performance in cluster is not higher than in singleton environment. Data is indexed on coordinator node, so increasing write-load on cluster may lead to ReplicationTimeout exception. It occurs because writing threads queue in the indexer and under high load timeout for replication to coordinator will be exceeded. + </para> + <para> + Taking in consideration this fact, it is recommended to exceed <parameter>replTimeout</parameter> value in cache configurations in case of high write-load. + </para> + <para> + <citetitle>Replication timeout</citetitle> + </para> + <para> + Some operations may take too much time. So if you get <exceptionname>ReplicationTimeoutException</exceptionname> try increasing replication timeout: + </para> + <programlisting language="XML" role="XML"> <clustering mode="replication" clusterName="${jbosscache-cluster-name}"> + ... + <sync replTimeout="60000" /> + </clustering> +</programlisting> + <para> + value is set in milliseconds. + </para> + </section> + </section> + </chapter> + <chapter xmlns="" id="chap-Reference_Guide-eXo_JCR_with_GateIn"> + <title>eXo JCR with JBoss Portal Platform</title> + <section xmlns="" id="sect-Reference_Guide-How_to_use_AS_Managed_DataSource_under_JBoss_AS"> + <title>How to use a Managed DataSource under JBoss Enterprise Application Platform 6</title> + <section id="sect-Reference_Guide-How_to_use_AS_Managed_DataSource_under_JBoss_AS-Configurations_Steps"> + <title>Configurations Steps</title> + <section id="sect-Reference_Guide-Configurations_Steps-Declaring_the_datasources_in_the_AS"> + <title>Declaring the Datasources in the AS</title> + <remark>NEEDINFO - FILE PATHS - I know this isn't right. Where do these get deployed again?</remark> + <para> + To declare the datasources using a JBoss application server, deploy a <literal>ds</literal> file (<filename><replaceable>XXX</replaceable>-ds.xml</filename>) into the <emphasis>deploy</emphasis> directory of the appropriate server profile (<filename>/server/<replaceable>PROFILE</replaceable>/deploy</filename>, for example). + </para> + <para> + This file configures all datasources which JBoss Portal Platform will need (there should be four specifically named: <emphasis>jdbcjcr_portal</emphasis>, <emphasis>jdbcjcr_portal-sample</emphasis>, <emphasis>jdbcidm_portal</emphasis> and <emphasis>jdbcidm_sample-portal</emphasis>). + </para> + <para> + For example: + </para> + <programlisting language="XML" role="XML"><?xml version="1.0" encoding="UTF-8"?> +<datasources> + <no-tx-datasource> + <jndi-name>jdbcjcr_portal</jndi-name> + <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcjcr_portal</connection-url> + <driver-class>org.hsqldb.jdbcDriver</driver-class> + <user-name>sa</user-name> + <password></password> + </no-tx-datasource> + + <no-tx-datasource> + <jndi-name>jdbcjcr_sample-portal</jndi-name> + <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcjcr_sample-portal</connection-url> + <driver-class>org.hsqldb.jdbcDriver</driver-class> + <user-name>sa</user-name> + <password></password> + </no-tx-datasource> + + <no-tx-datasource> + <jndi-name>jdbcidm_portal</jndi-name> + <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcidm_portal</connection-url> + <driver-class>org.hsqldb.jdbcDriver</driver-class> + <user-name>sa</user-name> + <password></password> + </no-tx-datasource> + + <no-tx-datasource> + <jndi-name>jdbcidm_sample-portal</jndi-name> + <connection-url>jdbc:hsqldb:${jboss.server.data.dir}/data/jdbcidm_sample-portal</connection-url> + <driver-class>org.hsqldb.jdbcDriver</driver-class> + <user-name>sa</user-name> + <password></password> + </no-tx-datasource> +</datasources></programlisting> + <para> + The properties can be set for datasource can be found here: <ulink url="http://docs.jboss.org/jbossas/docs/Server_Configuration_Guide/4/html/Conn...">Configuring JDBC DataSources - The non transactional DataSource configuration schema</ulink> + </para> + </section> + <section id="sect-Reference_Guide-Configurations_Steps-Do_not_bind_datasources_explicitly"> + <title>Do not bind datasources explicitly</title> + <para> + Do not let the portal explicitly bind datasources. </para> + <remark>NEEDINFO - FILE PATHS - I think some of the values have changed in the referenced file when I look at the new file below. New info required?</remark> + <para>Edit the <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/configuration.properties</filename> and comment out the following rows in the JCR section: + </para> + <programlisting>#gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver +#gatein.jcr.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr_${name} +#gatein.jcr.datasource.username=sa +#gatein.jcr.datasource.password=</programlisting> + <para> + Comment out the following lines in the IDM section: + </para> + <programlisting>#gatein.idm.datasource.driver=org.hsqldb.jdbcDriver +#gatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name} +#gatein.idm.datasource.username=sa +#gatein.idm.datasource.password=</programlisting> + <para> + Open the <filename>jcr-configuration.xml</filename> and <filename>idm-configuration.xml</filename> files and comment out references to the plug-in <literal>InitialContextInitializer</literal>. + </para> + <programlisting language="XML" role="XML"> +</programlisting> + </section> + </section> + </section> + </chapter> </part>

11 years, 7 months

1
0
0 / 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

gatein-commits May 2013