Author: jaredmorgs Date: 2012-07-11 02:00:45 -0400 (Wed, 11 Jul 2012) New Revision: 8781 Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml epp/docs/branches/5.2/Reference_Guide/en-US/Preface.xml epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.ent epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/5.2/Reference_Guide/en-US/extras/PortletBridge_Configuration/default205.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Config_Retrieval.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Profiles.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/System_Properties.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/Introduction.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/JavascriptInterApplicationCommunication.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/XMLResourceBundles.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gtn/managed-datasources-under-jboss-as.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/backup-client.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/exojcr-backup-service.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/use-external-backup-tool.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/cluster-config.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/jdbc-data-container-config.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/multilanguage-support.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/search-configuration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/other/link-producer.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/performance-tuning-guide.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/protocols/webdav.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/query-handler-config.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/repository-check-controller.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/fulltext-search-and-settings.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/jcr-query-usecases.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/searching-repository-content.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/statistics.xml epp/docs/branches/5.2/Reference_Guide/publican.cfg Log: BZ#794433 - Incorporated clarifying comments from Marek about JOSSO, and made procedures in this section easier to follow. Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -9,7 +9,7 @@ <productname>JBoss Enterprise Portal Platform</productname> <productnumber>5.2</productnumber> <edition>5.2.2</edition> - <pubsnumber>2</pubsnumber> + <pubsnumber>9</pubsnumber> <abstract> <para> This Reference Guide is a high-level usage document. It deals with more advanced topics than the Installation and User Guides, adding new content or taking concepts discussed in the earlier documents further. It aims to provide supporting documentation for advanced users of the JBoss Enterprise Portal Platform product. Its primary focus is on advanced use of the product and it assumes an intermediate or advanced knowledge of the technology and terms. Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Preface.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Preface.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Preface.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,16 +1,72 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <preface id="pref-Reference_Guide-Preface"> - <title>Preface</title> - <!-- FOR PUBLICAN --> <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> <!-- FOR JDOCBOOK: --> <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="fallback_content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </xi:fallback> - </xi:include> - <!-- FOR PUBLICAN --> <xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> <!-- FOR JDOCBOOK: --> <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="fallback_content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </xi:fallback> - </xi:include> + <title>Preface</title> + <section id="sect-File_Name_Conventions"> + <title>File Name Conventions</title> + <para>The following naming conventions are used in file paths for readability. Each convention is styled so that it stands out from the rest of text: + + </para> + <variablelist id="vari-Reference_Guide-Introduction-Devices"> + <varlistentry> + <term> + <replaceable>EPP_DIST</replaceable> + </term> + <listitem> + <para>The installation root of the JBoss Enterprise Application Platform instance. This folder contains the main folders that comprise the server such as <filename>/jboss-as</filename>. + </para> + <para>For example, if the JBoss Enterprise Portal Platform instance is deployed into the <filename>/opt/jboss/jboss-epp-&VY;/</filename> directory, the <replaceable>EPP_DIST</replaceable> directory is <filename>/opt/jboss/jboss-epp-&VY;</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>PORTAL_SSO</replaceable> + </term> + <listitem> + <para>The zip file located in the <filename><filename>EPP_DIST</filename>/gatein-sso</filename> directory of the JBoss Enterprise Portal Platform binary package. Used throughout <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>CAS_DIR</replaceable> + </term> + <listitem> + <para>The installation root of the Central Authentication Service (CAS) Single Sign-on Framework. This directory is an arbitrary location chosen when CAS is downloaded and installed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>HTTPD_DIST</replaceable> + </term> + <listitem> + <para>The installation root of the Apache httpd Server. This folder contains the main folders that comprise the server such as <filename>/conf</filename>, <filename>/webapps</filename>, and <filename>/bin</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>PROFILE</replaceable> + </term> + <listitem> + <para>The name of the server profile used as part of testing or production configuration. The server profiles reside in <filename>EPP_DIST/jboss-as/server</filename>.</para> + <para>For example, to use the <literal>default</literal> profile, replace the <replaceable>PROFILE</replaceable> text in the file path to read <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>default</replaceable>/</filename> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> +<!-- FOR PUBLICAN --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Common_Content/Conventions.xml"> + <!-- FOR JDOCBOOK: --> <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="fallback_content/Conventions.xml"/> + </xi:fallback> + </xi:include> +<!-- FOR PUBLICAN --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Common_Content/Feedback.xml"> + <!-- FOR JDOCBOOK: --> <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="fallback_content/Feedback.xml"/> + </xi:fallback> + </xi:include> </preface> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.ent =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.ent 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.ent 2012-07-11 06:00:45 UTC (rev 8781) @@ -17,4 +17,4 @@ <!ENTITY VX "5"> <!ENTITY VY "5.2"> <!ENTITY VZ "5.2.2"> -<!ENTITY WSRP_VERSION "2.1.0-GA"> +<!ENTITY WSRP_VERSION "2.1.6-EPP522-GA"> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -8,6 +8,34 @@ <simpara> <revhistory> <revision> + <revnumber>5.2.2-9</revnumber> + <date>Wed Jul 11 2012</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>BZ#794433 - Incorporated clarifying comments from Marek about JOSSO, and made procedures in this section easier to follow.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.2-6</revnumber> + <date>Tue Jul 10 2012</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>BZ#812412 - Extensive peer review comments incorporated. Book-wide spell-check run.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>5.2.2-2</revnumber> <date>Thu Jul 5 2012</date> <author> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/extras/PortletBridge_Configuration/default205.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/extras/PortletBridge_Configuration/default205.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/extras/PortletBridge_Configuration/default205.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,3 +1,3 @@ -<script src="/faces/rfRes/org/ajax4jsf/framework.pack.js" type="text/javascript"></script> -<script src="/faces/rfRes/org/richfaces/ui.pack.js" type="text/javascript"></script> -<link rel="stylesheet" type="text/css" href="/faces/rfRes/org/richfaces/skin.xcss"/> +<script src="/richFacesPortlet/faces/rfRes/org/ajax4jsf/framework.pack.js" type="text/javascript"></script> +<script src="/richFacesPortlet/faces/rfRes/org/richfaces/ui.pack.js" type="text/javascript"></script> +<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss"/> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Config_Retrieval.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Config_Retrieval.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Config_Retrieval.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -14,17 +14,17 @@ <procedure> <step> <para> - Services default <envar>RootContainer</envar> configurations from JAR files <filename><replaceable>EPP_HOME</replaceable>/conf/gatein/configuration.xml</filename>. + Services default <envar>RootContainer</envar> configurations from JAR files <filename><replaceable>EPP_DIST/jboss-as/</replaceable>/conf/gatein/configuration.xml</filename>. </para> </step> <step> <para> - External <envar>RootContainer</envar> configuration can be found at <filename><replaceable>EPP_HOME</replaceable>/conf/gatein/configuration.xml</filename>. + External <envar>RootContainer</envar> configuration can be found at <filename><replaceable>EPP_DIST/jboss-as/</replaceable>/conf/gatein/configuration.xml</filename>. </para> </step> <step> <para> - Services default <envar>PortalContainer</envar> configurations from JAR files <filename>/conf/portal/configuration.xml</filename>. + Services default <envar>PortalContainer</envar> configurations from JAR files <filename><replaceable>EPP_DIST</replaceable>/jboss-as/conf/portal/configuration.xml</filename>. </para> </step> <step> @@ -34,7 +34,7 @@ </step> <step> <para> - External configuration for services of named portal can be found at <filename><replaceable>EPP_HOME</replaceable>/conf/gatein/configuration.xml</filename>. + External configuration for services of named portal can be found at <filename><replaceable>EPP_DIST</replaceable>/jboss-as/conf/gatein/configuration.xml</filename>. </para> </step> </procedure> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -21,7 +21,7 @@ All <filename>configuration.xml</filename> files located at <filename>conf/portal/configuration.xml</filename> in the classpath will have their services configured at the <literal>PortalContainer</literal> scope. </para> <para> - Additionally, <emphasis role="bold">portal extensions</emphasis> can use configuration information stored in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/configuration.xml</filename>, and will also have their services configured in the <literal>PortalContainer</literal> scope. + Additionally, <emphasis role="bold">portal extensions</emphasis> can use configuration information stored in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/configuration.xml</filename>, and will also have their services configured in the <literal>PortalContainer</literal> scope. </para> <para> When eXo kernel reads a configuration, it loads the file from the kernel jar using the classloader and does not use an internet connection to resolve the file. @@ -36,13 +36,13 @@ <section id="sect-Reference_Guide-Configuration_syntax-Components"> <title>Components</title> <para> - A service component is defined in <filename>configuration.xml</filename> by using a <emphasis role="bold">&lt;component&gt;</emphasis> element. + A service component is defined in <filename>configuration.xml</filename> by using a &lt;component&gt; element. </para> <para> - Only one piece of information is required when defining a service; the service implementation class. This is specified using <literal>&lt;type&gt;</literal> + Only one piece of information is required when defining a service; the service implementation class. This is specified using &lt;type&gt; </para> <para> - Every component has a <literal>&lt;key&gt;</literal> that identifies it. If not explicitly set, a key defaults to the value of <literal>&lt;type&gt;</literal>. If a key can be loaded as a class, a class object is used as a key, otherwise a string is used. + Every component has a &lt;key&gt; that identifies it. If not explicitly set, a key defaults to the value of &lt;type&gt;. If a key can be loaded as a class, a class object is used as a key, otherwise a string is used. </para> <para> The usual approach is to specify an interface as a key. @@ -188,7 +188,7 @@ </listitem> <listitem> <para> - Web application configurations from the portal.war file - or the <emphasis>portal</emphasis> weppapp (folder <emphasis>/WEB-INF/conf/configuration.xml</emphasis>) + Web application configurations from the portal.war file - or the <emphasis>portal</emphasis> web app (folder <emphasis>/WEB-INF/conf/configuration.xml</emphasis>) </para> </listitem> <listitem> @@ -395,25 +395,24 @@ </section> </section> <section id="sect-Reference_Guide-Configuration_syntax-InitParams_configuration_element"> - <title>InitParams configuration element</title> - <para> - <parameter>InitParams</parameter> is a configuration element that is essentially a map of key-value pairs, where <emphasis role="bold">key</emphasis> is always a <literal>String</literal>, and <emphasis role="bold">value</emphasis> can be any type that can be described using the kernel XML configuration. + <title>&lt;init-params&gt; configuration element</title> + <para>&lt;init-params&gt; is a configuration element that is essentially a map of key-value pairs, where <emphasis role="bold">key</emphasis> is always a <literal>String</literal>, and <emphasis role="bold">value</emphasis> can be any type that can be described using the kernel XML configuration. </para> <para> - Service components that form the JBoss Enterprise Portal Platform infrastructure use <parameter>InitParams</parameter> elements to configure themselves. A component can have one instance of <parameter>InitParams</parameter> injected at most. + Service components that form the JBoss Enterprise Portal Platform infrastructure use &lt;init-params&gt; elements to configure themselves. A component can have one instance of &lt;init-params&gt; injected at most. </para> <para> - If the service component&apos;s constructor takes <parameter>InitParams</parameter> as any of the parameters it will automatically be injected at component instantiation time. + If the service component&apos;s constructor takes &lt;init-params&gt; as any of the parameters it will automatically be injected at component instantiation time. </para> <para> - The XML configuration for a service component that expects an <parameter>InitParams</parameter> element must have an <parameter>&lt;init-params&gt;</parameter> element present, however this element can be left empty. + The XML configuration for a service component that expects an &lt;init-params&gt; element must have an &lt;init-params&gt; element present, however this element can be left empty. </para> <para> - Below is an example of how the kernel XML configuration syntax looks when creating <parameter>InitParams</parameter> instances: + Below is an example of how the kernel XML configuration syntax looks when creating &lt;init-params&gt; instances: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default4.xml" parse="text"/></programlisting> <para> - An <parameter>InitParams</parameter> element description begins with an <parameter>&lt;init-params&gt;</parameter> element. + An &lt;init-params&gt; element description begins with an &lt;init-params&gt; element. </para> <para> It can have zero or more children elements, each of which is one of the following: @@ -421,61 +420,72 @@ <itemizedlist> <listitem> <para> - <parameter>&lt;value-param&gt;</parameter> + &lt;value-param&gt; </para> </listitem> <listitem> <para> - <parameter>&lt;values-param&gt;</parameter> + &lt;values-param&gt; </para> </listitem> <listitem> <para> - <parameter>&lt;properties-param&gt;</parameter> + &lt;properties-param&gt; </para> </listitem> - </itemizedlist> - <para> - or - </para> - <itemizedlist> <listitem> <para> - <parameter>&lt;object-param&gt;</parameter> + &lt;object-param&gt; </para> </listitem> </itemizedlist> <para> - Each of these child elements takes a <parameter>&lt;name&gt;</parameter> that serves as a map entry key, and an optional <parameter>&lt;description&gt;</parameter>. It also takes a type-specific <emphasis role="bold">value</emphasis> specification. + Each of these child elements takes a &lt;name&gt; that serves as a map entry key, and an optional &lt;description&gt;. It also takes a type-specific <emphasis role="bold">value</emphasis> specification. </para> <para> - The value specification for the <parameter>&lt;properties-param&gt;</parameter> defines one or more <parameter>&lt;property&gt;</parameter> elements, each of which specifies two strings; a property name and a property value. This is evident in the two previous examples. + The value specification for the &lt;properties-param&gt; defines one or more &lt;property&gt; elements, each of which specifies two strings; a property name and a property value. This is evident in the two previous examples. </para> <para> - Each <parameter>&lt;properties-params&gt;</parameter> defines one <literal>java.util.Properties</literal> instance. + Each &lt;properties-params&gt; defines one <literal>java.util.Properties</literal> instance. </para> + <example> + <title>&lt;properties-param&gt; Hibernate Example</title> + <programlisting language="XML" role="XML"> &lt;component&gt; + &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;hibernate.properties&lt;/name&gt; + &lt;description&gt;Default Hibernate Service&lt;/description&gt; + &lt;property name=&quot;hibernate.show_sql&quot; value=&quot;false&quot;/&gt; + &lt;property name=&quot;hibernate.cglib.use_reflection_optimizer&quot; value=&quot;true&quot;/&gt; + &lt;property name=&quot;hibernate.connection.url&quot; value=&quot;jdbc:hsqldb:file:../temp/data/exodb&quot;/&gt; + &lt;property name=&quot;hibernate.connection.driver_class&quot; value=&quot;org.hsqldb.jdbcDriver&quot;/&gt; +... + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component&gt;</programlisting> + <para> + In the org.exoplatform.services.database.impl.HibernateServiceImpl you will find that the name &quot;hibernate.properties&quot; of the properties-param is used to access the properties. + </para> + <programlisting language="Java" role="Java">package org.exoplatform.services.database.impl; + +public class HibernateServiceImpl implements HibernateService, ComponentRequestLifecycle { + public HibernateServiceImpl(InitParams initParams, CacheService cacheService) { + PropertiesParam param = initParams.getPropertiesParam(&quot;hibernate.properties&quot;); +... +}</programlisting> + </example> <para> - The value specification for <parameter>&lt;value-param&gt;</parameter> elements is a <parameter>&lt;value&gt;</parameter> element which defines a <literal>String</literal> instance. + The value specification for &lt;value-param&gt; elements is a &lt;value&gt; element which defines a <literal>String</literal> instance. </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default5.xml" parse="text"/></programlisting> <para> - The value specification for <parameter>&lt;values-param&gt;</parameter> requires one or more <parameter>&lt;value&gt;</parameter> elements. Each <parameter>&lt;value&gt;</parameter> represents one <literal>String</literal> instance. All <literal>String</literal> values are then collected into a <literal>java.util.List</literal> instance. + The value specification for &lt;values-param&gt; requires one or more &lt;value&gt; elements. Each &lt;value&gt; represents one <literal>String</literal> instance. All <literal>String</literal> values are then collected into a <literal>java.util.List</literal> instance. </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default6.xml" parse="text"/></programlisting> - <para> - For <parameter>&lt;object-param&gt;</parameter> entries, the value specification consists of an <parameter>&lt;object&gt;</parameter> element which is used for plain Java style object specification (specifying an implementation <emphasis>class - <parameter>&lt;type&gt;</parameter></emphasis>, and <emphasis>property values - <parameter>&lt;field&gt;</parameter></emphasis>). - </para> - <para> - The following section has an example of specifying a field of with a <literal>Collection</literal> type. - </para> - <para> - The <parameter>InitParams</parameter> structure (the names and types of entries) is specific for each service, as it is the code inside a service components&apos; class that defines which entry names to look up and what types it expects to find. - </para> - <section id="sect-Reference_Guide-InitParams_configuration_element-Value_Param"> - <title>Value-Param</title> - <para> - There is an value-param example: - </para> + <example> + <title>&lt;value-param&gt; Example</title> <programlisting language="XML" role="XML"> &lt;component&gt; &lt;key&gt;org.exoplatform.portal.config.UserACL&lt;/key&gt; &lt;type&gt;org.exoplatform.portal.config.UserACL&lt;/type&gt; @@ -489,7 +499,7 @@ ... &lt;/component&gt;</programlisting> <para> - The UserACL class accesses to the <emphasis role="bold">value-param</emphasis> in its constructor. + The UserACL class accesses to the &lt;value-param&gt; in its constructor. </para> <programlisting language="Java" role="Java">package org.exoplatform.portal.config; public class UserACL { @@ -499,46 +509,15 @@ ValueParam accessControlWorkspaceParam = params.getValueParam(&quot;access.control.workspace&quot;); if(accessControlWorkspaceParam != null) md.setAccessControlWorkspace(accessControlWorkspaceParam.getValue()); ...</programlisting> - </section> - <section id="sect-Reference_Guide-InitParams_configuration_element-Properties_Param"> - <title>Properties-Param</title> + </example> + <para> + For &lt;object-param&gt; entries, the value specification consists of an &lt;object&gt; element which is used for plain Java style object specification (specifying an implementation <emphasis>class - &lt;type&gt;</emphasis>, and <emphasis>property values - &lt;field&gt;</emphasis>). +</para> + <example> + <title>&lt;object-param&gt; and LDAP Example</title> <para> - Properties are name-value pairs. Both the name and the value are Java Strings. + Let&apos;s have a look at the configuration of the LDAPService. It is not important to understand LDAP, we only discuss the parameters as they relate to &lt;object-param&gt;. </para> - <para> - Here you see the hibernate configuration example: - </para> - <programlisting language="XML" role="XML"> &lt;component&gt; - &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;properties-param&gt; - &lt;name&gt;hibernate.properties&lt;/name&gt; - &lt;description&gt;Default Hibernate Service&lt;/description&gt; - &lt;property name=&quot;hibernate.show_sql&quot; value=&quot;false&quot;/&gt; - &lt;property name=&quot;hibernate.cglib.use_reflection_optimizer&quot; value=&quot;true&quot;/&gt; - &lt;property name=&quot;hibernate.connection.url&quot; value=&quot;jdbc:hsqldb:file:../temp/data/exodb&quot;/&gt; - &lt;property name=&quot;hibernate.connection.driver_class&quot; value=&quot;org.hsqldb.jdbcDriver&quot;/&gt; -... - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component&gt;</programlisting> - <para> - In the org.exoplatform.services.database.impl.HibernateServiceImpl you will find that the name &quot;hibernate.properties&quot; of the properties-param is used to access the properties. - </para> - <programlisting language="Java" role="Java">package org.exoplatform.services.database.impl; - -public class HibernateServiceImpl implements HibernateService, ComponentRequestLifecycle { - public HibernateServiceImpl(InitParams initParams, CacheService cacheService) { - PropertiesParam param = initParams.getPropertiesParam(&quot;hibernate.properties&quot;); -... -}</programlisting> - </section> - <section id="sect-Reference_Guide-InitParams_configuration_element-Object_Param"> - <title>Object-Param</title> - <para> - Let&apos;s have a look at the configuration of the LDAPService. It&apos;s not important to know LDAP, we only discuss the parameters. - </para> <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;org.exoplatform.services.LDAP.LDAPService&lt;/key&gt; &lt;type&gt;org.exoplatform.services.LDAP.impl.LDAPServiceImpl&lt;/type&gt; @@ -560,7 +539,7 @@ &lt;/init-params&gt; &lt;/component&gt;</programlisting> <para> - You see here an <emphasis role="bold">object-param</emphasis> is being used to pass the parameters inside an object (actually a java bean). It consists of a <emphasis role="bold">name</emphasis>, a <emphasis role="bold">description</emphasis> and exactly one <emphasis role="bold">object</emphasis>. The object defines the <emphasis role="bold">type</emphasis> and a number of <emphasis role="bold">fields</emphasis>. + You see here an &lt;object-param&gt; element is being used to pass the parameters inside an object (actually a java bean). It consists of a <emphasis role="bold">name</emphasis>, a <emphasis role="bold">description</emphasis> and exactly one <emphasis role="bold">object</emphasis>. The object defines the <emphasis role="bold">type</emphasis> and a number of <emphasis role="bold">fields</emphasis>. </para> <para> Here you see how the service accesses the object: @@ -602,7 +581,13 @@ <para> Have a look on this type test xml file: <ulink url="https://anonsvn.jboss.org/repos/exo-jcr/kernel/trunk/exo.kernel...;. </para> - </section> + </example> + <para> + The following section has an example of specifying a field of with a <literal>Collection</literal> type. + </para> + <para> + The &lt;init-params&gt; structure (the names and types of entries) is specific for each service, as it is the code inside a service components&apos; class that defines which entry names to look up and what types it expects to find. + </para> <section id="sect-Reference_Guide-InitParams_configuration_element-Collection"> <title>Collection</title> <para> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Profiles.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Profiles.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Profiles.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -55,12 +55,12 @@ <section id="sect-Reference_Guide-Profiles_configuration-Profiles_capable_configuration_elements"> <title>Profiles capable configuration elements</title> <para> - A configuration element is <emphasis>profiles</emphasis> capable when it carries a profiles element. + A &lt;configuration&gt; element is <emphasis>profiles</emphasis>-capable when it carries a &lt;profiles&gt; element. </para> <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Component_element"> - <title>Component element</title> + <title>&lt;component&gt; element</title> <para> - The component element declares a component when activated. It will shadow any element with the same key declared before in the same configuration file: + The &lt;component&gt; element declares a component when activated. It will shadow any element with the same key declared before in the same configuration file: </para> <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;Component&lt;/key&gt; @@ -73,9 +73,9 @@ &lt;/component&gt;</programlisting> </section> <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Component_plugin_element"> - <title>Component plug-in element</title> + <title>&lt;component-plugin&gt; element</title> <para> - The component-plugin element is used to dynamically extend the configuration of a given component. Thanks to the profiles the component-plugins could be enabled or disabled: + The &lt;component-plugin&gt; element is used to dynamically extend the configuration of a given component. Thanks to the profiles the &lt;component-plugin&gt; elements can be enabled or disabled: </para> <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;target-component&gt;Component&lt;/target-component&gt; @@ -93,18 +93,18 @@ &lt;/external-component-plugins&gt;</programlisting> </section> <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Import_element"> - <title>Import element</title> + <title>&lt;import&gt; element</title> <para> - The import element imports a referenced configuration file when activated: + The &lt;import&gt; element imports a referenced configuration file when activated: </para> <programlisting language="XML" role="XML">&lt;import&gt;empty&lt;/import&gt; &lt;import profiles=&quot;foo&quot;&gt;foo&lt;/import&gt; &lt;import profiles=&quot;bar&quot;&gt;bar&lt;/import&gt;</programlisting> </section> <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Init_param_element"> - <title>Init param element</title> + <title>&lt;init-params&gt; element</title> <para> - The init param element configures the parameter argument of the construction of a component service: + The &lt;init-params&gt; element configures the parameter argument of the construction of a component service: </para> <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;Component&lt;/key&gt; @@ -126,9 +126,9 @@ &lt;/component&gt;</programlisting> </section> <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Value_collection_element"> - <title>Value collection element</title> + <title>&lt;value-collection&gt; element</title> <para> - The value collection element configures one of the value of collection data: + The &lt;value-collection&gt; element configures one of the value of collection data: </para> <programlisting language="XML" role="XML">&lt;object type=&quot;org.exoplatform.container.configuration.ConfigParam&quot;&gt; &lt;field name=&quot;role&quot;&gt; @@ -141,9 +141,9 @@ &lt;/object&gt;</programlisting> </section> <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Field_configuration_element"> - <title>Field configuration element</title> + <title>&lt;field-configuration&gt; element</title> <para> - The field configuration element configures the field of an object: + The &lt;field-configuration&gt; element configures the field of an object: </para> <programlisting language="XML" role="XML">&lt;object-param&gt; &lt;name&gt;test.configuration&lt;/name&gt; Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/System_Properties.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/System_Properties.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/System_Properties.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,42 +1,40 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-System_property_configuration"> - <title>System property configuration</title> - <para> - A new property configurator service has been developed for taking care of configuring system properties from the inline kernel configuration or from specified property files. - </para> - <para> - The services is scoped at the root container level because it is used by all the services in the different portal containers in the application runtime. - </para> - <section id="sect-Reference_Guide-System_property_configuration-Properties_init_param"> - <title>Properties init param</title> - <para> - The properties init param takes a property declared to configure various properties. - </para> - -<programlisting language="XML" role="XML">&lt;component&gt; + <title>System property configuration</title> + <para> + A new property configurator service has been developed for taking care of configuring system properties from the inline kernel configuration or from specified property files. + </para> + <para> + The services is scoped at the root container level because it is used by all the services in the different portal containers in the application runtime. + </para> + <section id="sect-Reference_Guide-System_property_configuration-Properties_init_param"> + <title>Properties &lt;init-param&gt;</title> + <para> + The properties init param takes a property declared to configure various properties. + </para> + <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;PropertyManagerConfigurator&lt;/key&gt; &lt;type&gt;org.exoplatform.container.PropertyConfigurator&lt;/type&gt; &lt;init-params&gt; &lt;properties-param&gt; &lt;name&gt;properties&lt;/name&gt; - &lt;property name="foo" value="bar"/&gt; + &lt;property name=&quot;foo&quot; value=&quot;bar&quot;/&gt; &lt;/properties-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-System_property_configuration-Properties_URL_init_param"> - <title>Properties URL init param</title> - <para> - The properties URL init param allow to load an external file by specifying its URL. Both property and XML format are supported, see the javadoc of the <emphasis><envar>java.util.Properties</envar></emphasis> class for more information. When a property file is loaded the various property declarations are loaded in the order in which the properties are declared sequentially in the file. - </para> - -<programlisting language="XML" role="XML">&lt;component&gt; + </section> + <section id="sect-Reference_Guide-System_property_configuration-Properties_URL_init_param"> + <title>Properties URL &lt;init-param&gt;</title> + <para> + The properties URL init param allow to load an external file by specifying its URL. Both property and XML format are supported, see the javadoc of the <emphasis> + <envar>java.util.Properties</envar> + </emphasis> class for more information. When a property file is loaded the various property declarations are loaded in the order in which the properties are declared sequentially in the file. + </para> + <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;PropertyManagerConfigurator&lt;/key&gt; &lt;type&gt;org.exoplatform.container.PropertyConfigurator&lt;/type&gt; &lt;init-params&gt; @@ -46,33 +44,24 @@ &lt;/value-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> - <para> - In the properties file corresponding to the external properties, you can reuse variables before defining to create a new variable. In this case, the prefix "<emphasis>portal.container.</emphasis>" is not needed, see an example below: + <para> + In the properties file corresponding to the external properties, you can reuse variables before defining to create a new variable. In this case, the prefix &quot;<emphasis>portal.container.</emphasis>&quot; is not needed, see an example below: <programlisting>my-var1=value 1 my-var2=value 2 complex-value=${my-var1}-${my-var2}</programlisting> - </para> - - </section> - - <section id="sect-Reference_Guide-System_property_configuration-System_Property_configuration_of_the_properties_URL"> - <title>System Property configuration of the properties URL</title> - <para> - It is possible to replace the properties URL init param by a system property that overwrites it. The name of that property is <emphasis>exo.properties.url</emphasis>. - </para> - - </section> - - <section id="sect-Reference_Guide-System_property_configuration-Variable_Syntaxes"> - <title>Variable Syntaxes</title> - <para> - All the variables that we described in the previous sections can be defined thanks to 2 possible syntaxes which are <emphasis>${variable-name}</emphasis> or <emphasis>${variable-name:default-value}</emphasis>. The first syntax doesn't define any default value so if the variable has not be set the value will be <emphasis>${variable-name}</emphasis> to indicate that it could not be resolved. The second syntax allows you to define the default value after the semi colon so if the variable has not be set the value will be the given default value. - </para> - - </section> - - + </para> + </section> + <section id="sect-Reference_Guide-System_property_configuration-System_Property_configuration_of_the_properties_URL"> + <title>System Property configuration of the properties URL</title> + <para> + It is possible to replace the properties URL init param by a system property that overwrites it. The name of that property is <emphasis>exo.properties.url</emphasis>. + </para> + </section> + <section id="sect-Reference_Guide-System_property_configuration-Variable_Syntaxes"> + <title>Variable Syntaxes</title> + <para> + All the variables that we described in the previous sections can be defined thanks to 2 possible syntaxes which are <emphasis>${variable-name}</emphasis> or <emphasis>${variable-name:default-value}</emphasis>. The first syntax doesn&apos;t define any default value so if the variable has not be set the value will be <emphasis>${variable-name}</emphasis> to indicate that it could not be resolved. The second syntax allows you to define the default value after the semi colon so if the variable has not be set the value will be the given default value. + </para> + </section> </section> - - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -44,7 +44,7 @@ Authentication workflow consists of HTTP requests and redirects which include handshakes. Source code related to authentication is partially included in the WCI module, as the authentication process differs on <ulink url="http://www.jcp.org/en/jsr/detail?id=154" type="http">Servlet 2.5</ulink> containers and <ulink url="http://www.jcp.org/en/jsr/detail?id=315" type="http">Servlet 3.0</ulink> containers. </para> <para> - First you can see in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> that authentication is triggered by accessing a secured URL: + First you can see in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> that authentication is triggered by accessing a secured URL: </para> <programlisting language="XML" role="XML"> <![CDATA[ @@ -87,7 +87,7 @@ ]]> </programlisting> <para> - <literal>InitiateLoginServlet</literal> simply redirects user to login page placed in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename>. + <literal>InitiateLoginServlet</literal> simply redirects user to login page placed in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename>. <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/AuthenticationAndIdentity/Overview/loginScreen.png" format="PNG"/> @@ -98,7 +98,7 @@ </mediaobject> </para> <para> - Changes to the appearance of this login page can be made in this JSP file. You can also change image or CSS placed in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/login/skin</filename> . + Changes to the appearance of this login page can be made in this JSP file. You can also change image or CSS placed in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/login/skin</filename> . </para> <para> After a user submits the login form, they are redirected to the login URL; <ulink url="http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/classic" type="http">http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/private/classic</ulink>. @@ -429,7 +429,7 @@ </itemizedlist> </section> <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-reauthentication"> - <title>Reauthentication</title> + <title>Re-authentication</title> <itemizedlist> <listitem> <para> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -33,7 +33,7 @@ <section id="sect-Reference_Guide-Authentication_Token_Configuration-Configuring_Token_Services"> <title>Configuring Token Services</title> <para> - Token services configuration includes specifying the token validity period. The token service is configured as a portal component using the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/common/autologin-configuration.xml</filename> file. + Token services configuration includes specifying the token validity period. The token service is configured as a portal component using the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/common/autologin-configuration.xml</filename> file. </para> <para> In the XML example below, <emphasis>CookieTokenService</emphasis> is a subclass of <emphasis role="bold">AbstractTokenService</emphasis> so it has a property which specifies the validity period of the token. Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -9,11 +9,11 @@ <para>The plug-in is particularly useful when using the Site Publisher add-on, and directly adding users or groups to a LDAP server through LDIF files, or into a database using SQL. </para> <section> <title>Enable Initializer</title> - <para>The initializer is disabled by default. To activate it, uncomment the block containing the path to the <filename>initializer-configuration.xml</filename> file in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/configuration.xml</filename>. + <para>The initializer is disabled by default. To activate it, uncomment the block containing the path to the <filename>initializer-configuration.xml</filename> file in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/configuration.xml</filename>. </para> <programlisting language="XML">&lt;!-- Uncomment for enable initializer (OrganizationListenersInitializerService and related stuff) --&gt; &lt;import&gt;war:/conf/organization/initializer-configuration.xml&lt;/import&gt;</programlisting> - <para>All configuration for the initializer occurs in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename>, which is the main configuration file + <para>All configuration for the initializer occurs in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename>, which is the main configuration file for this initializer. More details about configuration options, along with alternatives to XML directive configuration, are described in subsequent sections.</para> </section> <section> @@ -84,7 +84,7 @@ </section> <section id="Triggering_Operations"> <title>Using configuration directives</title> - <para>There are a number of ways of controlling operations associated with CoreOrganizationInitializer. All parameters are configured in &lt;value-param&gt; directive blocks in the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename> file.</para> + <para>There are a number of ways of controlling operations associated with CoreOrganizationInitializer. All parameters are configured in &lt;value-param&gt; directive blocks in the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename> file.</para> <example> <title>&lt;value-param&gt; block for initializer directives</title> <programlisting language="XML">&lt;value-param&gt; @@ -96,7 +96,7 @@ <title>Disable launchAll at Startup</title> <para>For large implementations with many users and groups, consider disabling <parameter>launchAll</parameter> functionality during start-up for each portal container. Disabling this operation during start-up will result in a performance improvement.</para> <step> - <para>Open <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename></para> + <para>Open <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename></para> </step> <step> <para>Locate the <parameter>executeAllListenersDuringBoot</parameter> &lt;value-param&gt; parameter.</para> @@ -109,7 +109,7 @@ <title>Disable launchAll Job Scheduler</title> <para>A job scheduler is configured to run by default, and executes <parameter>launchAll</parameter> periodically. For large implementations with many users and groups, consider disabling the Job scheduler <parameter>launchAll</parameter> functionality for each portal container. Disabling this operation may result in a performance improvement.</para> <step> - <para>Open <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename></para> + <para>Open <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename></para> </step> <step> <para>Search for &quot;scheduler&quot; in the file.</para> @@ -122,7 +122,7 @@ <title>Alter the way JCR objects are created on-demand, at user login. </title> <para>When a user logs into the portal, the <parameter>treatUser</parameter> operation runs on-demand to create the required JCR objects. This operation (activated by default) improves overall performance of the portal, because user objects are only created when needed. To disable the operation (not recommended), follow the guidelines below.</para> <step> - <para>Open <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename></para> + <para>Open <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename></para> </step> <step> <para>Locate the <parameter>ExtensibleFilter</parameter> directive block.</para> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -8,7 +8,7 @@ <note> <title>Notational Device</title> <para> - For ease of readability the following section uses the notational device <replaceable>ID_HOME</replaceable> to represent the file path <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/organization/</filename>, as this directory is the root of all JBoss Enterprise Portal Platform&apos;s identity-related configuration. + For ease of readability the following section uses the notational device <replaceable>ID_HOME</replaceable> to represent the file path <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/organization/</filename>, as this directory is the root of all JBoss Enterprise Portal Platform&apos;s identity-related configuration. </para> </note> <para> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -17,7 +17,7 @@ <orderedlist> <listitem> <para> - The <emphasis>Remember Me</emphasis> feature can be disabled by removing the corresponding checkbox in: <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename> and <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</filename>. + The <emphasis>Remember Me</emphasis> feature can be disabled by removing the corresponding checkbox in: <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename> and <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</filename>. </para> </listitem> <listitem> @@ -45,7 +45,7 @@ </step> <step> <para> - Deploy the <filename>codec-example.jar</filename> into your <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib/</filename> directory. + Deploy the <filename>codec-example.jar</filename> into your <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib/</filename> directory. </para> </step> <step> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -8,7 +8,7 @@ <section id="sect-Reference_Guide-Predefined_User_Configuration-Overview"> <title>Overview</title> <para> - The initial Organization configuration should be specified by editing the content of <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</filename>. This file uses the portal XML configuration schema. It lists several configuration plug-ins. + The initial Organization configuration should be specified by editing the content of <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</filename>. This file uses the portal XML configuration schema. It lists several configuration plug-ins. </para> </section> <section id="sect-Reference_Guide-Predefined_User_Configuration-Plugin_for_adding_users_groups_and_membership_types"> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -6,7 +6,7 @@ <section id="sect-Reference_Guide-SSO_Single_Sign_On"> <title>SSO - Single Sign On</title> <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Overview"> - <title>Overview</title> + <title>Overview and Configuration Assumptions</title> <para> JBoss Enterprise Portal Platform provides an implementation of Single Sign On (<literal>SSO</literal>) as an integration and aggregation platform. </para> @@ -48,7 +48,7 @@ </para> </note> <para> - All the packages required for SSO setup can be found in a zip file located in the <filename>jboss-epp-<replaceable>VERSION</replaceable>/gatein-sso</filename> directory of the JBoss Enterprise Portal Platform binary package. + All the packages required for SSO setup can be found in a zip file located in the <filename><filename>EPP_DIST</filename>/gatein-sso</filename> directory of the JBoss Enterprise Portal Platform binary package. </para> <para> In the following scenarios this directory will be referred to as <replaceable>PORTAL_SSO</replaceable>. @@ -62,6 +62,10 @@ Remove <filename>JBOSS_HOME/server/PROFILE/deploy/gatein-sample-extension.ear</filename> and <filename>JBOSS_HOME/server/PROFILE/deploy/gatein-sample-portal.ear</filename> which are packaged by default with JBoss Enterprise Portal Platform. </para> --> </warning> </section> + <section> + <title>SSO Conf</title> + <para/> + </section> <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"> <title>Enabling SSO using JBoss SSO Valve</title> <!-- Source Metadata @@ -104,7 +108,7 @@ <title>SSO Integration</title> <step> <para> - Open the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/jbossweb.sar/server.xml</filename> file and uncomment one of the two <parameter>Valve</parameter> entries: + Open the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/jbossweb.sar/server.xml</filename> file and uncomment one of the two <parameter>Valve</parameter> entries: </para> <itemizedlist> <listitem> @@ -167,7 +171,7 @@ </step> <step> <para> - Open the <filename><replaceable>EPP_HOME</replaceable>/server/all/<replaceable>PROFILE</replaceable>/jbossweb.sar/server.xml</filename> file. + Open the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/all/<replaceable>PROFILE</replaceable>/jbossweb.sar/server.xml</filename> file. </para> </step> <step> @@ -236,7 +240,7 @@ <title/> <step> <para> - Open the <filename><replaceable>EPP_HOME</replaceable>/server/node1/deploy/jmx-console.war/WEB-INF/web.xml</filename> file and edit it as follows: + Open the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/node1/deploy/jmx-console.war/WEB-INF/web.xml</filename> file and edit it as follows: </para> <substeps> <step> @@ -302,7 +306,7 @@ <title>Redirect to Use SSO Valve Authentication</title> <step> <para> - Open the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file and edit the line: + Open the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file and edit the line: </para> <programlisting language="Java" role="java">&lt;a class=&quot;Login&quot; onclick=&quot;$signInAction&quot;&gt;&lt;%=_ctx.appRes(&quot;UILoginForm.label.Signin&quot;)%&gt;&lt;/a&gt; </programlisting> @@ -314,7 +318,7 @@ </step> <step> <para> - Open the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file and change the line: + Open the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file and change the line: </para> <programlisting language="Java" role="java">&lt;a onclick=&quot;$signInAction&quot;&gt;&lt;%=_ctx.appRes(&quot;UILogoPortlet.action.signin&quot;)%&gt;&lt;/a&gt; </programlisting> @@ -335,23 +339,20 @@ The integration consists of two parts; the first part consists of installing or configuring a CAS server, the second part consists of setting up the portal to use the CAS server. </para> <procedure id="proc-Reference_Guide-Central_Authentication_Service-CAS_server"> - <title>CAS server</title> + <title>Installing CAS server, and defining <replaceable>CAS_DIR</replaceable></title> <step> <para> - Set up the server to authenticate against the portal login module. + Set up the server to authenticate against the portal login module, as described in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"/>. </para> </step> <step> <para> - Downloaded CAS from <ulink url="http://www.jasig.org/cas/download" type="http"> http://www.jasig.org/cas/download </ulink> . + Download the latest version of CAS from <ulink url="http://www.jasig.org/cas/download" type="http"/> . </para> - <para> - The version, tested with these instructions is <emphasis role="bold">CAS 3.3.5</emphasis>. Other versions may work. - </para> </step> <step> <para> - Extract the downloaded file into a suitable location. This location will be referred to as <replaceable>CAS_DIR</replaceable> in the following example. + Extract the downloaded file into a suitable location. This location is referred to as <replaceable>CAS_DIR</replaceable> in the following example. </para> </step> </procedure> @@ -370,7 +371,7 @@ The CAS Server Plug-in makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. </para> <para> - In order for the plug-in to function correctly, it needs to be properly configured to connect to this service. This configuration is controlled by the <filename>cas.war/WEB-INF/deployerConfigContext.xml </filename> file. + In order for the plug-in to function correctly, it needs to be properly configured to connect to this service. This configuration is controlled by the <filename>cas.war/WEB-INF/deployerConfigContext.xml</filename> file. </para> <procedure id="proc-Reference_Guide-Central_Authentication_Service-Modifying_CAS_server"> <title>Modifying CAS server</title> @@ -385,23 +386,32 @@ </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default102.xml" parse="text"/></programlisting> <para> - with the following (ensure you set the host, port and context with the values corresponding to your portal). Also available in <filename>PORTAL_SSO/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>.): + with the following (ensure you set the host, port and context with the values corresponding to your portal). The code is available for direct copy in the <filename>PORTAL_SSO/cas/plugin/WEB-INF/deployerConfigContext.xml</filename> file: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default103.xml" parse="text"/></programlisting> </step> <step> <para> - Copy <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/sso-cas-plugin-&lt;VERSION&gt;.jar</filename> and <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/commons-httpclient-&lt;VERSION&gt;.jar</filename> into the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/src/main/webapp/WEB-INF/lib</filename> created directory. - </para> + Copy the following files into the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/src/main/webapp/WEB-INF/lib</filename> directory:</para> + <itemizedlist> + <listitem> + <para><filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/sso-cas-plugin-<replaceable>VERSION</replaceable>.jar</filename></para> + </listitem> + <listitem> + <para><filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/commons-httpclient-<replaceable>VERSION</replaceable>.jar</filename></para> + </listitem> + </itemizedlist> </step> <step> <para> - If you have not already done so, download an instance of Tomcat and extract it into a suitable location (which will be called <filename>TOMCAT_HOME</filename> for these instructions). + If you have not already done so, download an instance of Tomcat and extract it into a suitable location (which will be called <filename> + <replaceable>HTTPD_DIST</replaceable> + </filename> for these instructions). </para> </step> <step> <para> - Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform. + Edit <filename><replaceable>HTTPD_DIST</replaceable>/conf/server.xml</filename> and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform. </para> <note> <para> @@ -418,7 +428,7 @@ </step> <step> <para> - Copy the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/target/cas.war</filename> file into the <filename>TOMCAT_HOME/webapps</filename> directory. + Copy the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/target/cas.war</filename> file into the <filename>HTTPD_DIST/webapps</filename> directory. </para> <para> Tomcat should start without issue and should be accessible at <ulink url="http://localhost:8888/cas" type="http"> http://localhost:8888/cas </ulink> . @@ -452,12 +462,12 @@ <title>Setup the CAS client</title> <step> <para> - Copy all the libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/cas/gatein.ear/lib</filename> directory into the <filename>EPP_HOME/server/default/deploy/gatein.ear/lib</filename>) directory. + Copy all the libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/cas/gatein.ear/lib</filename> directory into the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/default/deploy/gatein.ear/lib</filename>) directory. </para> </step> <step> <para> - Edit the <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: + Edit the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default105.xml" parse="text"/></programlisting> <para> @@ -501,13 +511,13 @@ <title>Redirect to CAS</title> <step> <para> - Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: + Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default106.xml" parse="text"/></programlisting> </step> <step> <para> - Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: + Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default107.xml" parse="text"/></programlisting> </step> @@ -529,157 +539,130 @@ </para> </section> <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> - <title>Java Open Single Sign-On Project</title> + <title><remark>BZ#794433</remark>Java Open Single Sign-On Project</title> + <para>Configuring JOSSO for JBoss Enterprise Application Platform requires an Apache server instance to host JOSSO. JBoss Enterprise Application Platform communicates with the JOSSO Apache instance through the Single Sign On plug-in.</para> <para> - This Single Sign On plug-in enables seamless integration between JBoss Enterprise Portal Platform and the Java Open Single Sign-On Project (<emphasis role="bold">JOSSO</emphasis>) Single Sign On Framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"> www.josso.org </ulink> . + This Single Sign On plug-in enables seamless integration between JBoss Enterprise Portal Platform and the Java Open Single Sign-On Project (JOSSO) Single Sign On Framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"/> . </para> - <para> - This section details setting up the JOSSO server to authenticate against the JBoss Enterprise Portal Platform login module. + <para> The procedures in this section detail setting up the JOSSO server to authenticate against the JBoss Enterprise Portal Platform login module. </para> + <para>After completing all procedures in this section, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. + </para> <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-JOSSO_server"> - <title>JOSSO server</title> + <title>Download and extract JOSSO server</title> <step> <para> - Download JOSSO from <ulink url="http://sourceforge.net/projects/josso/files/" type="http"> http://sourceforge.net/projects/josso/files/ </ulink> . + Download an embedded Apache JOSSO version from <ulink url="http://sourceforge.net/projects/josso/files/JOSSO/" type="http"> http://sourceforge.net/projects/josso/files/ </ulink> . </para> <note> - <para> - Use the package that embeds Apache Tomcat. The integration was tested with JOSSO-1.8.1. - </para> + <para>JOSSO versions between 1.8.1 to 1.8.4 are supported. Versions other than these do not offer an embedded Apache instance.</para> + <para>The JOSSO version is referred to as <replaceable>josso-18X</replaceable> in all procedures within this section. </para> </note> </step> <step> <para> - Extract the package into what will be called <filename>JOSSO_HOME</filename> in this example. + Extract the package to an appropriate directory. This location is referred to as <filename>JOSSO_HOME</filename> in this example. </para> </step> </procedure> <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Modifying_JOSSO_server"> - <title>Modifying JOSSO server</title> + <title>Configure the JOSSO server</title> <step> - <para> - Copy the files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/plugin</filename> into the <filename>JOSSO_HOME</filename> directory created in the last step. - </para> - <para>If you have JOSSO 1.8.1, copy the files from <filename>PORTAL_SSO/josso/josso-181/plugin</filename> into the Tomcat directory (<filename>JOSSO_HOME</filename>).</para> - <para>If you have JOSSO 1.8.2 or newer, copy the files from <filename>PORTAL_SSO/josso/josso-182/plugin</filename> into the Tomcat directory (<filename>JOSSO_HOME</filename>).</para> - <para> - This action should replace or add the following files to the <filename>JOSSO_HOME/webapps/josso/WEB-INF/lib</filename> directory: - </para> + <para>Copy the specified files from <filename>PORTAL_SSO/josso/<replaceable>josso-18X</replaceable>/plugin</filename> </para> <itemizedlist> <listitem> - <para> - <filename>JOSSO_HOME/lib/josso-gateway-config.xml</filename> - </para> + <para>josso-gateway-config.xml</para> </listitem> <listitem> - <para> - <filename>JOSSO_HOME/lib/josso-gateway-gatein-stores.xml</filename> - </para> + <para>josso-gateway-gatein-stores.xml</para> </listitem> - <listitem> - <para> - <filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties</filename> - </para> - </listitem> </itemizedlist> </step> <step> - <para> - Edit <filename>TOMCAT_HOME/conf/server.xml</filename> file and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform port. + <para>Paste the files into the <filename><replaceable>JOSSO_HOME</replaceable>/webapps/josso/WEB-INF/lib</filename> directory.</para> + </step> + <step> + <para>Copy <filename>PORTAL_SSO/josso/<replaceable>josso-18X</replaceable>/plugin/gatein.properties</filename> to the <filename><replaceable>JOSSO_HOME</replaceable>/webapps/josso/WEB-INF/classes/</filename> directory</para> + </step> + <step> + <para> Edit the <filename>JOSSO_HOME/conf/server.xml</filename> file and change all ports from 8080 to 8888. This port change prevents a conflict with the default JBoss Enterprise Portal Platform port. <note> <title>Port Conflicts</title> <para> - If JBoss Enterprise Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change admin port from 8005 to 8805, and AJP port from 8009 to 8809. + If JBoss Enterprise Portal Platform is running on the same machine as Apache, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change the <literal>admin</literal> port from 8005 to 8805, and the <literal>AJP</literal> port from 8009 to 8809. </para> </note> </para> </step> <step> - <para> - Tomcat will start and allow access to <ulink url="http://localhost:8888/josso/signon/login.do" type="http"> http://localhost:8888/josso/signon/login.do </ulink> but at this stage login will not be available. - </para> - <mediaobject> - <imageobject> - <imagedata width="444" fileref="images/AuthenticationAndIdentity/SSO/opensso.png" format="PNG"/> - </imageobject> - </mediaobject> + <para>Follow the steps in <xref linkend="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_JOSSO_client"/> to configure the JOSSO Client. </para> </step> </procedure> <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_JOSSO_client"> - <title> Setup the JOSSO client</title> + <title> Configure the JOSSO client </title> <note> <para> There are some changes in JOSSO agent API between versions 1.8.1 and 1.8.2, which require different modules for different JOSSO versions. -This procedure uses <replaceable>josso-18X</replaceable> to substitute the directory <emphasis>josso-181</emphasis> if you -have JOSSO 1.8.1 and <emphasis>josso-182</emphasis> if you have JOSSO 1.8.2 or newer. +This procedure uses <replaceable>josso-18X</replaceable> to substitute the directory <filename>josso-181</filename>, or josso-182 or newer. </para> </note> <step> - <para>Copy the library files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/<replaceable>josso-18X</replaceable>/gatein.ear/lib</filename> into <filename>gatein.ear/lib</filename>.</para> + <para>Copy the library files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/<replaceable>josso-18X</replaceable>/gatein.ear/lib</filename> into <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib</filename>.</para> </step> <step> <para> - Copy the <filename><replaceable>PORTAL_SSO</replaceable>/josso/<replaceable>josso-18X</replaceable>/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename> file into the <filename>gatein.ear/02portal.war/WEB-INF/classes</filename> directory. + Copy <filename><replaceable>PORTAL_SSO</replaceable>/josso/<replaceable>josso-18X</replaceable>/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename> and paste the file into the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/classes</filename> directory. </para> </step> <step> <para> - Edit <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: + Edit <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default111.xml" parse="text"/></programlisting> </step> <step> - <para> - In Tomcat, edit <filename>EPP_HOME/conf/jaas.conf</filename> and uncomment this section: - </para> - <programlisting>org.gatein.sso.agent.login.SSOLoginModule required; -org.exoplatform.services.security.j2ee.TomcatLoginModule requiredtm -portalContainerName=portal -realmName=gatein-domain; -</programlisting> + <para>Follow the procedure in <xref linkend="proc-Test_the_JOSSO_Installation"/> to verify the login configuration is correct. </para> </step> + </procedure> + <procedure id="proc-Test_the_JOSSO_Installation"> + <title>Test the JOSSO Installation</title> <step> <para> - The installation can be tested at this point. - </para> - <substeps> - <step> - <para> - Start (or restart) JBoss Enterprise Portal Platform, and (assuming the JOSSO server on Tomcat is running) direct your browser to <ulink url="http://localhost:8888/josso/signon/login.do" type="http"> http://localhost:8888/josso/signon/login.do </ulink> . + Start (or restart) JBoss Enterprise Portal Platform. </para> - </step> - <step> - <para> - Login with the username <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal. - </para> - </step> - </substeps> </step> + <step> + <para>Start (or restart) the JOSSO Apache instance.</para> + </step> + <step> + <para>Open <ulink url="http://localhost:8888/josso/signon/login.do"/> to display the JOSSO login screen.</para> + </step> + <step> + <para> + Login with the user name <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal to verify the configuration to this point is correct. </para> + </step> </procedure> - <para> - The next part of the process is to redirect all user authentication to the JOSSO server. - </para> - <para> - Information about where the JOSSO server is hosted must be properly configured within the JBoss Enterprise Portal Platform instance. The required configuration is done by modifying four files: - </para> <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_portal_to_redirect_to_JOSSO"> - <title>Setup the portal to redirect to JOSSO</title> + <title>Redirect portal authentication to JOSSO</title> + <para>Redirect all user authentication to the JOSSO server. + Information about where the JOSSO server is hosted must be properly configured within the JBoss Enterprise Portal Platform instance. + </para> <step> <para> - In the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file modify the &apos;Sign In&apos; link as follows: + In the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file modify the <guilabel>Sign In</guilabel> link as follows: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default112.xml" parse="text"/></programlisting> </step> <step> <para> - Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: + Modify the <guilabel>Sign In</guilabel> link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default113.xml" parse="text"/></programlisting> </step> <step> <para> - Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: + Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with the following HTML code: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default114.xml" parse="text"/></programlisting> </step> @@ -690,9 +673,6 @@ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default115.xml" parse="text"/></programlisting> </step> </procedure> - <para> - From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. - </para> </section> <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenSSO"> <title>OpenSSO</title> @@ -765,17 +745,17 @@ <itemizedlist> <listitem> <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-&lt;VERSION&gt;.jar</filename> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-<replaceable>VERSION</replaceable>.jar</filename> </para> </listitem> <listitem> <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-httpclient-&lt;VERSION&gt;.jar</filename> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-httpclient-<replaceable>VERSION</replaceable>.jar</filename> </para> </listitem> <listitem> <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-logging-&lt;VERSION&gt;.jar</filename> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-logging-<replaceable>VERSION</replaceable>.jar</filename> </para> </listitem> </itemizedlist> @@ -914,15 +894,15 @@ <title>Setup the OpenSSO client</title> <step> <para> - Copy all libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/gatein.ear/lib</filename> directory into the <filename>EPP_HOME/server/default/deploy/gatein.ear/lib</filename> directory. + Copy all libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/gatein.ear/lib</filename> directory into the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/default/deploy/gatein.ear/lib</filename> directory. </para> <para> - Alternatively, in a Tomcat environment, copy the libraries into the <filename>EPP_HOMEibib</filename> directory. + Alternatively, in a Tomcat environment, copy the libraries into the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/ibib</filename> directory. </para> </step> <step> <para> - Edit the <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: + Edit the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default118.xml" parse="text"/></programlisting> </step> @@ -968,7 +948,7 @@ <title>Setup the portal to redirect to OpenSSO</title> <step> <para> - Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: + Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default119.xml" parse="text"/></programlisting> </step> @@ -997,7 +977,7 @@ </section> </section> <section id="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"> - <title>SPNEGO - Simple and Protected GSSAPI Negotiation Mechanism</title> + <title>Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO)</title> <para> The Simple and Protected GSSAPI Negotiation Mechanism (<emphasis role="bold">SPNEGO</emphasis>) uses desktop credentials provided during a desktop login to transparently authenticate a portal user through a web browser. </para> @@ -1312,10 +1292,10 @@ </step> <step> <para> - Add the SSO module binaries by copying <filename>PORTAL_SSO/spnego/gatein.ear/lib/sso-agent.jar</filename> to the <filename>EPP_HOME/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib/</filename> directory. + Add the SSO module binaries by copying <filename>PORTAL_SSO/spnego/gatein.ear/lib/sso-agent.jar</filename> to the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib/</filename> directory. </para> <para> - Copy the <filename>PORTAL_SSO/spnego/gatein.ear/lib/sso-spnego.jar</filename> file to the <filename>EPP_HOME/server/<replaceable>PROFILE</replaceable>/lib</filename> directory. + Copy the <filename>PORTAL_SSO/spnego/gatein.ear/lib/sso-spnego.jar</filename> file to the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/lib</filename> directory. </para> </step> <!-- This step not required as EPP already has the correct version of Negotiation 2.0.4.GA @@ -1328,7 +1308,7 @@ </step> --> <step> <para> - Modify the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file to match the following: + Modify the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file to match the following: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default126.xml" parse="text"/></programlisting> <para> @@ -1337,7 +1317,7 @@ </step> <step> <para> - Modify <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> to match: + Modify <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> to match: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default127.xml" parse="text"/></programlisting> <para> @@ -1371,13 +1351,13 @@ </step> <step> <para> - Integrate the request pre-processing needed for SPNEGO via filters by adding the following filters to the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> at the top of the Filter chain. + Integrate the request pre-processing needed for SPNEGO via filters by adding the following filters to the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> at the top of the Filter chain. </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default128.xml" parse="text"/></programlisting> </step> <step> <para> - Edit the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</filename> to match the following: + Edit the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</filename> to match the following: </para> <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default129.java" parse="text"/></programlisting> </step> @@ -1405,7 +1385,7 @@ Clicking the &apos;Sign In&apos; link on the JBoss Enterprise Portal Platform should automatically sign the &apos;demo&apos; user into the portal. </para> <para> - If you destroy your kerberos ticket with command <command>kdestroy</command>, then try to login again, you will directed to the login screen of JBoss Enterprise Portal Product because you don&apos;t have active Kerberos ticket. You can login with predefined account and password &quot;demo&quot;/&quot;gtn&quot; . + If you destroy your kerberos ticket with command <command>kdestroy</command>, then try to login again, you will directed to the login screen of JBoss Enterprise Portal Product because you do not have active Kerberos ticket. You can login with predefined account and password &quot;demo&quot;/&quot;gtn&quot; . </para> </section> </section> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Introduction.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Introduction.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Introduction.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -19,47 +19,6 @@ <para> This book provides a deep-dive information about installation and configuration of the services provided by JBoss Enterprise Portal Platform. </para> - <note> - <title>Notational Devices</title> - <para> - Along with the <emphasis>Document Conventions</emphasis> outlined in the <xref linkend="pref-Reference_Guide-Preface"/>, this document will also use the following notational devices: - <variablelist id="vari-Reference_Guide-Introduction-Devices"> - <title>Devices</title> - <varlistentry> - <term> - <replaceable>EPP_HOME</replaceable> - </term> - <listitem> - <para> - This device refers to the JBoss Enterprise Application Platform <application> - <filename>jboss-as</filename> - </application> directory deployed in JBoss Enterprise Portal Platform by default. - </para> - <para> - Therefore, if your JBoss Enterprise Portal Platform instance is deployed into a directory called <filename>/opt/jboss/jboss-epp-&VY;/</filename>, your <replaceable>EPP_HOME</replaceable> directory is <filename>/opt/jboss/jboss-epp-&VY;/jboss-as/</filename>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <replaceable>PROFILE</replaceable> - </term> - <listitem> - <para> - This device will usually follow an instance of <replaceable>EPP_HOME</replaceable> in a file path and refers to the directory that contains the server profile your JBoss Enterprise Portal Platform instance is configured to use. - </para> - <para> - JBoss Enterprise Portal Platform comes with six profiles by default; <emphasis role="bold">all</emphasis>, <emphasis role="bold">default</emphasis>, <emphasis role="bold">minimal</emphasis>, <emphasis role="bold">production</emphasis>, <emphasis role="bold">standard</emphasis> and <emphasis role="bold">web</emphasis>. These profiles are found in the <filename><replaceable>EPP_HOME</replaceable>/server/</filename> directory. - </para> - <para> - Therefore, if you are using the <emphasis>default</emphasis> profile, your <replaceable>PROFILE</replaceable> directory would be <filename><replaceable>EPP_HOME</replaceable>/server/default/</filename> - </para> - </listitem> - </varlistentry> - </variablelist> - - </para> - </note> <section id="sect-Reference_Guide-Introduction-Related_Links"> <title>Related Links</title> <variablelist> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -8,67 +8,63 @@ <section id="sect-Reference_Guide-Data_Import_Strategy-Introduction"> <title>Introduction</title> <para> - In the Portal extension mechanism, developers can define an extension that Portal data can be customized by configurations in the extension. There are several cases which an extension developer wants to define how to customize the Portal data, for example modifying, overwriting or just inserting a bit into the data defined by the portal. Therefore, GateIn also defines several modes for each case and the only thing which a developer has to do is to clarify the usecase and reasonably configure extensions. + In the Portal extension mechanism, developers can define an extension that Portal data can be customized by configurations in the extension. There are several cases which an extension developer wants to define how to customize the Portal data, for example modifying, overwriting or just inserting a bit into the data defined by the portal. Therefore, GateIn also defines several modes for each case and the only thing which a developer has to do is to clarify the use-case and reasonably configure extensions. </para> <para> This section shows you how data are changes in each mode. </para> </section> - <section id="sect-Reference_Guide-Data_Import_Strategy-Import_Mode"> - <title>Import Mode</title> + <section id="sect-Reference_Guide-Data_Import_Strategy-Data_Import_Strategy"> + <title>Data Import Strategy</title> <para> - In this section, the following modes for the import strategy are introduced: - </para> + The &apos;Portal Data&apos; term referred to in this section can be classified into three types of object data: </para> <itemizedlist> <listitem> - <para> - <literal>CONSERVE</literal> - </para> + <para>Portal Configuration</para> </listitem> <listitem> - <para> - <literal>MERGE</literal> - </para> + <para>Page Data</para> </listitem> <listitem> - <para> - <literal>INSERT</literal> - </para> + <para>Navigation Data</para> </listitem> - <listitem> + </itemizedlist> + <para>Each type of object data has some differences in the import strategy. + </para> + <section id="sect-Reference_Guide-Data_Import_Strategy-Portal_Config"> + <title>Portal Configuration</title> + <para> + PortalConfig defines the portal name, permission, layout and some properties of a site. These information are configured in the <emphasis>portal.xml</emphasis>, <emphasis>group.xml</emphasis> or <emphasis>user.xml</emphasis>, depending on the site type. The PortalConfig importer performs a strategy that is based on the mode defined in NewPortalConfigListener, including <literal>CONSERVE</literal>, <literal>INSERT</literal>, <literal>MERGE</literal> or <literal>OVERWRITE</literal>. Let&apos;s see how the import mode affects in the process of portal data performance: + </para> + <itemizedlist> + <listitem> + <para> + <literal>CONSERVE</literal>: There is nothing to be imported. The existing data will be kept without any changes. + </para> + </listitem> + <listitem> + <para> + <literal>INSERT</literal>: When the portal configuration does not exist, create the new portal defined by the portal configuration definition. Otherwise, do nothing. + </para> + </listitem> + <listitem> + <para> + <literal>MERGE</literal> and <literal>OVERWRITE</literal> have the same behavior. The new portal configuration will be created if it does not exist or update portal properties defined by the portal configuration definition. + </para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-Data_Import_Strategy-Page_Data"> + <title>Page Data</title> + <para> + The import mode affects the page data import as the same as PortalConfig. + </para> + <note> <para> - <literal>OVERWRITE</literal> + If the Import mode is <literal>CONSERVE</literal> or <literal>INSERT</literal>, the data import strategy always performs as the <literal>MERGE</literal> mode in the first data initialization of the Portal. </para> - </listitem> - </itemizedlist> - <para> - Each mode indicates how the Portal data are imported. The import mode value is set whenever <literal>NewPortalConfigListener</literal> is initiated. If the mode is not set, the default value will be used in this case. The default value is configurable as a UserPortalConfigService initial param. For example, the bellow configuration means that default value is <literal>MERGE</literal>. - </para> - <programlisting language="XML" role="XML"> -&lt;component&gt; - &lt;key&gt;org.exoplatform.portal.config.UserPortalConfigService&lt;/key&gt; - &lt;type&gt;org.exoplatform.portal.config.UserPortalConfigService&lt;/type&gt; - &lt;component-plugins&gt; - ............ - &lt;/component-plugins&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;default.import.mode&lt;/name&gt; - &lt;value&gt;merge&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; -&lt;/component&gt; - -</programlisting> - <para> - The way that the import strategy works with the import mode will be clearly demonstrated in next sections for each type of data. - </para> - </section> - <section id="sect-Reference_Guide-Data_Import_Strategy-Data_Import_Strategy"> - <title>Data Import Strategy</title> - <para> - The &apos;Portal Data&apos; term which has been referred in the previous sections can be classified into three types of object data: Portal Config, Page Data and Navigation Data; each of which has some differences in the import strategy. - </para> + </note> + </section> <section id="sect-Reference_Guide-Data_Import_Strategy-Navigation_Data"> <title>Navigation Data</title> <para> @@ -225,39 +221,55 @@ </varlistentry> </variablelist> </section> - <section id="sect-Reference_Guide-Data_Import_Strategy-Portal_Config"> - <title>Portal Config</title> - <para> - PortalConfig defines the portal name, permission, layout and some properties of a site. These information are configured in the <emphasis>portal.xml</emphasis>, <emphasis>group.xml</emphasis> or <emphasis>user.xml</emphasis>, depending on the site type. The PortalConfig importer performs a strategy that is based on the mode defined in NewPortalConfigListener, including <literal>CONSERVE</literal>, <literal>INSERT</literal>, <literal>MERGE</literal> or <literal>OVERWRITE</literal>. Let&apos;s see how the import mode affects in the process of portal data performance: - </para> - <itemizedlist> - <listitem> - <para> - <literal>CONSERVE</literal>: There is nothing to be imported. The existing data will be kept without any changes. - </para> - </listitem> - <listitem> - <para> - <literal>INSERT</literal>: When the portal config does not exist, create the new portal defined by the portal config definition. Otherwise, do nothing. - </para> - </listitem> - <listitem> - <para> - <literal>MERGE</literal> and <literal>OVERWRITE</literal> have the same behavior. The new portal config will be created if it does not exist or update portal properties defined by the portal config definition. - </para> - </listitem> - </itemizedlist> - </section> - <section id="sect-Reference_Guide-Data_Import_Strategy-Page_Data"> - <title>Page Data</title> - <para> - The import mode affects the page data import as the same as Portal Config. - </para> - <note> + </section> + <section id="sect-Reference_Guide-Data_Import_Strategy-Import_Mode"> + <title>Import Mode</title> + <para> + In this section, the following modes for the import strategy are introduced: + </para> + <itemizedlist> + <listitem> <para> - If the Import mode is <literal>CONSERVE</literal> or <literal>INSERT</literal>, the data import strategy always performs as the <literal>MERGE</literal> mode in the first data initialization of the Portal. + <literal>CONSERVE</literal> </para> - </note> - </section> + </listitem> + <listitem> + <para> + <literal>MERGE</literal> + </para> + </listitem> + <listitem> + <para> + <literal>INSERT</literal> + </para> + </listitem> + <listitem> + <para> + <literal>OVERWRITE</literal> + </para> + </listitem> + </itemizedlist> + <para> + Each mode indicates how the portal data is imported. The import mode value is set whenever <literal>NewPortalConfigListener</literal> is initiated. If the mode is not set, the default value will be used in this case. The default value is configurable as a UserPortalConfigService initial param. For example, the bellow configuration means that default value is <literal>MERGE</literal>. + </para> + <programlisting language="XML" role="XML"> +&lt;component&gt; + &lt;key&gt;org.exoplatform.portal.config.UserPortalConfigService&lt;/key&gt; + &lt;type&gt;org.exoplatform.portal.config.UserPortalConfigService&lt;/type&gt; + &lt;component-plugins&gt; + ............ + &lt;/component-plugins&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;default.import.mode&lt;/name&gt; + &lt;value&gt;merge&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; +&lt;/component&gt; + +</programlisting> + <para> + The way that the import strategy works with the import mode will be clearly demonstrated in next sections for each type of data. + </para> </section> </chapter> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -209,7 +209,7 @@ This configuration file structure is very similar to <filename>portal.xml</filename> and it can also contain container tags (some usage examples of container tags can be found in <filename>02portal.war/WEB-INF/conf/portal/portal/sharedlayout.xml</filename>). </para> <para> - Each application can decide whether to render the portlet border, the window state, the icons or portlet&apos;s mode. + Each application can decide whether to render the portlet border, the window state, the icons, or the portlet mode. </para> <!-- DOC NOTE: look into including some actual examples of 'container tags' from sharedlayout.xml in place here. --> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/pages.xml" parse="text"/></programlisting> </listitem> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -8,7 +8,7 @@ <section id="sect-Reference_Guide-Portal_Default_Permission_Configuration-Overview"> <title>Overview</title> <para> - The default permission configuration for the portal is defined through the <literal>org.exoplatform.portal.config.UserACL</literal> component configuration in the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename> file. + The default permission configuration for the portal is defined through the <literal>org.exoplatform.portal.config.UserACL</literal> component configuration in the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/portal/portal-configuration.xml</filename> file. </para> <para> It defines eight permissions types: Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,237 +1,198 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Internationalization_Configuration"> - <title>Internationalization Configuration</title> - <section id="sect-Reference_Guide-Internationalization_Configuration-Overview"> - <title>Overview</title> - <note> - <title>Assumed Knowledge</title> - <para> + <title>Internationalization Configuration</title> + <section id="sect-Reference_Guide-Internationalization_Configuration-Overview"> + <title>Overview</title> + <note> + <title>Assumed Knowledge</title> + <para> JBoss Enterprise Portal Platform is fully configurable for internationalization, however users should have a general knowledge of Internationalization in Java products before attempting these configurations. </para> - <para> - Sun Java hosts a comprehensive guide to internationalizing java products at <ulink url="http://java.sun.com/docs/books/tutorial/i18n/TOC.html" />. + <para> + Sun Java hosts a comprehensive guide to internationalizing Java products at <ulink url="http://java.sun.com/docs/books/tutorial/i18n/TOC.html"/>;. </para> - - </note> - <para> + </note> + <para> All JBoss Enterprise Portal Platform applications contain property files for various languages. They are packaged with the portlets applications in a <filename>WEB-INF/classes/locale/</filename> directory. </para> - <para> + <para> These files are located in the <filename>classes</filename> folder of the <filename>WEB-INF</filename> directory, so as to be loaded by the <literal>ClassLoader</literal>. </para> - <para> - All resource files are in a subfolder named <literal>locale</literal>. + <para> + All resource files are in a sub-folder named <literal>locale</literal>. </para> - <para> + <para> For instance; the translations for the <emphasis>NavigationPortlet</emphasis> are located in <filename>web.war/WEB-INF/classes/locale/portlet/portal</filename> </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_InternationalizationConfiguration/default147.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_InternationalizationConfiguration/default147.java" parse="text"/></programlisting> + <para> Inside those file are typical <literal>key=value</literal> Java EE properties. For example; in the <literal>Spanish</literal> file: </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_InternationalizationConfiguration/default148.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_InternationalizationConfiguration/default148.java" parse="text"/></programlisting> + <para> There are also properties files in the portal itself. They form the <emphasis role="bold">portal resource bundle</emphasis>. </para> - <para> + <para> From a portlet you can then access translations from the portlet itself or shared at the portal level, both are aggregated when you need them. </para> - <note> - <title>Translation in XML Format</title> - <para> + <note> + <title>Translation in XML Format</title> + <para> It is also possible to use a proprietary XML format to define translations. This is a more convenient way to translate a document for some languages such as Japanese, Arabic or Russian. </para> - <para> - Property files have to be ISO 8859-1 encoded, while the XML file can define its encoding. As a result it's easier for a human being to read a translation in XML instead of having to decode and encode the property file. + <para> + Property files have to be ISO 8859-1 encoded, while the XML file can define its encoding. As a result it&apos;s easier for a human being to read a translation in XML instead of having to decode and encode the property file. </para> - <para> - For more information refer to: <xref linkend="chap-Reference_Guide-XML_Resources_Bundles" /> + <para> + For more information refer to: <xref linkend="chap-Reference_Guide-XML_Resources_Bundles"/> </para> - - </note> - - </section> - - <section id="sect-Reference_Guide-Internationalization_Configuration-Locales_Configuration"> - <title>Locales Configuration</title> - <para> - Various languages are available in the portal package. The configuration below will define which languages are shown in the "<emphasis role="bold">Change Language</emphasis>" section and made available to users. + </note> + </section> + <section id="sect-Reference_Guide-Internationalization_Configuration-Locales_Configuration"> + <title>Locales Configuration</title> + <para> + Various languages are available in the portal package. The configuration below will define which languages are shown in the &quot;<emphasis role="bold">Change Language</emphasis>&quot; section and made available to users. </para> - <para> + <para> The <filename>02portal.war:/WEB-INF/conf/common/common-configuration.xml</filename> file of your installation contains the following section: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_InternationalizationConfiguration/default149.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_InternationalizationConfiguration/default149.xml" parse="text"/></programlisting> + <para> This configuration points to the locale configuration file. </para> - <para> + <para> The locale configuration file (<filename>02portal.war:/WEB-INF/conf/common/locales-config.xml</filename>) contains the following code: </para> - <programlistingco> - <areaspec> - <area coords="4" id="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-locale" /> - <area coords="5" id="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-output-encoding" /> - <area coords="6" id="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-input-encoding" /> - <area coords="7" id="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-description" /> - <area coords="22" id="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-orientation" /> - - </areaspec> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_InternationalizationConfiguration/default150.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-locale"> - <para> - <emphasis>locale</emphasis>: The locale has to be defined as per the codes defined <ulink type="http" url="http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt"&g...;. In this example "<emphasis>ar</emphasis>" is Arabic. + <programlistingco> + <areaspec> + <area coords="4" id="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-locale"/> + <area coords="5" id="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-output-encoding"/> + <area coords="6" id="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-input-encoding"/> + <area coords="7" id="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-description"/> + <area coords="22" id="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-orientation"/> + </areaspec> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_InternationalizationConfiguration/default150.xml" parse="text"/></programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-locale"> + <para> + <emphasis>locale</emphasis>: The locale has to be defined as per the codes defined <ulink url="http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt" type="http">here</ulink>. In this example &quot;<emphasis>ar</emphasis>&quot; is Arabic. </para> - - </callout> - <callout arearefs="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-output-encoding"> - <para> - <emphasis>output-encoding</emphasis>: deals with character encoding. It is recommended that <emphasis role="bold">UTF-8</emphasis> be used. + </callout> + <callout arearefs="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-output-encoding"> + <para> + <emphasis>output-encoding</emphasis>: deals with character encoding. It is recommended that UTF-8 be used. </para> - - </callout> - <callout arearefs="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-input-encoding"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-input-encoding"> + <para> <emphasis>input-encoding</emphasis>: In the Java implementation, the encoding parameters will be used for the request response stream. The input-encoding parameter will be used for request <literal>setCharacterEncoding(..)</literal>. </para> - - </callout> - <callout arearefs="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-description"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-description"> + <para> <emphasis>description</emphasis>: A description of the language </para> - - </callout> - <callout arearefs="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-orientation"> - <para> - <emphasis>orientation</emphasis>: Although the default orientation of text and images is Left-To-Right, JBoss Enterprise Portal Platform supports <emphasis role="bold">Right-To-Left</emphasis> orientation. Modifying text orientation is explained in <xref linkend="chap-Reference_Guide-Right_To_Left_RTL_Framework" />. + </callout> + <callout arearefs="area-Reference_Guide-Internationalization_Configuration-Locales_Configuration-orientation"> + <para> + <emphasis>orientation</emphasis>: Although the default orientation of text and images is Left-To-Right, JBoss Enterprise Portal Platform supports <emphasis role="bold">Right-To-Left</emphasis> orientation. Modifying text orientation is explained in <xref linkend="chap-Reference_Guide-Right_To_Left_RTL_Framework"/>. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - - </section> - - <section id="sect-Reference_Guide-Internationalization_Configuration-ResourceBundleService"> - <title>ResourceBundleService</title> - <para> + </callout> + </calloutlist> + </programlistingco> + </section> + <section id="sect-Reference_Guide-Internationalization_Configuration-ResourceBundleService"> + <title>ResourceBundleService</title> + <para> The resource bundle service is configured in: <filename>02portal.war:/WEB-INF/conf/common/common-configuration.xml</filename>: </para> - <programlistingco> - <areaspec> - <area coords="6 60" id="area-Reference_Guide-Internationalization_Configuration-ResourceBundleService-classpath_resources" /> - <area coords="24 60" id="area-Reference_Guide-Internationalization_Configuration-ResourceBundleService-portal_resource_names" /> - - </areaspec> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_InternationalizationConfiguration/default151.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-Internationalization_Configuration-ResourceBundleService-classpath_resources"> - <para> + <programlistingco> + <areaspec> + <area coords="6 60" id="area-Reference_Guide-Internationalization_Configuration-ResourceBundleService-classpath_resources"/> + <area coords="24 60" id="area-Reference_Guide-Internationalization_Configuration-ResourceBundleService-portal_resource_names"/> + </areaspec> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_InternationalizationConfiguration/default151.xml" parse="text"/></programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide-Internationalization_Configuration-ResourceBundleService-classpath_resources"> + <para> <emphasis>classpath.resources</emphasis>: These are discussed in a later section. </para> - - </callout> - <callout arearefs="area-Reference_Guide-Internationalization_Configuration-ResourceBundleService-portal_resource_names"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-Internationalization_Configuration-ResourceBundleService-portal_resource_names"> + <para> <emphasis>portal.resource.names</emphasis>: Defines all resources that belong to the <emphasis>Portal Resource Bundle</emphasis>. </para> - <para> + <para> These resources are merged to a single resource bundle which is accessible from anywhere in JBoss Enterprise Portal Platform. All these keys are located in the same bundle, which is separated from the navigation resource bundles. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - - </section> - - <section id="sect-Reference_Guide-Internationalization_Configuration-Navigation_Resource_Bundles"> - <title>Navigation Resource Bundles</title> - <para> + </callout> + </calloutlist> + </programlistingco> + </section> + <section id="sect-Reference_Guide-Internationalization_Configuration-Navigation_Resource_Bundles"> + <title>Navigation Resource Bundles</title> + <para> There is a resource bundle for each navigation. A navigation can exist for user, groups, and portal. </para> - <para> + <para> The previous example shows bundle definitions for the navigation of the classic portal and of four different groups. Each of these resource bundles occupies a different sphere, they are independent of each other and they are not included in the <parameter>portal.resource.names</parameter> parameter. </para> - <para> + <para> The properties for a group must be in the <filename>WEB-INF/classes/locale/navigation/group/</filename> folder. For example; <literal>/WEB-INF/classes/locale/navigation/group/organization/management/executive-board_en.properties</literal>. </para> - <para> - The folder and file names must correspond to the group hierarchy. The group name "<parameter>executive-board</parameter>" is followed by the <emphasis role="bold">iso 639</emphasis> code. + <para> + The folder and file names must correspond to the group hierarchy. The group name &quot;<parameter>executive-board</parameter>&quot; is followed by the ISO 639 code. </para> - <para> + <para> Each language defined in <parameter>LocalesConfig</parameter> must have a resource file defined. If the name of a group is changed the name of the folder and/or files of the correspondent navigation resource bundles must also be changed. </para> - <para> + <para> Content of <filename>executive-board_en.properties</filename>: </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_InternationalizationConfiguration/default152.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_InternationalizationConfiguration/default152.java" parse="text"/></programlisting> + <para> This resource bundle is only accessible for the navigation of the <parameter>organization.management.executive-board</parameter> group. </para> - - </section> - - <section id="sect-Reference_Guide-Internationalization_Configuration-Portlets"> - <title>Portlets</title> - <para> + </section> + <section id="sect-Reference_Guide-Internationalization_Configuration-Portlets"> + <title>Portlets</title> + <para> Portlets are independent applications and deliver their own resource files. </para> - <para> - All shipped portlet resources are located in the <emphasis role="bold">locale/portlet</emphasis> subfolder. The ResourceBundleService parameter <emphasis role="bold">classpath.resources</emphasis> defines this subfolder. <!-- Doing so the resource file that are in ~~locale/portlet~~ will never be stored in the JCR and reloaded at each start of the application server. --> + <para> + All shipped portlet resources are located in the <emphasis role="bold">locale/portlet</emphasis> sub-folder. The ResourceBundleService parameter <emphasis role="bold">classpath.resources</emphasis> defines this sub-folder. <!-- Doing so the resource file that are in ~~locale/portlet~~ will never be stored in the JCR and reloaded at each start of the application server. --> </para> - <procedure id="proc-Reference_Guide-Portlets-To_add_a_Spanish_translation_to_the_GadgetPortlet"> - <title>To add a Spanish translation to the <parameter>GadgetPortlet</parameter></title> - <step> - <para> + <procedure id="proc-Reference_Guide-Portlets-To_add_a_Spanish_translation_to_the_GadgetPortlet"> + <title>To add a Spanish translation to the GadgetPortlet</title> + <step> + <para> Create the file <literal>GadgetPortlet_es.properties</literal> in: <filename>WEB-INF/classes/locale/portlet/gadget/GadgetPortlet</filename>. </para> - - </step> - <step> - <para> - In <filename>portlet.xml</filename>, add <parameter>Spanish</parameter> as a <emphasis role="bold">supported-locale</emphasis> ('<emphasis role="bold">es</emphasis>' is the two letter code for Spanish). The <emphasis role="bold">resource-bundle</emphasis> is already declared and is the same for all languages : + </step> + <step> + <para> + In <filename>portlet.xml</filename>, add <parameter>Spanish</parameter> as a <emphasis role="bold">supported-locale</emphasis> (&apos;<emphasis role="bold">es</emphasis>&apos; is the two letter code for Spanish). The <emphasis role="bold">resource-bundle</emphasis> is already declared and is the same for all languages : </para> - -<programlisting language="XML" role="XML">&lt;supported-locale&gt;en&lt;/supported-locale&gt; + <programlisting language="XML" role="XML">&lt;supported-locale&gt;en&lt;/supported-locale&gt; &lt;supported-locale&gt;es&lt;/supported-locale&gt; &lt;resource-bundle&gt;locale.portlet.gadget.GadgetPortlet&lt;/resource-bundle&gt;</programlisting> - - </step> - - </procedure> - - <para> + </step> + </procedure> + <para> See the portlet specification for more details about portlet internationalization. </para> - <section id="sect-Reference_Guide-Portlets-Standard_Portlet_Resource_Keys"> - <title>Standard Portlet Resource Keys</title> - <para> + <section id="sect-Reference_Guide-Portlets-Standard_Portlet_Resource_Keys"> + <title>Standard Portlet Resource Keys</title> + <para> The portlet specification defines three standard keys: <emphasis>Title</emphasis>, <emphasis>Short Title</emphasis> and <emphasis>Keywords</emphasis>. Keywords is formatted as a comma-separated list of tags. </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_InternationalizationConfiguration/default154.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <!-- Commented out as not fully enterprise ready: https://jira.jboss.org/browse/GTNPORTAL-1482 + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_InternationalizationConfiguration/default154.java" parse="text"/></programlisting> + </section> +<!-- Commented out as not fully enterprise ready: https://jira.jboss.org/browse/GTNPORTAL-1482 Will reinstate when issues resolved <section id="sect-Reference_Guide-_Portlets_-Debugging_Resource_Bundle_Usage"> <title>Debugging Resource Bundle Usage</title> @@ -290,9 +251,5 @@ <para> For example, the translated value for the key "<parameter>organization.title</parameter>" is simply the value "<parameter>organization.title</parameter>". Selecting that language allows use of the portal and its applications with all the keys visible. This makes it easier to find out the correct key for a given label in the portal page. </para> -</section> --> - </section> - - +</section> --> </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/JavascriptInterApplicationCommunication.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/JavascriptInterApplicationCommunication.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/JavascriptInterApplicationCommunication.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,213 +1,168 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-JavaScript_Inter_Application_Communication"> - <title>JavaScript Inter Application Communication</title> - <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Overview"> - <title>Overview</title> - <para> - JavaScript Inter Application Communication is designed to allow applications within a page to exchange data. This library is made for broadcasting messages on topic. - </para> - <para> - It is based on three functions: - </para> - <itemizedlist> - <listitem> - <para> - Subscribe. - </para> - - </listitem> - <listitem> - <para> - Publish. - </para> - - </listitem> - <listitem> - <para> - Unsubscribe. - </para> - - </listitem> - - </itemizedlist> - <para> - A subscription to a topic will receive any subtopic messages. For example, an application subscribed to "<literal>/eXo/application</literal>" will receive messages sent on the "<literal>/eXo/application/map</literal>" topic. A message sent on "<literal>/eXo</literal>", however, would not be received. - </para> - <variablelist id="vari-Reference_Guide-Overview-Subscription_Topics"> - <title>Subscription Topics</title> - <varlistentry> - <term>/eXo</term> - <listitem> - <para> - This topic contains all the events generated by the platform. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>/eXo/portal/notification</term> - <listitem> - <para> - A message is sent on this topic will prompt a pop-up notification in the top right of the screen. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Library"> - <title>Library</title> - <para> - The Inter Application Communication library is found in <filename>01eXoResources.war:/javascript/eXo/core/Topic.js</filename> - </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_JavascriptInterApplicationCommunication/default155.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Syntax"> - <title>Syntax</title> - <para> - The three messaging functions require particular objects and definitions in their syntax: - </para> - <variablelist> - <varlistentry> - <term>Subscribe</term> - <listitem> - <para> - The <literal>subscribe</literal> function is used to subscribe a callback to a topic. It uses the following parameters: - </para> - <variablelist> - <varlistentry> - <term>topic</term> - <listitem> - <para> - The topic that will be listened for. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>func</term> - <listitem> - <para> - The name of the object function to call when a message is received on the topic. It has to be a function that takes an Object parameter. The event received will have this format: -<programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_JavascriptInterApplicationCommunication/default156.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting>{ + <title>JavaScript Inter Application Communication</title> + <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Overview"> + <title>Overview</title> + <para> + JavaScript Inter Application Communication is designed to allow applications within a page to exchange data. This library is made for broadcasting messages on topic. + </para> + <para> + It is based on three functions: + </para> + <itemizedlist> + <listitem> + <para> + Subscribe. + </para> + </listitem> + <listitem> + <para> + Publish. + </para> + </listitem> + <listitem> + <para> + Unsubscribe. + </para> + </listitem> + </itemizedlist> + <para> + A subscription to a topic will receive any subtopic messages. For example, an application subscribed to &quot;<literal>/eXo/application</literal>&quot; will receive messages sent on the &quot;<literal>/eXo/application/map</literal>&quot; topic. A message sent on &quot;<literal>/eXo</literal>&quot;, however, would not be received. + </para> + <variablelist id="vari-Reference_Guide-Overview-Subscription_Topics"> + <title>Subscription Topics</title> + <varlistentry> + <term>/eXo</term> + <listitem> + <para> + This topic contains all the events generated by the platform. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>/eXo/portal/notification</term> + <listitem> + <para> + A message is sent on this topic will prompt a pop-up notification in the top right of the screen. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Library"> + <title>Library</title> + <para> + The Inter Application Communication library is found in <filename>01eXoResources.war:/javascript/eXo/core/Topic.js</filename> + </para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_JavascriptInterApplicationCommunication/default155.java" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Syntax"> + <title>Syntax</title> + <para> + The three messaging functions require particular objects and definitions in their syntax: + </para> + <variablelist> + <varlistentry> + <term>Subscribe</term> + <listitem> + <para> + The <literal>subscribe</literal> function is used to subscribe a callback to a topic. It uses the following parameters: + </para> + <variablelist> + <varlistentry> + <term>topic</term> + <listitem> + <para> + The topic that will be listened for. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>func</term> + <listitem> + <para> + The name of the object function to call when a message is received on the topic. It has to be a function that takes an Object parameter. The event received will have this format: +<programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_JavascriptInterApplicationCommunication/default156.java" parse="text"/></programlisting> + <!-- <programlisting>{ senderId:senderId, message:message, topic: topic } </programlisting> --> - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Publish</term> - <listitem> - <para> - The <literal>publish</literal> function is used to publish an event to the other subscribed applications through the given channels. Its parameters are: - </para> - <variablelist> - <varlistentry> - <term>senderId</term> - <listitem> - <para> - This is a string that identifies the sender. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>topicName</term> - <listitem> - <para> - The topic that the message will be published. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>message</term> - <listitem> - <para> - This is the message body to be delivered to the subscribers to the topic. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Unsubscribe</term> - <listitem> - <para> - The <literal>unsubscribe</literal> function is used to unsubscribe a callback to a topic. The required parameters are: - </para> - <variablelist> - <varlistentry> - <term>topic</term> - <listitem> - <para> - The topic that will is to be unsubscribed from. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>id</term> - <listitem> - <para> - This is the context object. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Example_of_Javascript_events_usage"> - <title>Example of Javascript events usage</title> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_JavascriptInterApplicationCommunication/default157.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>Publish</term> + <listitem> + <para> + The <literal>publish</literal> function is used to publish an event to the other subscribed applications through the given channels. Its parameters are: + </para> + <variablelist> + <varlistentry> + <term>senderId</term> + <listitem> + <para> + This is a string that identifies the sender. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>topicName</term> + <listitem> + <para> + The topic that the message will be published. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>message</term> + <listitem> + <para> + This is the message body to be delivered to the subscribers to the topic. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>Unsubscribe</term> + <listitem> + <para> + The <literal>unsubscribe</literal> function is used to unsubscribe a callback to a topic. The required parameters are: + </para> + <variablelist> + <varlistentry> + <term>topic</term> + <listitem> + <para> + The topic that will is to be unsubscribed from. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>id</term> + <listitem> + <para> + This is the context object. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Example_of_Javascript_events_usage"> + <title>Example of JavaScript events usage</title> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_JavascriptInterApplicationCommunication/default157.xml" parse="text"/></programlisting> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -57,7 +57,7 @@ The returned <literal>Locale</literal> has to be one of the locales supported by portal, otherwise it will fall back to the portal default <literal>Locale</literal>. </para> <para> - The supported locales are listed in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/common/locales-config.xml</filename> file as described in <xref linkend="sect-Reference_Guide-Internationalization_Configuration-Locales_Configuration"/> . + The supported locales are listed in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/common/locales-config.xml</filename> file as described in <xref linkend="sect-Reference_Guide-Internationalization_Configuration-Locales_Configuration"/> . </para> <para> The <literal>determineLocale()</literal> method takes a parameter of type <literal>LocaleContextInfo</literal>, which represents a compilation of preferred locales from different sources; user’s profile, portal default, browser language settings, current session, browser cookie. @@ -204,7 +204,7 @@ <section id="sect-Reference_Guide-Pluggable_Locale_Policy-LocalePolicy_Configuration"> <title>LocalePolicy Configuration</title> <para> - The <literal>LocalePolicy</literal> framework is enabled for portlets by configuring <literal>LocalizationLifecycle</literal> class in portal&apos;s webui configuration file: <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/webui-configuration.xml</filename>: + The <literal>LocalePolicy</literal> framework is enabled for portlets by configuring <literal>LocalizationLifecycle</literal> class in portal&apos;s webui configuration file: <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/webui-configuration.xml</filename>: </para> <programlisting language="XML" role="XML">&lt;application-life-cycle-listeners&gt; ... @@ -212,7 +212,7 @@ &lt;/application-life-cycle-listeners&gt; </programlisting> <para> - The default <literal>LocalePolicy</literal> implementation is installed as an eXo Kernel portal service via <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/portal/web-configuration.xml</filename>. + The default <literal>LocalePolicy</literal> implementation is installed as an eXo Kernel portal service via <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/portal/web-configuration.xml</filename>. </para> <para> The following excerpt is responsible for installing the service: @@ -229,10 +229,10 @@ <section id="sect-Reference_Guide-Pluggable_Locale_Policy-Keeping_non_bridged_resources_in_sync_with_current_Locale"> <title>Keeping non-bridged resources in sync with current Locale</title> <para> - All the resources in portals that are not portlets themselves, but are accessed through portlets - reading data through <literal>PortletRequest</literal>, and writing to <literal>PortletResponse</literal> - are referred to as &apos;bridged&apos;. Any resources that are accessed directly, bypassing portal filters and servlets, are referred to as &apos;non-bridged&apos;. + All the resources in portals that are not portlets themselves, but are accessed through portlets - reading data through <literal>PortletRequest</literal>, and writing to <literal>PortletResponse</literal> - are referred to as &apos;bridged&apos;. Any resources that are accessed directly, bypassing portal filters and servlets, are referred to as <firstterm>non-bridged</firstterm>. </para> <para> - Non-bridged servlets, and .jsps have no access to <literal>PortalRequest</literal>. They don&apos;t use <literal>PortletRequest.getLocale()</literal> to determine current <literal>Locale</literal>. Instead, they use <literal>ServletRequest.getLocale()</literal> which is subject to precise semantics defined by Servlet specification - it reflects browser&apos;s language preference. + Non-bridged servlets, and .jsps have no access to <literal>PortalRequest</literal>. They do not use <literal>PortletRequest.getLocale()</literal> to determine current <literal>Locale</literal>. Instead, they use <literal>ServletRequest.getLocale()</literal> which is subject to precise semantics defined by Servlet specification - it reflects browser&apos;s language preference. </para> <para> In other words, non-bridged resources do not have a notion of current <literal>Locale</literal> in the same sense that portlets do. The result is that when mixing portlets and non-bridged resources there may be a localization mismatch, an inconsistency in the language used by different resources composing your portal page. @@ -244,7 +244,7 @@ That way even localization of servlets, and .jsps accessed in a non-bridged manner can stay in sync with portlet localization. </para> <para> - <literal>LocalizationFilter</literal> is installed through the portal&apos;s web.xml file: <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. + <literal>LocalizationFilter</literal> is installed through the portal&apos;s web.xml file: <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. </para> <programlisting language="XML" role="XML">&lt;filter&gt; &lt;filter-name&gt;LocalizationFilter&lt;/filter-name&gt; Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -459,7 +459,7 @@ </para> <section id="sect-Reference_Guide-Rendering-_PortalURL_"> <title> - <emphasis role="bold">PortalURL</emphasis> + <emphasis role="bold">Portal URL</emphasis> </title> <para> <code>PortalURL</code> play a similar role at the portal level, its main role is to abstract the creation of an URL for a resource managed by the portal. @@ -589,7 +589,7 @@ </para> </section> <section id="sect-Reference_Guide-Rendering-Portlet_URLs"> - <title>Portlet URLs</title> + <title>Portlet URL</title> <para> Portlet URLs API implementation delegates to the portal <code>ComponentURL</code> (via the portlet container SPI). It is possible to control the language in the URL from a <code>PortletURL</code> object by setting a property named <code>gtn:lang</code>: </para> @@ -617,7 +617,7 @@ </programlisting> </section> <section id="sect-Reference_Guide-Rendering-Webui_URLBuilder_"> - <title>Webui <code>URLBuilder</code></title> + <title>WebUI <code>URL Builder</code></title> <para> This internal API for creating URL works as before and delegates to the <code>PortletURL</code> API when the framework is executed in a portlet and to a <code>ComponentURL</code> API when the framework is executed in the portal context. The API has been modified to take in account the language in URL with two properties on the builder: </para> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -67,7 +67,7 @@ It works by appending -lt or -rt to the stylesheet name. </para> <para> - For instance: <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet-rt.css</filename> will return the same stylesheet as <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet.css</filename> but processed for the RT orientation. The <parameter>-lt</parameter> suffix is optional. + For instance: <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet-rt.css</filename> will return the same stylesheet as <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet.css</filename> but processed for the RT orientation. The <parameter>-lt</parameter> suffix is optional. </para> <para> Stylesheet authors can annotate their stylesheet to create content that depends on the orientation. @@ -112,7 +112,7 @@ The web resource filter uses the same naming pattern as the skin service. When an image ends with the -rt suffix the portal will attempt to locate the original image and create a mirror of it. </para> <para> - For instance: requesting the image <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/01eXoResources.war/skin/DefaultSkin/webui/component/UITabSystem/UITabs/background/NormalTabStyle-rt.gif</filename> returns a mirror of the image <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/01eXoResources.war/skin/DefaultSkin/webui/component/UITabSystem/UITabs/background/NormalTabStyle.gif</filename>. + For instance: requesting the image <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/01eXoResources.war/skin/DefaultSkin/webui/component/UITabSystem/UITabs/background/NormalTabStyle-rt.gif</filename> returns a mirror of the image <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/01eXoResources.war/skin/DefaultSkin/webui/component/UITabSystem/UITabs/background/NormalTabStyle.gif</filename>. </para> <note> <para> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,575 +1,452 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> - <chapter id="chap-Reference_Guide-Skinning_the_Portal"> - <title>Skinning the Portal</title> - - <section id="sect-Reference_Guide-Skinning_the_Portal-Overview"> - <title>Overview</title> - - <para> +<chapter id="chap-Reference_Guide-Skinning_the_Portal"> + <title>Skinning the Portal</title> + <section id="sect-Reference_Guide-Skinning_the_Portal-Overview"> + <title>Overview</title> + <para> JBoss Enterprise Portal Platform provides robust skinning support for the entire portal User Interface (UI). This includes support for skinning all of the common portal elements as well as being able to provide custom skins and window decoration for individual portlets. This has been designed with common graphic resource reuse and ease of development in mind. </para> - </section> - - <section id="sect-Reference_Guide-Skinning_the_Portal-Skin_Components"> - <title>Skin Components</title> - - <para> + </section> + <section id="sect-Reference_Guide-Skinning_the_Portal-Skin_Components"> + <title>Skin Components</title> + <para> The skin of a page is composed of three separate parts: </para> - - <variablelist> - <varlistentry> - <term>Portal Skin</term> - - <listitem> - <para> + <variablelist> + <varlistentry> + <term>Portal Skin</term> + <listitem> + <para> The portal skin contains the CSS styles for the portal and its various UI components. This should include all the UI components except for the window decorators and portlet specific styles. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Window Styles</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>Window Styles</term> + <listitem> + <para> The CSS styles associated with the portlet window decorators. The window decorators contain the control buttons and borders surrounding each portlet. Individual portlets can have their own window decorator selected or be rendered without one. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Portlet Skins</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>Portlet Skins</term> + <listitem> + <para> The portlet skins dictate how portlets are rendered on the page. There are two main ways they can be effected: </para> - - <variablelist> - <varlistentry> - <term>Portlet Specification CSS Classes</term> - - <listitem> - <para> + <variablelist> + <varlistentry> + <term>Portlet Specification CSS Classes</term> + <listitem> + <para> The portlet specification defines a set of CSS classes that should be available to portlets. JBoss Enterprise Portal Platform provides these classes as part of the portal skin. This allows each portal skin to define its own look and feel for these default values. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Portlet Skins</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>Portlet Skins</term> + <listitem> + <para> JBoss Enterprise Portal Platform provides a means for portlet CSS files to be loaded based on the current portal skin. This allows a portlet to provide different CSS styles to better match the current portal look and feel. Portlet skins provide a much more customizable CSS experience than just using the portlet specification CSS classes. </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> + </listitem> </varlistentry> - </variablelist> - - <note> - <title>CSS Classes</title> - - <para> - The window decorators and the default portlet specification CSS classes should be considered separate types of skinning components, but they need to be included as part of the overall portal skin. The portal skin must include these components' CSS classes or they will not be displayed correctly. + </variablelist> + </listitem> + </varlistentry> + </variablelist> + <note> + <title>CSS Classes</title> + <para> + The window decorators and the default portlet specification CSS classes should be considered separate types of skinning components. They need to be included as part of the overall portal skin otherwise they will not be displayed correctly. </para> - - <para> + <para> A portlet skin does not need to be included as part of the portal skin and can be included within the portlets web application. </para> - </note> - </section> - - <section id="sect-Reference_Guide-Skinning_the_Portal-Skin_Selection"> - <title>Skin Selection</title> - - <section id="sect-Reference_Guide-Skin_Selection-Skin_Selection_Through_the_User_Interface"> - <title>Skin Selection Through the User Interface</title> - - <para> + </note> + </section> + <section id="sect-Reference_Guide-Skinning_the_Portal-Skin_Selection"> + <title>Skin Selection</title> + <section id="sect-Reference_Guide-Skin_Selection-Skin_Selection_Through_the_User_Interface"> + <title>Skin Selection Through the User Interface</title> + <para> A skin can be selected to be displayed to the user by multiple means. The easiest way to change the skin is to select it through the user interface. An administrator can change the default skin for the portal, or a logged in user can select which skin they would prefer to be displayed. </para> - - <para> - Please see the <ulink type="http" url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platfo... Guide</ulink> for information on how to change the skin using the user interface. + <para> + Please see the <ulink url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platfo... type="http">User Guide</ulink> for information on how to change the skin using the user interface. </para> - </section> - - <section id="sect-Reference_Guide-Skin_Selection-Setting_the_Default_Skin_within_the_Configuration_Files"> - <title>Setting the Default Skin within the Configuration Files</title> - - <para> + </section> + <section id="sect-Reference_Guide-Skin_Selection-Setting_the_Default_Skin_within_the_Configuration_Files"> + <title>Setting the Default Skin within the Configuration Files</title> + <para> The default skin can also be configured using the portal configuration files. This allows the portal to have the new default skin ready for use when JBoss Enterprise Portal Platform is first started. </para> - - <para> + <para> The default skin of the portal is called <literal>Default</literal>. To change this value add a <literal>skin</literal> tag in the <literal>02portal.war/WEB-INF/conf/portal/portal/classic/portal.xml</literal> configuration file. </para> - - <para> + <para> To change the skin to <literal>MySkin</literal> you would make the following changes: </para> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default180.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - </section> - - <section id="sect-Reference_Guide-Skinning_the_Portal-Skins_in_Page_Markups"> - <title>Skins in Page Markups</title> - - <para> - A JBoss Enterprise Portal Platform skin contains CSS styles for the portal's components but also shares components that may be reused in portlets. When JBoss Enterprise Portal Platform generates a portal page markup, it inserts stylesheet links in the page's <literal>head</literal> tag. + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default180.xml" parse="text"/></programlisting> + </section> + </section> + <section id="sect-Reference_Guide-Skinning_the_Portal-Skins_in_Page_Markups"> + <title>Skins in Page Markups</title> + <para> + A JBoss Enterprise Portal Platform skin contains CSS styles for the portal&apos;s components but also shares components that may be reused in portlets. When JBoss Enterprise Portal Platform generates a portal page markup, it inserts stylesheet links in the page&apos;s <literal>head</literal> tag. </para> - - <para> + <para> There are two main types of CSS links that will appear in the <literal>head</literal> tag: a link to the portal skin CSS file and a link to the portlet skin CSS files. </para> - - <variablelist> - <varlistentry> - <term>Portal Skin</term> - - <listitem> - <para> + <variablelist> + <varlistentry> + <term>Portal Skin</term> + <listitem> + <para> The portal skin will appear as a single link to a CSS file. This link will contain contents from all the portal skin classes merged into one file. This allows the portal skin to be transferred as a single file instead of multiple smaller files. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Portlet Skin</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>Portlet Skin</term> + <listitem> + <para> Each portlet on a page may contribute its own style. The link to the portlet skin will only appear on the page if that portlet is loaded on the current page. A page may contain many portlet skin CSS links or none. </para> - </listitem> - </varlistentry> - </variablelist> - - <para> + </listitem> + </varlistentry> + </variablelist> + <para> In the code fragment below you can see the two types of links: </para> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default181.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <note> - <title>CSS Classes</title> - - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default181.xml" parse="text"/></programlisting> + <note> + <title>CSS Classes</title> + <para> Window styles and the portlet specification CSS classes are included within the portal skin. </para> - </note> - </section> - - <section id="sect-Reference_Guide-Skinning_the_Portal-The_Skin_Service"> - <title>The Skin Service</title> - - <para> + </note> + </section> + <section id="sect-Reference_Guide-Skinning_the_Portal-The_Skin_Service"> + <title>The Skin Service</title> + <para> The skin service manages the various types of skins. It is responsible for discovering and deploying skins into the portal. </para> - - <section id="sect-Reference_Guide-The_Skin_Service-Skin_configuration"> - <title>Skin configuration</title> - - <para> + <section id="sect-Reference_Guide-The_Skin_Service-Skin_configuration"> + <title>Skin configuration</title> + <para> JBoss Enterprise Portal Platform automatically discovers web archives that contain a file descriptor for skins (<filename>WEB-INF/gatein-resources.xml</filename>). This file is responsible for specifying the portal, portlet and window decorators to be deployed into the skin service. </para> - - <para> - The full schema can be found at: <ulink type="http" url="http://www.gatein.org/xml/ns/gatein_resources_1_2" />. + <para> + The full schema can be found at: <ulink url="http://www.gatein.org/xml/ns/gatein_resources_1_2" type="http"/>. </para> - - <para> + <para> Below is an example of where to define a skin (<literal>MySkin</literal>) with its CSS location, and specify some window decorator skins: </para> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default182.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - - <section id="sect-Reference_Guide-The_Skin_Service-Resource_Request_Filter"> - <title>Resource Request Filter</title> - - <para> - Because of JBoss Enterprise Portal Platform's Right-To-Left support, all CSS files need to be retrieved through a Servlet filter and the web application needs to be configured to activate this filter. This is already done for <literal>01eXoResources.war</literal> web application which contains the default skin. + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default182.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-The_Skin_Service-Resource_Request_Filter"> + <title>Resource Request Filter</title> + <para> + Because of JBoss Enterprise Portal Platform&apos;s Right-To-Left support, all CSS files need to be retrieved through a Servlet filter and the web application needs to be configured to activate this filter. This is already done for <literal>01eXoResources.war</literal> web application which contains the default skin. </para> - - <para> + <para> Any new web applications containing skinning CSS files will need to have the following added to their <filename>web.xml</filename> : </para> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default183.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <note> - <title>The <literal>display-name</literal> Element</title> - - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default183.xml" parse="text"/></programlisting> + <note> + <title>The <literal>display-name</literal> Element</title> + <para> The <literal>display-name</literal> element will also need to be specified in the <literal>web.xml</literal> for the skinning service to work properly with the web application. </para> - </note> - </section> - </section> - - <section id="sect-Reference_Guide-Skinning_the_Portal-The_Default_Skin"> - <title>The Default Skin</title> - - <para> + </note> + </section> + </section> + <section id="sect-Reference_Guide-Skinning_the_Portal-The_Default_Skin"> + <title>The Default Skin</title> + <para> The default skin for JBoss Enterprise Portal Platform is located as part of the <literal>01eXoResources.war</literal>. The main files associated with the skin are: </para> - - <variablelist> - <varlistentry> - <term>WEB-INF/gatein-resources.xml</term> - - <listitem> - <para> - For the default portal skin, this file contains definitions for the portal skin, the window decorations that this skin provides and well as defining some javascript resources which are not related to the skin. The default portal skin doesn't directly define portlet skins, these should be provided by the portlets themselves. + <variablelist> + <varlistentry> + <term>WEB-INF/gatein-resources.xml</term> + <listitem> + <para> + For the default portal skin, this file contains definitions for the portal skin, the window decorations that this skin provides and well as defining some JavaScript resources which are not related to the skin. The default portal skin doesn&apos;t directly define portlet skins, these should be provided by the portlets themselves. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>WEB-INF/web.xml</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>WEB-INF/web.xml</term> + <listitem> + <para> For the default portal skin, the <filename>web.xml</filename> of the <literal>eXoResources.war</literal> will contains a lot of information which is mostly irrelevant to the portal skinning. The area of interest in this file is the <literal>resourcerequestfilter</literal> and the fact that the <parameter>display-name</parameter> is set. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>skin/Stylesheet.css</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>skin/Stylesheet.css</term> + <listitem> + <para> This file is the main portal skin stylesheet. It is the main entry point to the CSS class definitions for the skin. The main content points of this file are: </para> - - <programlistingco> -<areaspec> - <area coords="1" id="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-uiportletapplication" /> - <area coords="2" id="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-components" /> - <area coords="3" id="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-portletthemes" /> - <area coords="4" id="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-portlet" /> - - </areaspec> -<programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_Skinning/default184.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-uiportletapplication"> - <para> + <programlistingco> + <areaspec> + <area coords="1" id="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-uiportletapplication"/> + <area coords="2" id="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-components"/> + <area coords="3" id="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-portletthemes"/> + <area coords="4" id="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-portlet"/> + </areaspec> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default184.java" parse="text"/></programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-uiportletapplication"> + <para> The skin for the main portal page. </para> - </callout> - - - - <callout arearefs="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-components"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-components"> + <para> Skins for various portal components. </para> - </callout> - - - - <callout arearefs="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-portletthemes"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-portletthemes"> + <para> Window decoration skins. </para> - </callout> - - - - <callout arearefs="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-portlet"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-Skinning_the_Portal-The_Default_Skin-portlet"> + <para> The portlet specification CSS classes. </para> - </callout> - </calloutlist> - </programlistingco> - - <para> + </callout> + </calloutlist> + </programlistingco> + <para> This method imports other CSS stylesheet files (some of which may also import further CSS stylesheets) instead of defining all the CSS classes in this one file. Splitting the CSS classes between multiple files allows new skins to reuse parts of the default skin. </para> - - <para> + <para> To reuse a CSS stylesheet from the default portal skin you would need to reference the default skin from <literal>eXoResources</literal>. For example; to include the window decorators from the default skin within a new portal skin you would need to use this import: </para> -<programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_Skinning/default185.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <note> - <title>Stylesheet Merging</title> - - <para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default185.java" parse="text"/></programlisting> + <note> + <title>Stylesheet Merging</title> + <para> When the portal skin is added to the page, it merges all the CSS stylesheets into a single file. </para> - </note> - </listitem> - </varlistentry> - </variablelist> - </section> - - <section id="sect-Reference_Guide-Skinning_the_Portal-Creating_New_Skins"> - <title>Creating New Skins</title> - - <section id="sect-Reference_Guide-Creating_New_Skins-Creating_a_New_Portal_Skin"> - <title>Creating a New Portal Skin</title> - - <para> + </note> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Skinning_the_Portal-Creating_New_Skins"> + <title>Creating New Skins</title> + <section id="sect-Reference_Guide-Creating_New_Skins-Creating_a_New_Portal_Skin"> + <title>Creating a New Portal Skin</title> + <para> New portal skins will need to be added to the portal through the skin service. Therefore, the web application which contains the skins will need to be properly configured for the skin service to discover them. This means properly configuring the <literal>ResourceRequestFilter</literal> and <filename>gatein-resources.xml</filename>. </para> - - <section id="sect-Reference_Guide-Creating_a_New_Portal_Skin-Portal_Skin_Configuration"> - <title>Portal Skin Configuration</title> - - <para> + <section id="sect-Reference_Guide-Creating_a_New_Portal_Skin-Portal_Skin_Configuration"> + <title>Portal Skin Configuration</title> + <para> The <filename>gatein-resources.xml</filename> will need to specify the new portal skin. This will include the name of the new skin, where to locate its CSS stylesheet file and whether to overwrite an existing portal theme with the same name. </para> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default186.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default186.xml" parse="text"/></programlisting> + <para> The default portal skin and window styles are defined in <filename>01eXoResources.war/WEB-INF/gatein-resources.xml</filename>. </para> - - <note> - <title>CSS</title> - - <para> + <note> + <title>CSS</title> + <para> The CSS for the portal skin needs to contain the CSS for all the window decorations and the portlet specification CSS classes. </para> - </note> - </section> - - <section id="sect-Reference_Guide-Creating_a_New_Portal_Skin-Portal_Skin_Preview_Icon"> - <title>Portal Skin Preview Icon</title> - - <para> + </note> + </section> + <section id="sect-Reference_Guide-Creating_a_New_Portal_Skin-Portal_Skin_Preview_Icon"> + <title>Portal Skin Preview Icon</title> + <para> It is possible to see a preview of what the portal will look like when selecting a new skin. This functionality relies on the current skin being updated with skin icons for all other available skins. Otherwise it will not be able to show the previews. </para> - - <para> + <para> It is recommended that preview icons of any other skins are included when creating a new portal skin and that the other skins are updated with your new portal skin preview. </para> - - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/PortalDevelopment/Skinning/portal-change-skin.png" format="PNG" scale="100" width="444" /> - </imageobject> - - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/PortalDevelopment/Skinning/portal-change-skin.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - - <para> + <mediaobject> + <imageobject role="html"> + <imagedata width="444" align="center" scale="100" fileref="images/PortalDevelopment/Skinning/portal-change-skin.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata width="444" contentwidth="150mm" align="center" fileref="images/PortalDevelopment/Skinning/portal-change-skin.png" format="PNG"/> + </imageobject> + </mediaobject> + <para> The portal skin preview icon is specified through the CSS of the portal skin. In order for the current portal skin to be able to display the preview it must specify a specific CSS class and set the icon as the background. </para> - - <para> - For a portal named <emphasis role="bold">MySkin</emphasis> in must define the following CSS class: + <para> + For a portal named <literal>MySkin</literal>, it must define the following CSS class: </para> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default187.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - In order for the default skin to display the skin icon for a new portal skin, the preview screenshot needs to be placed in: <filename>01eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/background</filename>. + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default187.xml" parse="text"/></programlisting> + <para> + In order for the default skin to display the skin icon for a new portal skin, the preview screen shot needs to be placed in: <filename>01eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/background</filename>. </para> - - <para> - The CSS stylesheet for the default portal needs to have the following updated with the preview icon CSS class. For a skin named <emphasis role="bold">MySkin</emphasis> then the following needs to be updated: <filename>01eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css</filename>. + <para> + The CSS stylesheet for the default portal needs to have the following updated with the preview icon CSS class. For a skin named <literal>MySkin</literal>, the following needs to be updated: <filename>01eXoResources.war:/skin/DefaultSkin/portal/webui/component/customization/UIChangeSkinForm/Stylesheet.css</filename>. </para> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default188.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - </section> - - <section id="sect-Reference_Guide-Creating_New_Skins-Creating_a_New_Window_Style"> - <title>Creating a New Window Style</title> - - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default188.xml" parse="text"/></programlisting> + </section> + </section> + <section id="sect-Reference_Guide-Creating_New_Skins-Creating_a_New_Window_Style"> + <title>Creating a New Window Style</title> + <para> Window styles are the CSS applied to window decorations. An administrator can decide which style of decoration should go around the window when they add a new application or gadget to a page. </para> - - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/PortalDevelopment/Skinning/windowStyles.png" format="PNG" scale="100" width="444" /> - </imageobject> - - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/PortalDevelopment/Skinning/windowStyles.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - - <section id="sect-Reference_Guide-Creating_a_New_Window_Style-Window_Style_Configuration"> - <title>Window Style Configuration</title> - - <para> + <mediaobject> + <imageobject role="html"> + <imagedata width="444" align="center" scale="100" fileref="images/PortalDevelopment/Skinning/windowStyles.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata width="444" contentwidth="150mm" align="center" fileref="images/PortalDevelopment/Skinning/windowStyles.png" format="PNG"/> + </imageobject> + </mediaobject> + <section id="sect-Reference_Guide-Creating_a_New_Window_Style-Window_Style_Configuration"> + <title>Window Style Configuration</title> + <para> Window Styles are defined within a <filename>gatein-resources.xml</filename> file which is used by the skin service to deploy the window style into the portal. Window styles can belong in a window style category. This category and the window styles will need to be specified in resources file. </para> - - <para> + <para> The following <filename>gatein-resources.xml</filename> fragment will add <literal>MyThemeBlue</literal> and <literal>MyThemeRed</literal> to the <literal>MyTheme</literal> category. </para> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default189.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default189.xml" parse="text"/></programlisting> + <para> The windows style configuration for the default skin is configured in: <filename>01eXoResources.war/WEB-INF/gatein-resources.xml</filename>. </para> - - <note> - <title>Window Styles and Portal Skins</title> - - <para> + <note> + <title>Window Styles and Portal Skins</title> + <para> When a window style is defined in <filename>gatein-resources.xml</filename> file, it will be available to all portlets regardless of whether the current portal skin supports the window decorator or not. </para> - - <para> + <para> It is recommended that when a new window decorator is added that it be added to all portal skins or that all portal skins share a common stylesheet for window decorators. </para> - </note> - </section> - - <section id="sect-Reference_Guide-Creating_a_New_Window_Style-Window_Style_CSS"> - <title>Window Style CSS</title> - - <para> + </note> + </section> + <section id="sect-Reference_Guide-Creating_a_New_Window_Style-Window_Style_CSS"> + <title>Window Style CSS</title> + <para> In order for the skin service to display the window decorators, it must have CSS classes specifically named in relation to the window style name. The service will try and display CSS based on this naming convention. The CSS class must be included as part of the current portal skin for the window decorators to be displayed. </para> - - <para> + <para> The location of the window decorator CSS classes for the default portal theme is located at: <filename>01eXoResources.war/skin/PortletThemes/Stylesheet.css</filename>. </para> - - <para></para> - - <para> + <para/> + <para> Create the CSS file: </para> -<programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_Skinning/default190.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - - <section id="sect-Reference_Guide-Creating_a_New_Window_Style-How_to_Set_the_Default_Window_Style"> - <title>How to Set the Default Window Style</title> - - <para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default190.java" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Creating_a_New_Window_Style-How_to_Set_the_Default_Window_Style"> + <title>How to Set the Default Window Style</title> + <para> To set the default window style to be used for a portal you will need to specify the CSS classes for a theme called <literal>DefaultTheme</literal>. </para> - - <note> - <title>DefaultTheme</title> - - <para> + <note> + <para> You do not need to specify the <literal>DefaultTheme</literal> in <filename>gatein-resources.xml</filename>. </para> - </note> - </section> - </section> - - <section id="sect-Reference_Guide-Creating_New_Skins-How_to_Create_New_Portlet_Skins"> - <title>How to Create New Portlet Skins</title> - - <para> + </note> + </section> + </section> + <section id="sect-Reference_Guide-Creating_New_Skins-How_to_Create_New_Portlet_Skins"> + <title>How to Create New Portlet Skins</title> + <para> Portlets often require additional styles that may not be defined by the portal skin. JBoss Enterprise Portal Platform allows portlets to define additional stylesheets for each portlet and will append the corresponding <literal>link</literal> tags to the <literal>head</literal>. </para> - - <para> + <para> The link ID will be of the form <parameter>{portletAppName}{PortletName}</parameter>. </para> - - <para> - For example: <literal>ContentPortlet</literal> in <literal>content.war</literal>, will give <parameter>id="content<literal>ContentPortlet"</literal></parameter>. + <para> + For example: <literal>ContentPortlet</literal> in <literal>content.war</literal>, will give <parameter>id=&quot;content<literal>ContentPortlet&quot;</literal></parameter>. </para> - - <para> + <para> To define a new CSS file to include whenever a portlet is available on a portal page, the following fragment needs to be added in <filename>gatein-resources.xml</filename>. </para> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default191.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default191.xml" parse="text"/></programlisting> + <para> This will load the <literal>DefaultStylesheet.css</literal> when the Default skin is used and the <literal>OtherSkinStylesheet.css</literal> when the <literal>OtherSkin</literal> is used. </para> - - <note> - <title>Updating Portlet Skins</title> - - <para> + <note> + <title>Updating Portlet Skins</title> + <para> If the current portal skin is not defined as one of the supported skins, then the portlet CSS class will not be loaded. It is recommended that portlet skins are updated whenever a new portal skin is created. </para> - </note> - - <section id="sect-Reference_Guide-How_to_Create_New_Portlet_Skins-Define_a_Custom_CSS_File"> - <title>Define a Custom CSS File</title> - - <para> + </note> + <section id="sect-Reference_Guide-How_to_Create_New_Portlet_Skins-Define_a_Custom_CSS_File"> + <title>Define a Custom CSS File</title> + <para> JBoss Enterprise Portal Platform &VX; does not serve CSS files directly, but uses a filter as well as a skin service in order to: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Cache the CSS files. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Merge them into one file if possible. This will be discussed further in <xref linkend="sect-Reference_Guide-Tips_and_Tricks-Easier_CSS_Debugging"/>. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Add support for Right-To-Left (RTL) languages. This is discussed in more detail in <xref linkend="sect-Reference_Guide-Right_To_Left_RTL_Framework-Stylesheet"/>. </para> - </listitem> - </itemizedlist> - - <para> + </listitem> + </itemizedlist> + <para> This causes JBoss Enterprise Portal Platform to create non-functioning a CSS-link in html-src-code. </para> - - <procedure> - <title>To Resolve This:</title> - - <step> - <para> + <procedure> + <title>To Resolve This:</title> + <step> + <para> Add the following files to the custom portlet application: </para> - - <variablelist> - <title></title> - - <varlistentry> - <term><filename>WEB-INF/gatein-resources.xml</filename>:</term> - - <listitem> -<programlisting language="XML" role="XML"><![CDATA[<portlet-skin> + <variablelist> + <title/> + <varlistentry> + <term><filename>WEB-INF/gatein-resources.xml</filename>:</term> + <listitem> + <programlisting language="XML" role="XML"><![CDATA[<portlet-skin> <application-name>custom</application-name> <portlet-name>test</portlet-name> <skin-name>Default</skin-name> <css-path>/css/main.css</css-path> </portlet-skin> ]]></programlisting> - <note> - <title>Note:</title> - - <itemizedlist> - <listitem> - <para> + <note> + <title>Note:</title> + <itemizedlist> + <listitem> + <para> The value of the <parameter>application-name</parameter> element needs to match the value of the <parameter>display-name</parameter> element in <filename>web.xml</filename>. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The value of the <parameter>portlet-name</parameter> element needs to match the value of the <parameter>portlet-name</parameter> element in <filename>portlet.xml</filename>. </para> - </listitem> - </itemizedlist> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>WEB-INF/web.xml</filename>:</term> - - <listitem> -<programlisting language="XML" role="XML"><![CDATA[<display-name>custom</display-name> + </listitem> + </itemizedlist> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>WEB-INF/web.xml</filename>:</term> + <listitem> + <programlisting language="XML" role="XML"><![CDATA[<display-name>custom</display-name> <filter> <filter-name>ResourceRequestFilter</filter-name> @@ -581,47 +458,41 @@ <url-pattern>/*</url-pattern> </filter-mapping> ]]></programlisting> - <note> - <title>Note:</title> - - <itemizedlist> - <listitem> - <para> + <note> + <title>Note:</title> + <itemizedlist> + <listitem> + <para> The value of the <parameter>display-name</parameter> element needs to match the value of the <parameter>application-name</parameter> element in <filename>gatein-resources.xml</filename>. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The <literal>ResourceRequestFilter</literal> needs to be added to the custom portlet application for proper CSS file handling within the Portal container. </para> - </listitem> - </itemizedlist> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>WEB-INF/portlet.xml</filename>:</term> - - <listitem> -<programlisting language="XML" role="XML"><![CDATA[<portlet-name>test</portlet-name> + </listitem> + </itemizedlist> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>WEB-INF/portlet.xml</filename>:</term> + <listitem> + <programlisting language="XML" role="XML"><![CDATA[<portlet-name>test</portlet-name> ]]></programlisting> - <note> - <title>Note:</title> - - <para> + <note> + <title>Note:</title> + <para> The value of the <parameter>portlet-name</parameter> element needs to match the value of the <parameter>portlet-name</parameter> element in <filename>gatein-resources.xml</filename>. </para> - </note> - </listitem> - </varlistentry> - </variablelist> - - <para> + </note> + </listitem> + </varlistentry> + </variablelist> + <para> The final portlet application will be structured as illustrated below: </para> -<programlisting>custom.war + <programlisting>custom.war ├── css │ └── main.css └── WEB-INF @@ -631,136 +502,110 @@ ├── portlet.xml └── web.xml </programlisting> - </step> - </procedure> - </section> - - <section id="sect-Reference_Guide-How_to_Create_New_Portlet_Skins-Change_Portlet_Icons"> - <title>Change Portlet Icons</title> - - <para> + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-How_to_Create_New_Portlet_Skins-Change_Portlet_Icons"> + <title>Change Portlet Icons</title> + <para> Each portlet can be registered by a unique icon in the portlet registry or page editor. This icon can be changed by adding an image to the directory of the portlet web application: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <filename>skin/DefaultSkin/portletIcons/<replaceable>portlet_name</replaceable>.png </filename>. </para> - </listitem> - </itemizedlist> - - <para> + </listitem> + </itemizedlist> + <para> To be used correctly the icon must be named after the portlet. </para> - - <para> + <para> For example; the icon for an account portlet named <literal>AccountPortlet</literal> would be located at: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <filename>skin/DefaultSkin/portletIcons/AccountPortlet.png</filename> </para> - </listitem> - </itemizedlist> - - <note> - <title>Portlet Icons Directory</title> - - <para> + </listitem> + </itemizedlist> + <note> + <title>Portlet Icons Directory</title> + <para> You must use <literal>skin/DefaultSkin/portletIcons/</literal> for the directory to store the portlet icon regardless of what skin is going to be used. </para> - </note> - </section> - </section> - - <section id="sect-Reference_Guide-Creating_New_Skins-Create_New_Portlet_Specification_CSS_Classes"> - <title>Create New Portlet Specification CSS Classes</title> - - <para> + </note> + </section> + </section> + <section id="sect-Reference_Guide-Creating_New_Skins-Create_New_Portlet_Specification_CSS_Classes"> + <title>Create New Portlet Specification CSS Classes</title> + <para> The portlet specification defines a set of default CSS classes that should be available for portlets. These classes are included as part of the portal skin. Please see the portlet specification for a list of the default classes that should be available. </para> - - <para> + <para> For the default portal skin, the portlet specification CSS classes are defined in: <filename>01eXoResources.war/skin/Portlet/Stylesheet.css</filename>. </para> - </section> - </section> - - <section id="sect-Reference_Guide-Skinning_the_Portal-Tips_and_Tricks"> - <title>Tips and Tricks</title> - - <section id="sect-Reference_Guide-Tips_and_Tricks-Easier_CSS_Debugging"> - <title>Easier CSS Debugging</title> - - <para> + </section> + </section> + <section id="sect-Reference_Guide-Skinning_the_Portal-Tips_and_Tricks"> + <title>Tips and Tricks</title> + <section id="sect-Reference_Guide-Tips_and_Tricks-Easier_CSS_Debugging"> + <title>Easier CSS Debugging</title> + <para> By default, CSS files are cached and their imports are merged into a single CSS file at the server side. This reduces the number of HTTP requests from the browser to the server. </para> - - <para> + <para> The optimization code is quite simple as all the CSS files are parsed at the server start and all the <literal>@import</literal> and <literal>url(...)</literal> references are rewritten to support a single flat file. The result is stored in a cache directly used from the <literal>ResourceRequestFilter</literal>. </para> - - <para> - Although the optimization is useful for a production environment, it may be easier to deactivate this optimization while debugging stylesheets. Set the java system property <literal>exo.product.developing</literal> to <literal>true</literal> to disable the optimization. + <para> + Although the optimization is useful for a production environment, it may be easier to deactivate this optimization while debugging stylesheets. Set the Java system property <literal>exo.product.developing</literal> to <literal>true</literal> to disable the optimization. </para> - - <para> + <para> For example, the property can be passed as a JVM parameter with <literal>-D</literal> option when running JBoss Enterprise Portal Platform. </para> -<programlisting><command>sh jboss-as/bin/run.sh -Dexo.product.developing=true</command></programlisting> -<!-- <programlisting language="Java" role="Java"><xi:include parse="text" href="../../extras/PortalDevelopment_Skinning/default192.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> --> - <warning> - <para> + <programlisting><command>sh jboss-as/bin/run.sh -Dexo.product.developing=true</command></programlisting> +<!-- <programlisting language="Java" role="Java"><xi:include parse="text" href="../../extras/PortalDevelopment_Skinning/default192.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> --> <warning> + <para> This option may cause display bugs in some browsers. </para> - </warning> - </section> - - <section id="sect-Reference_Guide-Tips_and_Tricks-Some_CSS_Techniques"> - <title>Some CSS Techniques</title> - - <para> + </warning> + </section> + <section id="sect-Reference_Guide-Tips_and_Tricks-Some_CSS_Techniques"> + <title>Some CSS Techniques</title> + <para> It is recommended that users have some experience with CSS before studying JBoss Enterprise Portal Platform CSS. </para> - - <para> + <para> JBoss Enterprise Portal Platform relies heavily on CSS to create the layout and effects for the UI. Some common techniques for customizing JBoss Enterprise Portal Platform CSS are explained below. </para> - - <section id="sect-Reference_Guide-Some_CSS_Techniques-Border_Pattern"> - <title>Border Pattern</title> - - <para> + <section id="sect-Reference_Guide-Some_CSS_Techniques-Border_Pattern"> + <title>Border Pattern</title> + <para> The decorator is a pattern to create a contour or a curve around an area. In order to achieve this effect you need to create nine cells. The <literal>BODY</literal> is the central area that you want to decorate. The other eight cells are distributed around the <literal>BODY</literal> cell. You can use the width, height and background image properties to achieve any decoration effect that you want. </para> - - <mediaobject> - <imageobject> - <imagedata fileref="images/PortalDevelopment/Skinning/decoratorPattern.png" format="PNG" width="418" /> - </imageobject> - </mediaobject> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default193.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - - <section id="sect-Reference_Guide-Some_CSS_Techniques-Left_Margin_Left_Pattern"> - <title>Left Margin Left Pattern</title> - - <para> + <mediaobject> + <imageobject> + <imagedata width="418" fileref="images/PortalDevelopment/Skinning/decoratorPattern.png" format="PNG"/> + </imageobject> + </mediaobject> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default193.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Some_CSS_Techniques-Left_Margin_Left_Pattern"> + <title>Left Margin Left Pattern</title> + <para> Left margin left pattern is a technique to create two blocks side by side. The left block will have a fixed size and the right block will take the rest of the available space. When the user resizes the browser the added or removed space will be taken from the right block. </para> - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/PortalDevelopment/Skinning/leftMarginPattern.png" format="PNG" align="center"/> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/PortalDevelopment/Skinning/leftMarginPattern.png" format="PNG" align="center" width="100mm"/> - </imageobject> - </mediaobject> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_Skinning/default194.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - </section> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/PortalDevelopment/Skinning/leftMarginPattern.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata width="100mm" align="center" fileref="images/PortalDevelopment/Skinning/leftMarginPattern.png" format="PNG"/> + </imageobject> + </mediaobject> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_Skinning/default194.xml" parse="text"/></programlisting> </section> - </chapter> + </section> + </section> +</chapter> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/XMLResourceBundles.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/XMLResourceBundles.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/XMLResourceBundles.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,47 +1,40 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-XML_Resources_Bundles"> - <title>XML Resources Bundles</title> - <section id="sect-Reference_Guide-XML_Resources_Bundles-Overview"> - <title>Overview</title> - <para> - Resource bundles are usually stored in property files. However, as property files are plain files, issues with the encoding of the file may arise. The XML resource bundle format has been developed to provide an alternative to property files. - </para> - <itemizedlist> - <listitem> - <para> - The XML format declares the encoding of the file. This avoids use of the <literal>native2ASCII</literal> program which can interfere with encoding. - </para> - - </listitem> - <listitem> - <para> - Property files generally use <literal>ISO 8859-1</literal> character encoding which does not cover the full unicode charset. As a result, languages such as Arabic would not be natively supported. - </para> - - </listitem> - <listitem> - <para> - Tooling for XML files is better supported than the tooling for Java property files and thus the XML editor copes well with the file encoding. - </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide-XML_Resources_Bundles-XML_format"> - <title>XML format</title> - <para> - The XML format is very simple and has been developed based on the 'Don't Repeat Yourself' (DRY) principle. Usually resource bundle keys are hierarchically defined and we can leverage the hierarchic nature of the XML for that purpose. Here is an example of turning a property file into an XML resource bundle file: - </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_XMLResourceBundles/default195.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting>UIAccountForm.tab.label.AccountInputSet = ... + <title>XML Resources Bundles</title> + <section id="sect-Reference_Guide-XML_Resources_Bundles-Overview"> + <title>Overview</title> + <para> + Resource bundles are usually stored in property files. However, as property files are plain files, issues with the encoding of the file may arise. The XML resource bundle format has been developed to provide an alternative to property files. + </para> + <itemizedlist> + <listitem> + <para> + The XML format declares the encoding of the file. This avoids use of the <literal>native2ASCII</literal> program which can interfere with encoding. + </para> + </listitem> + <listitem> + <para> + Property files generally use <literal>ISO 8859-1</literal> character encoding which does not cover the full unicode charset. As a result, languages such as Arabic would not be natively supported. + </para> + </listitem> + <listitem> + <para> + Tooling for XML files is better supported than the tooling for Java property files and thus the XML editor copes well with the file encoding. + </para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-XML_Resources_Bundles-XML_format"> + <title>XML format</title> + <para> + The XML format is very simple and has been developed based on the &apos;do not Repeat Yourself&apos; (DRY) principle. Usually resource bundle keys are hierarchically defined and we can leverage the hierarchic nature of the XML for that purpose. Here is an example of turning a property file into an XML resource bundle file: + </para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_XMLResourceBundles/default195.java" parse="text"/></programlisting> +<!-- <programlisting>UIAccountForm.tab.label.AccountInputSet = ... UIAccountForm.tab.label.UIUserProfileInputSet = ... UIAccountForm.label.Profile = ... UIAccountForm.label.HomeInfo= ... @@ -50,9 +43,8 @@ UIAccountForm.label.Confirmpassword= ... UIAccountForm.label.email= ... UIAccountForm.action.Reset= ... -</programlisting> --> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_XMLResourceBundles/default196.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +</programlisting> --> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_XMLResourceBundles/default196.xml" parse="text"/></programlisting> +<!-- <programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <bundle> <UIAccountForm> <tab> @@ -73,20 +65,14 @@ <Reset>...</Reset> </action> </UIAccountForm> -</bundle>]]></programlisting> --> - </section> - - <section id="sect-Reference_Guide-XML_Resources_Bundles-Portal_Support"> - <title>Portal Support</title> - <para> - In order to be loaded by the portal at runtime (actually the resource bundle service), the name of the file must be the same as a property file and it must use the <emphasis role="bold">.xml</emphasis> suffix. - </para> - <para> - For example; for the Account Portlet to be displayed in Arabic, the resource bundle would be <emphasis role="bold"> AccountPortlet_ar.xml</emphasis> rather than <emphasis role="bold">AccountPortlet_ar.properties</emphasis>. - </para> - - </section> - - +</bundle>]]></programlisting> --> </section> + <section id="sect-Reference_Guide-XML_Resources_Bundles-Portal_Support"> + <title>Portal Support</title> + <para> + In order to be loaded by the portal at runtime (actually the resource bundle service), the name of the file must be the same as a property file and it must use the <emphasis role="bold">.xml</emphasis> suffix. + </para> + <para> + For example; for the Account Portlet to be displayed in Arabic, the resource bundle would be <emphasis role="bold"> AccountPortlet_ar.xml</emphasis> rather than <emphasis role="bold">AccountPortlet_ar.properties</emphasis>. + </para> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -40,10 +40,10 @@ &lt;/portlet-app&gt; </programlisting> <para> - The path to the global <filename>portlet.xml</filename> is the value of <literal>gatein.portlet.config</literal> in the <filename>configuration.properties.xml</filename> file. By default The file path is <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/conf/gatein/portlet.xml</filename> + The path to the global <filename>portlet.xml</filename> is the value of <literal>gatein.portlet.config</literal> in the <filename>configuration.properties.xml</filename> file. By default The file path is <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/conf/gatein/portlet.xml</filename> </para> <para> - <emphasis role="bold">For JBoss</emphasis>: The file path is <filename><replaceable>EPP_HOME</replaceable>/server/default/conf/gatein/portlet.xml</filename>. + <emphasis role="bold">For JBoss</emphasis>: The file path is <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/default/conf/gatein/portlet.xml</filename>. </para> <section id="sect-Reference_Guide-Shared_portlet.xml-Global_Metadata_Elements"> <title>Global Metadata Elements</title> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -65,7 +65,7 @@ <term>DEFAULT</term> <listitem> <para> - Directs the bridge to first delegate the render only if an Exception is thrown then render the view based on its own logic. If the configuration parameter is not present or has an invalid value the bridge renders using default behavior as it would if DEFAULT was set. + Directs the bridge to first delegate the render. If an exception is thrown, the bridge renders the view based on its own logic. If the configuration parameter is not present or has an invalid value the bridge renders using default behavior as it would if DEFAULT was set. </para> </listitem> </varlistentry> @@ -112,8 +112,7 @@ </para> </note> <para> - The <literal>org.ajax4jsf.RESOURCE_URI_PREFIX</literal> configuration cross-references the path to your scripts below. These settings are required for <application>RichFaces</application> using the &quot;<parameter>NONE</parameter>&quot; strategy. - </para> + The <literal>org.ajax4jsf.RESOURCE_URI_PREFIX</literal> configuration cross-references the path to your scripts below. These settings are required for <application>RichFaces</application> using the &quot;<parameter>NONE</parameter>&quot; strategy. Replace all <replaceable>richFacesPortlet</replaceable> text in the example with the actual name of the portlet resource. </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default205.xml" parse="text"/></programlisting> <para> <application>Seam</application> automatically configures your Ajax4JSF Filter, so if you are running a <application>Seam</application> portlet, you do not need the following Filter configuration (however, you do need the <literal>RESOURCE_URI_PREFIX</literal> no matter what). @@ -121,7 +120,7 @@ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default206.xml" parse="text"/></programlisting> </section> <section id="sect-Reference_Guide-RichFaces_Setup_and_Configuration_Options-Configuration_needed_for_Richfaces_to_work_with_WSRP_and_PortletBridge"> -<!-- Content added from JBEPP-708 and JBQA-3999 --> <title>Configuration needed for Richfaces to work with WSRP and PortletBridge</title> +<!-- Content added from JBEPP-708 and JBQA-3999 --> <title>Configure RichFaces to work with WSRP and PortletBridge</title> <para> Use the following settings in <filename>web.xml</filename> when running WSRP portlets: </para> @@ -140,14 +139,11 @@ &lt;/context-param&gt; </programlisting> <para> - The styles below must also be manually added to the facelets template header in the <filename><replaceable>EPP_HOME</replaceable>/portletbridge/examples/richFacesPortlet-<replaceable>&lt;VERSION&gt;</replaceable>.war:richFacesPortlet.war/templates/main.xhtml</filename> file. + The styles below must also be manually added to the facelets template header in the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/portletbridge/examples/richFacesPortlet-<replaceable>VERSION</replaceable>.war:richFacesPortlet.war/templates/main.xhtml</filename> file. </para> - <programlisting language="XML" role="XML">&lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; - href=&quot;/richFacesPortlet/faces/rfResorg/richfaces/renderkit/html/css/basic_both.xcss&quot;/&gt; - &lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; - href=&quot;/richFacesPortlet/faces/rfResorg/richfaces/renderkit/html/css/extended_both.xcss&quot;/&gt; - &lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; - href=&quot;/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss&quot;/&gt; + <programlisting language="XML" role="XML">&lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;/richFacesPortlet/faces/rfRes/org/richfaces/renderkit/html/css/basic_both.xcss&quot;/&gt; +&lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;/richFacesPortlet/faces/rfRes/org/richfaces/renderkit/html/css/extended_both.xcss&quot;/&gt; +&lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss&quot;/&gt; </programlisting> <para> The table below outlines the current status of RichFaces features when used in both local and remote portlets. @@ -627,7 +623,7 @@ The bridge maps a render parameter to a backing bean using settings in your <filename>faces-config.xml</filename> and <filename>portlet.xml</filename>. </para> <para> - A clear and working example can be found in the Seam Booking Demo portlet. <ulink url="http://anonsvn.jboss.org/repos/portletbridge/tags/2.2.0.GA.EPP5... + A clear and working example can be found in the Seam Booking Demo portlet. <ulink url="http://anonsvn.jboss.org/repos/portletbridge/tags/2.3.0.CP01.EP... </para> <para> You must define the following <emphasis>init params</emphasis> in your <filename>portlet.xml</filename>. @@ -655,7 +651,7 @@ We have setup a few examples to show you how to use <literal>EL</literal> and a simple bean that will allow you to use the portlet resource serving mechanism within a JSF portlet. </para> <para> - In <ulink url="http://anonsvn.jboss.org/repos/portletbridge/tags/2.0.0.CR1/exa...;, you can see a very simple implementation of a Map object that uses the bridge to get and encode a resource url served from the portlets web application. + In <ulink url="http://anonsvn.jboss.org/repos/portletbridge/tags/2.3.0.CP01.EP...;, you can see a very simple implementation of a Map object that uses the bridge to get and encode a resource URL served from the portlet application. </para> <para> So, when you have the normal &quot;<filename>/images</filename>&quot;, &quot;<filename>/styles</filename>&quot; and other resource folders in your web application, you can use the following <literal>EL</literal> expression to serve them in your JSF application. Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,174 +1,156 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge"> - <title>Getting started with JBoss Portlet Bridge</title> - <para> - JBoss Portlet Bridge not only gives you the ability to run JSF web applications in a portlet, but also gives you the benefit of running supported JBoss frameworks like <application>Seam</application> and <application>RichFaces</application>. - </para> - <section id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Whats_New_in_2.0"> - <title>What's New in 2.0?</title> - <section id="sect-Reference_Guide-Whats_New_in_2.0-Eventing"> - <title>Eventing</title> - <para> - The bridge considers a portlet event a model event. The event is targeted to the applications data model, not its view. - </para> - <para> - As JSF events primarily concern its view, the bridge processes the portlet events manually, however provisions are made to ensure that any model changes resulting from processing the event are updated in the view. - </para> - <para> - Since event payloads are arbitrarily complex, the manual processing of the data, though managed by the bridge, is left to the (portlet) application to support. - </para> - <para> - See <xref linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events" /> for details and examples. - </para> - - </section> - - <section id="sect-Reference_Guide-Whats_New_in_2.0-Portlet_Served_Resources"> - <title>Portlet Served Resources</title> - <para> - The bridge deals with portlet served resources in one of two ways: - </para> - <para> - If the request is for a non-JSF resource, the bridge handles the request by acquiring a request dispatcher and forwarding the request to the named resource. - </para> - <para> - If the request is for a JSF resource, the bridge runs the full JSF life-cycle ensuring that data is processed and the resource (markup) is rendered. - </para> - <para> - See <xref linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Serving_Your_JSF_Resources_in_a_Portlet" /> for details and examples. - </para> - - </section> - - <section id="sect-Reference_Guide-Whats_New_in_2.0-Public_Render_Parameters"> - <title>Public Render Parameters</title> - <para> - The bridge automates the processing of public render parameters. - </para> - <para> - A public render parameter can be mapped to an object's accessor (<literal>get</literal>/<literal>set</literal> method) designed to handle a String representation of the value via a <application>Faces</application> <literal>ValueExpression</literal>. - </para> - <para> - When a new public render parameter value is received in a request, the bridge sets the value by calling the <literal>ValueExpression</literal>'s <parameter>setValue()</parameter>. - </para> - <para> - At the end of a request, if the current value of any mapped public render parameter doesn't match the current incoming value, the bridge sets the new value in an outgoing public render parameter (if feasible in the given phase). - </para> - <para> - See <xref linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters" /> for details and examples. - </para> - - </section> - - - </section> - - <section id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Bridge_Frameworks_and_Extensions"> - <title>Bridge Frameworks and Extensions</title> - <para> - The JBoss Portlet Bridge currently supports JBoss Enterprise Portal Platform, <application>GateIn</application>, <application>JSF 1.2</application>, <application>JBoss Seam</application>, and <application>JBoss Richfaces</application>. There are configurations that apply to supporting each framework. See section <xref linkend="sect-Reference_Guide-Bridge_Configuration" /> for instructions. - </para> - <para> - The JBoss Portlet Bridge project is also actively developing extensions called "<emphasis role="bold">Bridgelets</emphasis>". - </para> - <para> - In this release it was decided to bring all available bridgelets into the impl code base since they are critical in most JSF portlet applications. A single line of configuration utilizes these features. - </para> - <section id="sect-Reference_Guide-Bridge_Frameworks_and_Extensions-Seam_Bridgelets"> - <title>Seam Bridgelets</title> - <para> - For example, the <literal>PortalIdentity</literal> <application>Seam</application> component allows you to instantly have Single Sign-On (SSO) between <application>Seam</application> and <application>GateIn</application> or <application>JBoss Enterprise Portal Platform</application>. - </para> - <para> - This extension is configured in your <application>Seam</application> application's <filename>components.xml</filename> file as follows. - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_GettingStarted/default218.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-Bridge_Frameworks_and_Extensions-RichFaces_Bridgelets"> - <title>RichFaces Bridgelets</title> - <para> - <application>Richfaces</application> does not account for multiple components on the same portal page by default. This following <filename>web.xml</filename> renders all <application>RichFaces</application> component javascript portal-friendly. - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_GettingStarted/default219.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - - </section> - - <section id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Before_You_Start"> - <title>Before You Start</title> - <para> - The embedded version in the JBoss Enterprise Portal Platform is made to be compatible with the JSF implementation, portal and application server that compose the product. You will find the binaries embedded in <filename>jboss-epp-&lt;VERSION&gt;/portletbridge</filename> - </para> - <para> - You can run a provided archetype and deploy the generated <literal>war</literal> or <literal>ear</literal> in a few easy steps. <!-- (See <xref linkend="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes" />) --> - </para> - - </section> - - <!-- Section removed as per feedback from Prabhat Jha + <title>Getting started with JBoss Portlet Bridge</title> + <para> + JBoss Portlet Bridge not only gives you the ability to run JSF web applications in a portlet, but also gives you the benefit of running supported JBoss frameworks like <application>Seam</application> and <application>RichFaces</application>. + </para> + <section id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Whats_New_in_2.0"> + <title>What&apos;s New in 2.0?</title> + <section id="sect-Reference_Guide-Whats_New_in_2.0-Eventing"> + <title>Eventing</title> + <para> + The bridge considers a portlet event a model event. The event is targeted to the applications data model, not its view. + </para> + <para> + As JSF events primarily concern its view, the bridge processes the portlet events manually, however provisions are made to ensure that any model changes resulting from processing the event are updated in the view. + </para> + <para> + Since event payloads are arbitrarily complex, the manual processing of the data, though managed by the bridge, is left to the (portlet) application to support. + </para> + <para> + See <xref linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events"/> for details and examples. + </para> + </section> + <section id="sect-Reference_Guide-Whats_New_in_2.0-Portlet_Served_Resources"> + <title>Portlet Served Resources</title> + <para> + The bridge deals with portlet served resources in one of two ways: + </para> + <para> + If the request is for a non-JSF resource, the bridge handles the request by acquiring a request dispatcher and forwarding the request to the named resource. + </para> + <para> + If the request is for a JSF resource, the bridge runs the full JSF life-cycle ensuring that data is processed and the resource (markup) is rendered. + </para> + <para> + See <xref linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Serving_Your_JSF_Resources_in_a_Portlet"/> for details and examples. + </para> + </section> + <section id="sect-Reference_Guide-Whats_New_in_2.0-Public_Render_Parameters"> + <title>Public Render Parameters</title> + <para> + The bridge automates the processing of public render parameters. + </para> + <para> + A public render parameter can be mapped to an object&apos;s accessor (<literal>get</literal>/<literal>set</literal> method) designed to handle a String representation of the value via a <application>Faces</application> <literal>ValueExpression</literal>. + </para> + <para> + When a new public render parameter value is received in a request, the bridge sets the value by calling the <literal>ValueExpression</literal>&apos;s <parameter>setValue()</parameter>. + </para> + <para> + At the end of a request, if the current value of any mapped public render parameter doesn&apos;t match the current incoming value, the bridge sets the new value in an outgoing public render parameter (if feasible in the given phase). + </para> + <para> + See <xref linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters"/> for details and examples. + </para> + </section> + </section> + <section id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Bridge_Frameworks_and_Extensions"> + <title>Bridge Frameworks and Extensions</title> + <para> + The JBoss Portlet Bridge currently supports <application>JBoss Enterprise Portal Platform</application>, <application>GateIn</application>, <application>JSF 1.2</application>, <application>JBoss Seam</application>, and <application>JBoss Richfaces</application>. There are configurations that apply to supporting each framework. See section <xref linkend="sect-Reference_Guide-Bridge_Configuration"/> for instructions. + </para> + <para> + The JBoss Portlet Bridge project is also actively developing extensions called &quot;<emphasis role="bold">Bridgelets</emphasis>&quot;. + </para> + <para> + In this release it was decided to bring all available bridgelets into the impl code base since they are critical in most JSF portlet applications. A single line of configuration utilizes these features. + </para> + <section id="sect-Reference_Guide-Bridge_Frameworks_and_Extensions-Seam_Bridgelets"> + <title>Seam Bridgelets</title> + <para> + For example, the <literal>PortalIdentity</literal> <application>Seam</application> component allows you to instantly have Single Sign-On (SSO) between <application>Seam</application> and <application>GateIn</application> or <application>JBoss Enterprise Portal Platform</application>. + </para> + <para> + This extension is configured in your <application>Seam</application> application&apos;s <filename>components.xml</filename> file as follows. + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_GettingStarted/default218.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Bridge_Frameworks_and_Extensions-RichFaces_Bridgelets"> + <title>RichFaces Bridgelets</title> + <para> + <application>Richfaces</application> does not account for multiple components on the same portal page by default. This following <filename>web.xml</filename> renders all <application>RichFaces</application> component javascript portal-friendly. + </para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_GettingStarted/default219.xml" parse="text"/></programlisting> + </section> + </section> + <section id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Before_You_Start"> + <title>Before You Start</title> + <para> + The embedded version in the JBoss Enterprise Portal Platform is made to be compatible with the JSF implementation, portal and application server that compose the product. You will find the binaries embedded in <filename>jboss-epp-<replaceable>VERSION</replaceable>/portletbridge</filename> + </para> + <para> + You can run a provided archetype and deploy the generated <literal>war</literal> or <literal>ear</literal> in a few easy steps. <!-- (See <xref linkend="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes" />) --> + </para> + </section> +<!-- Section removed as per feedback from Prabhat Jha <section id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes"> - <title>Maven Archetypes</title> - <para> - This product utilizes <ulink url="http://maven.apache.org/guides/introduction/introduction-to-arc... archetypes</ulink> which allow you get up and running with different flavors of the bridge quickly. - </para> - <table frame="all" id="tabl-Reference_Guide-Maven_Archetypes-Available_Archetypes"> - <title>Available Archetypes</title> - <tgroup align="left" cols="5" colsep="1" rowsep="1"> - <colspec colname="c1"></colspec> - <colspec colname="c2"></colspec> - <colspec colname="c3"></colspec> - <colspec colname="c5" colnum="5"></colspec> - <thead> - <row> - <entry align="center"> - Archetype - </entry> - <entry align="center" nameend="c5" namest="c2"> - Command - </entry> - </row> - </thead> - <tbody> - <row class="table-odd" style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;"> - <entry align="left"> - JSF 1.2 Basic - </entry> - <entry align="left" nameend="c5" namest="c2"> - + <title>Maven Archetypes</title> + <para> + This product utilizes <ulink url="http://maven.apache.org/guides/introduction/introduction-to-arc... archetypes</ulink> which allow you get up and running with different flavors of the bridge quickly. + </para> + <table frame="all" id="tabl-Reference_Guide-Maven_Archetypes-Available_Archetypes"> + <title>Available Archetypes</title> + <tgroup align="left" cols="5" colsep="1" rowsep="1"> + <colspec colname="c1"></colspec> + <colspec colname="c2"></colspec> + <colspec colname="c3"></colspec> + <colspec colname="c5" colnum="5"></colspec> + <thead> + <row> + <entry align="center"> + Archetype + </entry> + <entry align="center" nameend="c5" namest="c2"> + Command + </entry> + </row> + </thead> + <tbody> + <row class="table-odd" style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;"> + <entry align="left"> + JSF 1.2 Basic + </entry> + <entry align="left" nameend="c5" namest="c2"> + <programlisting language="Java" role="Java"><xi:include href="../../../extras/PortletBridge_GettingStarted/default220.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </entry> - </row> - <row class="table-even" style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;"> - <entry align="left"> - RichFaces Basic - </entry> - <entry align="left" nameend="c5" namest="c2"> - + </entry> + </row> + <row class="table-even" style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;"> + <entry align="left"> + RichFaces Basic + </entry> + <entry align="left" nameend="c5" namest="c2"> + <programlisting language="Java" role="Java"><xi:include href="../../../extras/PortletBridge_GettingStarted/default221.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </entry> - </row> - <row class="table-odd" style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;"> - <entry align="left"> - Seam Basic (Modular EAR) - </entry> - <entry align="left" nameend="c5" namest="c2"> - + </entry> + </row> + <row class="table-odd" style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;"> + <entry align="left"> + Seam Basic (Modular EAR) + </entry> + <entry align="left" nameend="c5" namest="c2"> + <programlisting language="Java" role="Java"><xi:include href="../../../extras/PortletBridge_GettingStarted/default222.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </entry> - </row> + </entry> + </row> <row> <entry> Any combination JSF 1.2, RichFaces, or Seam. @@ -178,48 +160,45 @@ </programlisting> </entry> </row> - </tbody> - </tgroup> - </table> - </section> --> <!-- Section removed as per feedback from Prabhat Jha + </tbody> + </tgroup> + </table> + </section> --><!-- Section removed as per feedback from Prabhat Jha <section id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Video_Tutorials"> - <title>Video Tutorials</title> - <para> - The following links provide tutorial videos created by the Portlet Bridge developer: - </para> - <itemizedlist> - <listitem> - <para> - <ulink url="http://www.vimeo.com/3977469">Episode 1: Getting Started With The Bridge</ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="http://www.vimeo.com/4521877">Episode 2: Portlet 1.0 Advanced Seam and RichFaces</ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="http://www.vimeo.com/5847864">Episode 3: Seam and Portlet 2.0 Eventing</ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="http://www.vimeo.com/7255033">Episode 4: Running the 2.0 bridge on GateIn and deploy using JBoss Tools</ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="http://www.vimeo.com/8752541">Episode 5: GateIn JMX Metrics and Dashboard Demo</ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="http://www.vimeo.com/wesleyhales/videos">Check here for the latest videos.</ulink> - </para> - </listitem> - </itemizedlist> - </section> --> -</section> - - + <title>Video Tutorials</title> + <para> + The following links provide tutorial videos created by the Portlet Bridge developer: + </para> + <itemizedlist> + <listitem> + <para> + <ulink url="http://www.vimeo.com/3977469">Episode 1: Getting Started With The Bridge</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.vimeo.com/4521877">Episode 2: Portlet 1.0 Advanced Seam and RichFaces</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.vimeo.com/5847864">Episode 3: Seam and Portlet 2.0 Eventing</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.vimeo.com/7255033">Episode 4: Running the 2.0 bridge on GateIn and deploy using JBoss Tools</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.vimeo.com/8752541">Episode 5: GateIn JMX Metrics and Dashboard Demo</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.vimeo.com/wesleyhales/videos">Check here for the latest videos.</ulink> + </para> + </listitem> + </itemizedlist> + </section> --></section> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,110 +1,38 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-JBoss_Portlet_Bridge_Overview"> - <title>JBoss Portlet Bridge Overview</title> - <formalpara id="form-Reference_Guide-JBoss_Portlet_Bridge_Overview-What_is_the_JBoss_Portlet_Bridge"> - <title>What is the JBoss Portlet Bridge?</title> - <para> + <title>JBoss Portlet Bridge Overview</title> + <formalpara id="form-Reference_Guide-JBoss_Portlet_Bridge_Overview-What_is_the_JBoss_Portlet_Bridge"> + <title>What is the JBoss Portlet Bridge?</title> + <para> The JBoss Portlet Bridge (or <literal>JBPB</literal> for short) is an implementation of the <ulink url="http://jcp.org/en/jsr/detail?id=329">JSR-329</ulink> specification. </para> - - </formalpara> - <para> + </formalpara> + <para> It supports the JSF 1.2 runtime within a JSR 286 portlet and with added enhancements to support other web frameworks (such as <ulink url="http://www.seamframework.org/">Seam</ulink> and <ulink url="http://www.jboss.org/jbossrichfaces/">RichFaces</ulink>). </para> - <para> + <para> It allows any Java developer to quickly get started with their JSF web application running in a portal environment. The developer no longer needs to worry about the underlying portlet development, portlet concepts, or the API. </para> - <para> + <para> Find more information about the JBoss Portlet Bridge, the developers, the community at <ulink url="http://www.jboss.org/portletbridge/">the project page</ulink>. </para> - <formalpara id="form-Reference_Guide-JBoss_Portlet_Bridge_Overview-Understanding_how_JSF_works_with_Portal"> - <title>Understanding how JSF works with Portal</title> - <para> + <formalpara id="form-Reference_Guide-JBoss_Portlet_Bridge_Overview-Understanding_how_JSF_works_with_Portal"> + <title>Understanding how JSF works with Portal</title> + <para> The portlet bridge is not a portlet. It is the mediator between the two environments and allows JSF and Portal to be completely unaware of each other. </para> - - </formalpara> - <para> + </formalpara> + <para> The bridge is used to execute <literal>Faces</literal> requests on behalf of the portlet. During each request, the <literal>Faces</literal> environment is setup and handled by the bridge. </para> - <para> + <para> Part of this implementation acts as a <literal>Faces</literal> controller much as the FacesServlet does in the direct client request environment. </para> - <para> + <para> The other part of this implementation is provided by implementing a variety of (standard) <literal>Faces</literal> extensions. </para> - <important> - <title>Disclaimer</title> - <para> - This draft specification for the JSR 329 specification is not final. Any final specification that may be published will likely contain differences, some of which may be substantial. - </para> - <para> - Publication of this draft specification is not intended to provide the basis for implementations of the specification. This draft specification is provided AS IS. - </para> - <para> - THERE ARE NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF CONDITION OF TITLE OR NONINFRINGEMENT. You may copy and display this draft specification provided that you include this notice and any existing copyright notice. - </para> - <para> - Except for the limited copyright license granted above, there are no other licenses granted to any intellectual property owned or controlled by any of the authors or developers of this material. No other rights are granted by implication, estoppel or otherwise. - </para> - - </important> - <!-- <figure id="build.fig"> -<title>Faces in Portlet Environment</title> -<mediaobject> -<imageobject> -<imagedata align="center" fileref="images/portletbridge-basic.png"/> -</imageobject> -</mediaobject> -</figure> -<imageobject> -<imagedata fileref="images/frontpage.png" format="png" align="center" -valign="middle"/> -</imageobject> -</para> --><!-- <para> -<emphasis role="bold">JBoss Portal Resources:</emphasis> -<orderedlist> -<listitem> -<para> -<ulink url="http://labs.jboss.com/jbossportal">JBoss Portal Home Page</ulink> -</para> -</listitem> -<listitem> -<para>Forums: -<ulink -url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&amp;f=215" ->User</ulink> -| -<ulink -url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&amp;f=205" ->Design</ulink> -| -<ulink url="http://jboss.org/index.html?module=bb&amp;op=viewforum&... -</para> -</listitem> -<listitem> -<para> -<ulink url="http://www.jboss.com/wiki/Wiki.jsp?page=JBossPortal">Wi... -</para> -</listitem> -<listitem> -<para> -<ulink url="http://www.portletswap.com">PortletSwap.com portlet exchange</ulink> -</para> -</listitem> -<listitem> -<para> -<ulink -url="http://jira.jboss.com/jira/browse/JBPORTAL?report=com.atlassian.jira.plugin.system.project:roadmap-panel" ->Our Roadmap</ulink> -</para> -</listitem> -</orderedlist> -</para> --> </section> - - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,255 +1,203 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge"> - <title>Developing Portlets with the Bridge</title> - <para> + <title>Developing Portlets with the Bridge</title> + <para> This chapter demonstrates common development tasks described by the 329 specification. </para> - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Excluding_Attributes_from_the_Bridge_Request_Scope"> - <title>Excluding Attributes from the Bridge Request Scope</title> - <para> + <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Excluding_Attributes_from_the_Bridge_Request_Scope"> + <title>Excluding Attributes from the Bridge Request Scope</title> + <para> When your application uses request attributes on a per request basis and you do not want that particular attribute to be managed in the extended bridge request scope, you must use the following configuration in your <filename>faces-config.xml</filename>. </para> - <para> - In the code sample below you can see that any attribute namespaced as <literal>foo.bar</literal> or any attribute beginning with <literal>foo.baz(wild-card)</literal> will be excluded from the bridge request scope and only be used per that application's request. + <para> + In the code sample below you can see that any attribute namespaced as <literal>foo.bar</literal> or any attribute beginning with <literal>foo.baz.(wild-card)</literal> will be excluded from the bridge request scope and only be used per that application&apos;s request. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default223.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Supporting_PortletMode_Changes"> - <title>Supporting PortletMode Changes</title> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default223.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Supporting_PortletMode_Changes"> + <title>Supporting PortletMode Changes</title> + <para> A <literal>PortletMode</literal> represents a distinct render path within an application. There are three standard modes: <emphasis>view</emphasis>, <emphasis>edit</emphasis>, and <emphasis>help</emphasis>. </para> - <para> - The bridge's <literal>ExternalContext.encodeActionURL</literal> recognizes the query string parameter <literal>javax.portlet.faces.PortletMode</literal> and uses this parameter's value to set the portlet mode on the underlying portlet <literal>actionURL</literal> or response. + <para> + The bridge&apos;s <literal>ExternalContext.encodeActionURL</literal> recognizes the query string parameter <literal>javax.portlet.faces.PortletMode</literal> and uses this parameter&apos;s value to set the portlet mode on the underlying portlet <literal>actionURL</literal> or response. </para> - <para> + <para> Once processed it then removes this parameter from the query string. This means the following navigation rule causes one to render the <filename>/edit.jspx</filename> viewId in the portlet edit mode: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default224.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Navigating_to_a_modes_last_viewId"> - <title>Navigating to a mode's last viewId</title> - <para> - By default a mode change will start in the mode's default view without any (prior) existing state. One common portlet pattern when returning to a mode left after entering another mode (e.g.. view -&gt; edit -&gt; view) is to return to the last view (and state) of this origin mode. + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default224.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Navigating_to_a_modes_last_viewId"> + <title>Navigating to a mode&apos;s last viewId</title> + <para> + By default a mode change will start in the mode&apos;s default view without any (prior) existing state. One common portlet pattern when returning to a mode left after entering another mode (e.g.. view -&gt; edit -&gt; view) is to return to the last view (and state) of this origin mode. </para> - <para> + <para> The bridge will explicitly encode the necessary information so that when returning to a prior mode it can target the appropriate view and restore the appropriate state. </para> - <para> - The session attributes maintained by the bridge are intended to be used by developers to navigate back from a mode to the last location and state of a prior mode. As such, a developer needs to describe a dynamic navigation: "From view <parameter>X</parameter> return to the last view of mode <parameter>Y</parameter>". + <para> + The session attributes maintained by the bridge are intended to be used by developers to navigate back from a mode to the last location and state of a prior mode. As such, a developer needs to describe a dynamic navigation: &quot;From view <parameter>X</parameter> return to the last view of mode <parameter>Y</parameter>&quot;. </para> - <para> + <para> This is most easily expressed via an <literal>EL</literal> expression. For example: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default225.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <section id="sect-Reference_Guide-Navigating_to_a_modes_last_viewId-Note_to_Portlet_Developers"> - <title>Note to Portlet Developers</title> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default225.xml" parse="text"/></programlisting> + <section id="sect-Reference_Guide-Navigating_to_a_modes_last_viewId-Note_to_Portlet_Developers"> + <title>Note to Portlet Developers</title> + <para> Depending on the bridge implementation, when using values from these session scoped attributes or any viewIds which may contain query string parameters it may be necessary to use the wild-card syntax when identifying the rule target. In the above, for example, the </para> - -<programlisting language="XML" role="XML">&lt;to-view-id&gt; + <programlisting language="XML" role="XML">&lt;to-view-id&gt; </programlisting> - <para> + <para> expression returns a <parameter>viewId</parameter> of the form </para> - -<programlisting language="XML" role="XML">/viewId?javax.portlet.faces.PortletMode=view&amp;.... + <programlisting language="XML" role="XML">/viewId?javax.portlet.faces.PortletMode=view&amp;.... </programlisting> - <para> - Without wild-carding, when a subsequent navigation occurs from this new view, the navigation rules wouldn't resolve because there wouldn't be an exact match. Likewise, the above <literal>edit.jspx</literal> + <para> + Without wild-carding, when a subsequent navigation occurs from this new view, the navigation rules wouldn&apos;t resolve because there wouldn&apos;t be an exact match. Likewise, the above <literal>edit.jspx</literal> </para> - -<programlisting language="XML" role="XML">&lt;from-view-id&gt; + <programlisting language="XML" role="XML">&lt;from-view-id&gt; </programlisting> - <para> + <para> is wild-carded because there are navigation rules that target it that use a query string: </para> - -<programlisting language="XML" role="XML"> + <programlisting language="XML" role="XML"> &lt;to-view-id&gt; /edit.jspx?javax.portlet.faces.PortletMode=edit &lt;/to-view-id&gt; </programlisting> - <para> + <para> Developers are encouraged to use such wild-carding to ensure they execute properly in the broadest set of bridge implementations. </para> - - </section> - - </section> - - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Clearing_The_View_History_When_Changing_Portlet_Modes"> - <title>Clearing The View History When Changing Portlet Modes</title> - <para> - By default the bridge remembers the view history when you switch to a different portlet mode (like "Help" or "Edit"). You can use the following parameter in your <filename>portlet.xml</filename> to use the default viewId each time you switch modes. + </section> + <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Clearing_The_View_History_When_Changing_Portlet_Modes"> + <title>Clearing The View History When Changing Portlet Modes</title> + <para> + By default the bridge remembers the view history when you switch to a different portlet mode (like &quot;Help&quot; or &quot;Edit&quot;). You can use the following parameter in your <filename>portlet.xml</filename> to use the default viewId each time you switch modes. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default230.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-General_Error_Handling"> - <title>General Error Handling</title> - <note> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default230.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-General_Error_Handling"> + <title>General Error Handling</title> + <note> + <para> If you are developing a <application>Seam</application> portlet you can now use <filename>pages.xml</filename> for all error handling. </para> - - </note> - <para> + </note> + <para> The following configuration may be used to handle exceptions. This is also useful for handling session timeout and <literal>ViewExpiredExceptions</literal>. </para> - <note> - <title>The Location Element</title> - <para> + <note> + <title>The Location Element</title> + <para> The location element must contain the <filename>/faces/</filename> mapping to work properly. </para> - - </note> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default231.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Custom_Ajax_Error_Handling"> - <title>Custom Ajax Error Handling</title> - <para> + </note> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default231.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Custom_Ajax_Error_Handling"> + <title>Custom Ajax Error Handling</title> + <para> By default, error handling is sent to a standard servlet page for Ajax requests. To handle the error inside the portlet, use the following javascript: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default232.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default232.xml" parse="text"/></programlisting> + <para> Also, add the following to <filename>web.xml</filename>. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default233.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default233.xml" parse="text"/></programlisting> + <para> Read more about these settings here <ulink url="http://docs.jboss.org/richfaces/3.3.X/3.3.3.Final/en/devguide/h... Errors and Session Expiration Handling</ulink> </para> - - </section> - - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Communication_Between_Your_Portlets"> - <title>Communication Between Your Portlets</title> - <para> + </section> + <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Communication_Between_Your_Portlets"> + <title>Communication Between Your Portlets</title> + <para> There are four different ways to send messages, events, and parameters between portlets which are contained in different <literal>ears/wars</literal> or contained in the same <literal>war</literal>. </para> - <para> + <para> Having two portlets in the same <literal>war</literal> or having them separated does not affect the Portlet Container because each portlet has a different <parameter>HttpSession</parameter>. </para> - <para> - The recommended way to share a parameter or event payload between two or more portlets with the Portlet 2.0 specification are the <xref linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters" /> and <xref linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events" /> mechanisms. + <para> + The recommended way to share a parameter or event payload between two or more portlets with the Portlet 2.0 specification are the <xref linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters"/> and <xref linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events"/> mechanisms. </para> - <para> + <para> This allows you to decouple your application from surgically managing objects in the <parameter>PortletSession.APPLICATION_SCOPE.</parameter> </para> - <para> + <para> However, if these do not meet your use case or you have a different strategy, you can use one of the following methods. </para> - <section id="sect-Reference_Guide-Communication_Between_Your_Portlets-Storing_Components_in_PortletSession.APPLICATION_SCOPE"> - <title>Storing Components in <parameter>PortletSession.APPLICATION_SCOPE</parameter></title> - <para> + <section id="sect-Reference_Guide-Communication_Between_Your_Portlets-Storing_Components_in_PortletSession.APPLICATION_SCOPE"> + <title>Storing Components in <parameter>PortletSession.APPLICATION_SCOPE</parameter></title> + <para> Sometimes it is beneficial to store your <application>Seam</application> components in the portlet <parameter>APPLICATION_SCOPE</parameter>. </para> - <para> + <para> By default, these objects are stored in the <parameter>PORTLET_SCOPE</parameter> but with the annotation below, this class can be pulled out of the <literal>PortletSession</literal> and its values used in other portlets across different <application>Seam</application> applications. </para> - -<programlisting language="Java" role=&quot;JAVA&quot;&gt;(a)PortletScope(PortletScope.ScopeType.APPLICATION_SCOPE) + <programlisting language="Java" role=&quot;JAVA&quot;&gt;(a)PortletScope(PortletScope.ScopeType.APPLICATION_SCOPE) </programlisting> - <para> + <para> Then you would pull the stateful object from the session: </para> - -<programlisting language="Java" role="Java"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default235.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default235.java" parse="text"/></programlisting> + <para> This method is demonstrated in this video: <ulink url="http://www.vimeo.com/4521877">Lesson 2: Portlet 1.0 Advanced Seam and RichFaces</ulink> </para> - - </section> - - <section id="sect-Reference_Guide-Communication_Between_Your_Portlets-Using_the_PortletSession"> - <title>Using the PortletSession</title> - <para> + </section> + <section id="sect-Reference_Guide-Communication_Between_Your_Portlets-Using_the_PortletSession"> + <title>Using the PortletSession</title> + <para> If you need to access the <literal>PortletSession</literal> to simply share a parameter or value across multiple portlets, you can use the following: </para> - -<programlisting language="Java" role="Java"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default236.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default236.java" parse="text"/></programlisting> + <para> Then, in your JSP or Facelets page, you can use: </para> - -<programlisting language="XML" role="XML">#{httpSessionScope['your parameter name']} + <programlisting language="XML" role="XML">#{httpSessionScope[&apos;your parameter name&apos;]} </programlisting> - <para> + <para> <note> - <title>Note to Portlet Developers</title> - <para> + <title>Note to Portlet Developers</title> + <para> <literal>#{httpSessionScope}</literal> was implemented after <literal>2.0.0.BETA</literal>. If you are using the <literal>1.0</literal> bridge or pre <literal>2.0.0.BETA</literal>, you must use the <literal>EL</literal> variable <literal>#{sessionApplicationScope}</literal>. </para> - - </note> + </note> For more information about which <literal>EL</literal> variables are provided by the bridge, read <ulink url="http://jcp.org/aboutJava/communityprocess/edr/jsr329/index2.htm... 6.5.1 of the JSR-329 specification</ulink>. </para> - - </section> - - </section> - - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Linking_to_PortletJSF_Pages_Using_houtputlink"> - <title>Linking to Portlet/JSF Pages Using h:outputlink</title> - <para> + </section> + <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Linking_to_PortletJSF_Pages_Using_houtputlink"> + <title>Linking to Portlet/JSF Pages Using h:outputlink</title> + <para> For linking to any JSF/Facelets page within your portlet web application, you can use the following. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default238.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Redirecting_to_an_External_Page_or_Resource"> - <title>Redirecting to an External Page or Resource</title> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default238.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Redirecting_to_an_External_Page_or_Resource"> + <title>Redirecting to an External Page or Resource</title> + <para> To link to a non JSF view, <emphasis>jboss.org</emphasis> for example, you can use the following parameter. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default239.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default239.xml" parse="text"/></programlisting> + <para> Then in your backing bean, you must call a <parameter>redirect()</parameter>. </para> - -<programlisting language="Java" role="JAVA">FacesContext.getCurrentInstance().getExternalContext().redirect("http://www.jboss.org"); + <programlisting language="Java" role="JAVA">FacesContext.getCurrentInstance().getExternalContext().redirect(&quot;http://www.jboss.org&quot;); </programlisting> - - </section> - - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Using_Provided_EL_Variables"> - <title>Using Provided EL Variables</title> - <para> + </section> + <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Using_Provided_EL_Variables"> + <title>Using Provided EL Variables</title> + <para> All <literal>EL</literal> variables found in the JSR-329 (Portlet 2.0) specification are available in the JBoss Portlet Bridge. For example, you can use the following to edit the portlet preferences on the UI: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default241.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default241.xml" parse="text"/></programlisting> + <para> Then in your backing bean, you must call the PortletPreferences.store() method. </para> - -<programlisting language="Java" role="Java"><xi:include href="../../../extras/PortletBridge_Portlet_Development/default242.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default242.java" parse="text"/></programlisting> + </section> </section> - - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -121,7 +121,7 @@ This section describes how to deploy a portlet in JBoss Enterprise Portal Platform. </para> <para> - An example portlet called <filename>SimplestHelloWorld</filename> is available in the <filename>/jboss-epp-&lt;VERSION&gt;-src/portal/examples/portlets/</filename> directory of the JBoss Enterprise Portal Platform sources package. + An example portlet called <filename>SimplestHelloWorld</filename> is available in the <filename>/jboss-epp-<replaceable>VERSION</replaceable>-src/portal/examples/portlets/</filename> directory of the JBoss Enterprise Portal Platform sources package. </para> <section id="sect-Reference_Guide-Deploying_your_first_Portlet-Compiling"> <title>Compiling</title> @@ -142,7 +142,7 @@ </step> <step> <para> - Copy the package file into <literal>EPP_HOME/server/default/deploy</literal>. + Copy the package file into <literal><replaceable>EPP_DIST</replaceable>/jboss-as/server/default/deploy</literal>. </para> </step> <step> @@ -354,7 +354,7 @@ <para>Obtain the JBoss Enterprise Portal Platform sources package from the Customer Support portal.</para> </step> <step> - <para>Move to <filename>/jboss-epp-&lt;VERSION&gt;-src/portal/examples/portlets/jsphellouser</filename> </para> + <para>Move to <filename>/jboss-epp-<replaceable>VERSION</replaceable>-src/portal/examples/portlets/jsphellouser</filename> </para> </step> <step> <para> @@ -523,7 +523,7 @@ In order to write a portlet using JSF a &apos;bridge&apos; is needed. This software allows developers to write a portlet application as if it was a JSF application. The bridge then negotiates the interactions between the two layers. </para> <para> - An example using the JBoss Portlet Bridge is available in the <filename>/jboss-epp-&lt;VERSION&gt;-src/portal/examples/portlets/</filename> directory of the JBoss Enterprise Portal Platform sources package. The configuration is slightly different from a JSP application. This example can be used as a base to configure instead of creating a new application. + An example using the JBoss Portlet Bridge is available in the <filename>/jboss-epp-<replaceable>VERSION</replaceable>-src/portal/examples/portlets/</filename> directory of the JBoss Enterprise Portal Platform sources package. The configuration is slightly different from a JSP application. This example can be used as a base to configure instead of creating a new application. </para> <para> As in any JSF application, the file <literal>faces-config.xml</literal> is required. It must contain the following information: Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,105 +1,89 @@ -<?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 "../Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="wsrp"> - <title>Web Services for Remote Portlets (WSRP)</title> - - <section> - <title>Introduction</title> - <para>The Web Services for Remote Portlets specification defines a web service interface for accessing and + <title>Web Services for Remote Portlets (WSRP)</title> + <section> + <title>Introduction</title> + <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>Scenarios that motivate WSRP functionality include: </para> - <itemizedlist> - <listitem> - <para>Content hosts, such as portal servers, providing Portlets as presentation-oriented web services + <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 + </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 + </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... website for WSRP</ulink>. Further suggested reading is the <ulink url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr... for a good, albeit technical, overview of WSRP. </para> - </section> - - <section id="wsrp_support"> - <title>Level of support in JBoss Enterprise Portal Platform</title> - <para>The WSRP Technical Committee defined + </section> + <section id="wsrp_support"> + <title>Level of support in JBoss Enterprise Portal Platform</title> + <para>The WSRP Technical Committee defined <ulink url="http://www.oasis-open.org/committees/download.php/3073">... Use Profiles</ulink> to help with WSRP interoperability. This section will refer to terms defined in that document. </para> - - <para>JBoss Enterprise Portal Platform provides a Simple level of support for the WSRP Producer except that out-of-band registration + <para>JBoss Enterprise 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 Enterprise Portal Platform provides a Medium level of support for WSRP, except that the consumer only handles + <para>On the Consumer side, JBoss Enterprise Portal Platform provides a Medium level of support for WSRP, except that the consumer only handles HTML markup (as JBoss Enterprise Portal Platform itself does not handle other markup types). It 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 + <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 Enterprise 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 + <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">... 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 Enterprise Portal Platform supports WSRP 2.0 with a complete implementation of the non-optional features. The only + <para>JBoss Enterprise 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 Enterprise Portal Platform, WSRP is only activated and supported + <note> + <title>Note</title> + <para>As of version &VZ; of JBoss Enterprise Portal Platform, WSRP is only activated and supported when JBoss Enterprise Portal Platform is deployed on JBoss Application Server. </para> - </note> - </section> - - <section> - <title>Deploying JBoss Enterprise Portal Platform's WSRP services</title> - <para> + </note> + </section> + <section> + <title>Deploying JBoss Enterprise Portal Platform&apos;s WSRP services</title> + <para> JBoss Enterprise Portal Platform provides a complete support of 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 Enterprise Portal Platform - extension and is now self-contained in an easy to install package named - <filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear</filename> - where - <filename>$JBOSS_PROFILE_HOME</filename> - refers to your JBoss AS profile directory (<filename>default</filename>, for instance). + extension and is now self-contained in a package named + <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein-wsrp-integration.ear</filename> +. </para> - <para> - The extension itself is composed of the following components, assuming - <replaceable>$WSRP_VERSION</replaceable> - (at the time of the writing, it was &WSRP_VERSION;) is the version of the WSRP component and - <replaceable>$PORTAL_VERSION</replaceable> - (at the time of the writing, it was &VZ;) is the current JBoss Enterprise Portal Platform version: + <para> + The extension itself is composed of the following components: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <filename>META-INF</filename> contains files necessary for EAR packaging. The only file that is of interest from a user perspective is @@ -107,169 +91,163 @@ which allows you to configure WS-Security support for the consumer. Please see the <xref linkend="wss_configuration"/> section for more details. </para> - </listitem> - <listitem> - <para> - The <filename>extension-component-$PORTAL_VERSION.jar</filename>, which contains the components needed to + </listitem> + <listitem> + <para> + The <filename>extension-component-&VZ;.jar</filename>, which contains the components needed to integrate the WSRP component into JBoss Enterprise 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-$PORTAL_VERSION.jar</filename>, which contains the configuration file + </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-$PORTAL_VERSION.war</filename>, which contains the configuration files + </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 Enterprise Portal Platform. </para> - </listitem> - <listitem> - <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 + </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 + </listitem> + <listitem> + <para> + The <filename>wsrp-producer-jb5wsss-&WSRP_VERSION;.war</filename>, which contains the producer-side support for WS-Security. The only file of interest from a user perspective is <filename>gatein-wsse-producer.xml</filename> which allows you to configure WS-Security support for the producer. Please see the <xref linkend="wss_configuration"/> section. for more details. </para> - </listitem> - </itemizedlist> - - <para> + </listitem> + </itemizedlist> + <para> If you are not going to use WSRP in JBoss Enterprise 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 Enterprise Portal Platform on a non-default port or hostname</title> - <para> + <section id="wsrp-ports"> + <title>Considerations to use WSRP when running JBoss Enterprise Portal Platform on a non-default port or hostname</title> + <para> JBoss WS (the web service stack that JBoss Enterprise Portal Platform uses) should take care of the details of updating the port and host name used in WSDL. See the - <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... WS user guide on that - subject - </ulink> + <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... WS user guide on that subject </ulink> for more details. </para> - <para> + <para> Of course, 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 Enterprise Portal Platform's 'self' producer. Please refer to + update the configuration for the consumer used to consume JBoss Enterprise Portal Platform&apos;s &apos;self&apos; producer. Please refer to the <xref linkend="consumer_configuration"/> to learn how to do so. </para> - </section> - </section> - - <section> - <title>Securing WSRP</title> - <section> - <title>Considerations to use WSRP with SSL</title> - <para>It is possible to use WSRP over SSL for secure exchange of data. Please refer to the + </section> + </section> + <section> + <title>Securing WSRP</title> + <section> + <title>Considerations to use WSRP with SSL</title> + <para>It is possible to use WSRP over SSL for secure exchange of data. Please refer to the <ulink url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu... on how to do so from - <ulink url="http://community.jboss.org/wiki/GateIn">GateIn's wiki</ulink>. + <ulink url="http://community.jboss.org/wiki/GateIn">GateIn&apos;s wiki</ulink>. </para> - </section> - <section> - <title>WSRP and WS-Security</title> - <para>Portlets may present different data or options depending on the currently authenticated user. For remote + </section> + <section> + <title>WSRP and WS-Security</title> + <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. </para> - <note> - <title>Web Container Compatibility</title> - <para>WSRP and WS-Security is currently only supported on JBoss Enterprise Portal Platform when running on top of JBoss + <note> + <title>Web Container Compatibility</title> + <para>WSRP and WS-Security is currently only supported on JBoss Enterprise Portal Platform when running on top of JBoss AS 5. </para> - </note> - <warning> - <title>Encryption</title> - <para>You will want to encrypt the credentials being sent between the consumer and producer, otherwise they + </note> + <warning> + <title>Encryption</title> + <para>You will want to encrypt the credentials being sent between the consumer and producer, otherwise they will be sent in plain text and could be easily intercepted. You can either 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. <emphasis role="bold">Use of encryption is strongly recommended.</emphasis> </para> - </warning> - <important> - <title>Credentials</title> - <para>When the consumer sends the user credentials to the producer, it is sending the credentials for the + </warning> + <important> + <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. Please + <para>The recommended approach for this situation would be to use a common LDAP configuration. Please see the user guide on how to configure LDAP for use with JBoss Enterprise Portal Platform </para> - </important> - <para>The GateIn Wiki article, <ulink url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity... - GateIn WSRP and Web Service Security</ulink>, also provides a step-by-step example on how to configure + </important> + <para>The GateIn Wiki article, <ulink url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity... GateIn WSRP and Web Service Security</ulink>, also provides a step-by-step example on how to configure WSRP with WS-Security. </para> - <section id="wss_configuration"> - <title>WS-Security Configuration</title> - <para>JBoss Enterprise Portal Platform uses JBossWS Native to handle ws-security. Please see the WS-Security section of the - <ulink url="http://www.jboss.org/jbossas/docs/5-x">JBoss AS 5 Administration and Configuration Guide - </ulink> for in-depth configuration options. Please note that since the consumer passes its credentials + <section id="wss_configuration"> + <title>WS-Security Configuration</title> + <para>JBoss Enterprise Portal Platform uses JBossWS Native to handle ws-security. Please see the WS-Security section of the + <ulink url="http://www.jboss.org/jbossas/docs/5-x">JBoss AS 5 Administration and Configuration Guide </ulink> for in-depth configuration options. Please note that since the consumer passes its credentials to the producer, the consumer will act as the wss client and the producer will act as the wss server. </para> - <para> The following are the JBossWS Native configuration files which need to be configure for WSRP: + <para> The following are the JBossWS Native configuration files which need to be configure for WSRP: </para> - <itemizedlist> - <listitem> - <para> - <filename>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</filename>: JBossWS + <itemizedlist> + <listitem> + <para>JBossWS configuration file for the consumer. </para> - </listitem> - <listitem> - <para> - <filename>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml - </filename>: JBossWS configuration file for the producer. + <para> + <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE/</replaceable>/gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</filename></para> + </listitem> + <listitem> + <para>JBossWS configuration file for the producer. </para> - </listitem> - </itemizedlist> - </section> - <section> - <title>WS-Security Producer Configuration</title> - <para> + <para> + <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml </filename></para> + </listitem> + </itemizedlist> + </section> + <section> + <title>WS-Security Producer Configuration</title> + <para> Other than the JBossWS configuration file mention above, no other configuration changes should be necessary for the producer. </para> - </section> - <section> - <title>WS-Security Consumer Configuration</title> - <para>The consumer requires a few changes before it will function properly with WS-Security. The consumer + </section> + <section> + <title>WS-Security Consumer Configuration</title> + <para>The consumer requires a few changes before it will function properly with WS-Security. The consumer needs access to the current servlet request since this is used to retrieve the currently authenticated user. In order for the consumer to access this information, it needs a special servlet-filter added to the portal. </para> - <para>In <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> add the following information: + <para>In <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/02portal.war/WEB-INF/web.xml</filename> add the following information: </para> -<programlisting role="XML"><![CDATA[<!-- Filter to put request and response in ServletAccess --> + <programlisting role="XML"><![CDATA[<!-- Filter to put request and response in ServletAccess --> <filter> <filter-name>ServletAccessFilter</filter-name> <filter-class>org.gatein.wsrp.servlet.ServletAccessFilter</filter-class> @@ -279,47 +257,46 @@ <url-pattern>/*</url-pattern> </filter-mapping>]]> </programlisting> - <para> - Finally, in the WSRP Configuration portlet, in the consumer configuration options, you will need to check the 'Enable WS Security' checkbox: + <para> + Finally, in the WSRP Configuration portlet, in the consumer configuration options, you will need to check the &apos;Enable WS Security&apos; checkbox: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_wss_selected.png" format="PNG" align="center" valign="middle" scalefit="1"/> - </imageobject> - </mediaobject> - </section> - <section> - <title>WS-Security Consumer Checklist</title> - <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_wss_selected.png" format="PNG"/> + </imageobject> + </mediaobject> + </section> + <section> + <title>WS-Security Consumer Checklist</title> + <para> In order for the consumer to handle ws-security, the following steps must be completed properly </para> - <itemizedlist> - <listitem> - <para>The JBossWS configuration files must be configured.</para> - </listitem> - <listitem> - <para>The filter must be added to the portal's web.xml.</para> - </listitem> - <listitem> - <para>The enable wss feature must be check in the wsrp admin.</para> - </listitem> - </itemizedlist> - <para>The consumer will not properly handle ws-security unless all 3 are properly configured.</para> - </section> + <itemizedlist> + <listitem> + <para>The JBossWS configuration files must be configured.</para> + </listitem> + <listitem> + <para>The filter must be added to the portal&apos;s web.xml.</para> + </listitem> + <listitem> + <para>The enable wss feature must be check in the wsrp admin.</para> + </listitem> + </itemizedlist> + <para>The consumer will not properly handle ws-security unless all 3 are properly configured.</para> </section> - </section> - - <section> - <title>Making a portlet remotable</title> - <important> - <para> + </section> + </section> + <section> + <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 Enterprise Portal Platform does - <emphasis role="bold">NOT</emphasis>, by default, expose local portlets for consumption - by remote WSRP consumers. In order to make a portlet remotely available, it must be made "remotable" by marking + </important> + <para>JBoss Enterprise 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 @@ -329,11 +306,11 @@ 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> - <para>In the following example, the "BasicPortlet" portlet is specified as being remotable. + <example> + <title>Single Portlet Remotable Example</title> + <para>The &quot;BasicPortlet&quot; portlet is specified as being remotable. </para> - <example> - <title>Example</title> - <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" @@ -353,9 +330,8 @@ </portlet> </portlet-app>]]></programlisting> </para> - - </example> - <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> @@ -364,10 +340,20 @@ element level. Individual portlets can override that value to not be remotely exposed. This is an example: </para> - <example> - <title>Example</title> - <para> - <programlisting><![CDATA[ + <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 Enterprise Portal Platform&apos;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" @@ -394,45 +380,32 @@ </container-runtime-option> </portlet-app>]]> </programlisting> - </para> - - </example> - - <para> - The example above defines two portlets. The + <para>It is possible to override the default behavior by specifying a value for 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 Enterprise Portal Platform's - WSRP - producer. - Note, however, that it is possible to override the default behavior: specifying a value for the - <code>org.gatein.pc.remotable container-runtime-option</code> - at the <code>portlet</code> - level will take precedence over the default. In the example above, the + 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 + 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. + value set to <code>true</code>, portlets are not remotely exposed. </para> - </section> - - <section> - <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 + </example> + </section> + <section> + <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&apos;s WSDL definition. Please refer to the remote producer&apos;s documentation for specific instructions. For instructions on how to do so in JBoss Enterprise Portal Platform, please refer to <xref linkend="consumer_configuration"/>. </para> - <para> - JBoss Enterprise Portal Platform's Producer is automatically set up when you deploy a portal instance with the WSRP service. + <para> + JBoss Enterprise Portal Platform&apos;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 @@ -441,64 +414,53 @@ <literal>localhost</literal> and the default port is 8080. </para> - </section> - - <section id="consumer_configuration"> - <title>Consuming remote WSRP portlets in JBoss Enterprise Portal Platform</title> - <section> - <title>Overview</title> - <para> - To be able to consume WSRP portlets exposed by a remote producer, JBoss Enterprise Portal Platform's WSRP consumer needs to + </section> + <section id="consumer_configuration"> + <title>Consuming remote WSRP portlets in JBoss Enterprise Portal Platform</title> + <section> + <title>Overview</title> + <para> + To be able to consume WSRP portlets exposed by a remote producer, JBoss Enterprise Portal Platform&apos;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> + <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 id="consumer_gui"> - <title>Configuring a remote producer using the configuration portlet</title> - <para> + </section> + <section id="consumer_gui"> + <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 Enterprise Portal Platform. We will configure access to NetUnity's public WSRP producer. + consumed within JBoss Enterprise Portal Platform. We will configure access to NetUnity&apos;s public WSRP producer. </para> - - <note> - <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/Workaroundwhenchunkedencodingis... page - </ulink> + <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/Workaroundwhenchunkedencodingis... page </ulink> for more details. </para> - </note> - - <para> + </note> + <para> JBoss Enterprise 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%2Fclassic%2FwsrpConfiguration&amp;username=root&amp;password=gtn"> - http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... - </ulink> + <ulink url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&amp;username=root&amp;password=gtn"> http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... </ulink> </para> - - <para> + <para> You should see a screen similar to: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_init.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - <para>This screen presents all the configured Consumers associated with their status and possible actions on + <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 @@ -506,65 +468,57 @@ 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> + <note> + <title>Note</title> + <para> The WSRP configuration was not installed by default in previous versions of JBoss Enterprise 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> + <para> Use the usual procedure to log in as a Portal administrator and go to the Application Registry. With the default install, you can just go to - <ulink - url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&amp;username=root&amp;password=gtn"> - http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... - </ulink> + <ulink url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&amp;username=root&amp;password=gtn"> http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... </ulink> 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> + <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> + </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": + &quot;<literal>netunity</literal>&quot; in + the &quot;Create a consumer named:&quot; field then click on &quot;Create consumer&quot;: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_create.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - <para>You should now see a form allowing you to enter/modify the information about the Consumer. + <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 &amp; Save" button:</para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_wsdl.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - <para>This will retrieve the service description associated with the Producer which WSRP interface is described + and press the &quot;Refresh &amp; Save&quot; 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 fileref="images/WSRP/config_missing.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - <para>This particular producer requests simple + <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> @@ -572,64 +526,56 @@ <literal>Yes</literal> and <literal>No</literal> - (in that order) for the values and then pressing the "Refresh &amp; Save" button should result in:</para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_end.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - - <note> - <title>Note</title> - <para>At this point, there is no automated way to learn about which possible values (if any) are + (in that order) for the values and then pressing the &quot;Refresh &amp; Save&quot; 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 + property description but this is not always the case... Please refer to the specific Producer&apos;s documentation. </para> - </note> - - <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 Enterprise Portal Platform's producer via - WSRP 2), you would have seen something similar to the screenshot below, after pressing the "Refresh &amp; Save" button: + consumer (the consumer that accesses the portlets made remotely available by JBoss Enterprise Portal Platform&apos;s producer via + WSRP 2), you would have seen something similar to the screenshot below, after pressing the &quot;Refresh &amp; Save&quot; button: <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_refresh.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_refresh.png" format="PNG"/> + </imageobject> + </mediaobject> </para> - </section> - - <section id="consumer_xml"> - <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 + </section> + <section id="consumer_xml"> + <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>$JBOSS_PROFILE_HOME/conf/gatein/</filename> directory. + <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/conf/gatein/</filename> directory. </para> - <note> - <title>Note</title> - <para>An XML Schema defining which elements are available to configure Consumers via XML can be found + <note> + <title>Note</title> + <para>An XML Schema defining which elements are available to configure Consumers via XML can be found in - <filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd - </filename> + <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-&WSRP_VERSION;.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> </para> - </note> - <important> - <para> + </note> + <important> + <para> It is important to note that 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> - - <!--<para>It is important to note how the XML consumers configuration file is processed. It is read the first +<!--<para>It is important to note how the XML consumers configuration file is processed. It is read the first time the WSRP service starts and the associated information is then put under control of JCR (Java Content Repository). Subsequent launches of the WSRP service will use the JCR-stored information for all producers already known to JBoss Enterprise Portal Platform. More specifically, the @@ -646,46 +592,37 @@ <filename>wsrp-consumers-config.xml</filename> (if such information exists) as the producer will be re-created the next time the WSRP is launched if that information is not removed. - </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>--> </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 + <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>&lt;wsrp-producer&gt;</literal> element. </para> - - <para>JBoss Enterprise Portal Platform also needs to learn about the remote producer's endpoints to be able to connect to the + <para>JBoss Enterprise Portal Platform also needs to learn about the remote producer&apos;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>&lt;endpoint-wsdl-url&gt;</literal> element. </para> - - <para>Both the + <para>Both the <literal>id</literal> attribute and <literal>&lt;endpoint-wsdl-url&gt;</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 + </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 + <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 @@ -700,8 +637,7 @@ 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 + <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 @@ -709,21 +645,18 @@ 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 + <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 + <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 + </note> + <para>Registration configuration is done via the <literal>&lt;registration-data&gt;</literal> element. Since JBoss Enterprise 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 @@ -737,31 +670,28 @@ element. If you choose to provide a consumer name, please remember that this should uniquely identify your consumer. </para> - </section> - - <section> - <title>Examples</title> - - <para> + </section> + <section> + <title>Examples</title> + <para> Here is the configuration of the <literal>selfv1</literal> and <literal>selfv2</literal> consumers as found in - <filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename> + <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/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> + <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 <xref linkend="consumer_gui"/>. </para> - </note> + </note> </para> - - <example> - <title>Example</title> - <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" @@ -782,14 +712,11 @@ </deployments>]]> </programlisting> </para> - - </example> - - <para>Here is an example of a WSRP descriptor with registration data and cache expiring every minute:</para> - - <example> - <title>Example</title> - <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" @@ -810,53 +737,46 @@ </deployment> </deployments>]]></programlisting> </para> - </example> - </section> + </example> </section> - - <section> - <title>Adding remote portlets to categories</title> - <para> + </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 fileref="images/WSRP/remote_portlets.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/remote_portlets.png" format="PNG"/> + </imageobject> + </mediaobject> </para> - - <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> + <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 fileref="images/WSRP/remote_portlets_category.png" format="PNG" align="center" - valign="middle" - scalefit="1"/> - </imageobject> - </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> + </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> + <para> Of note, though, is that, starting with version 5.2 of JBoss Enterprise Portal Platform, it is now possible to also add a remote portlet to a <filename>pages.xml</filename> @@ -875,28 +795,28 @@ 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> + <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> + <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 Enterprise Portal Platform's WSRP producer, the portlet handles are, at + <note> + <para> + For remote portlets published by JBoss Enterprise Portal Platform&apos;s WSRP producer, the portlet handles are, at the time of this writing, following the <literal>/&lt;portlet application name&gt;.&lt;portlet name&gt;</literal> format. </para> - </note> - <section> - <title>Example</title> - <para> + </note> + <section> + <title>Example</title> + <para> In the following example, two portlets are defined for a page named <literal>Test</literal> in the @@ -905,23 +825,23 @@ other one accessing it via the <literal>selfv2</literal> - consumer which consumes JBoss Enterprise Portal Platform's WSRP producer. You can see that the first one is local (the + consumer which consumes JBoss Enterprise Portal Platform&apos;s WSRP producer. You can see that the first one is local (the <code>&lt;portlet-application&gt;</code> with the - '<literal>Added locally</literal>' + &apos;<literal>Added locally</literal>&apos; title) and follows the usual declaration. The second portlet (the one with the - '<literal>Added from selfv2 consumer</literal>' + &apos;<literal>Added from selfv2 consumer</literal>&apos; title) comes from the <literal>selfv2</literal> consumer and uses the <code>&lt;wsrp&gt;</code> element instead of <code>&lt;portlet&gt;</code> - element and follows the format for portlets coming from the JBoss Enterprise Portal Platform's WSRP producer. + element and follows the format for portlets coming from the JBoss Enterprise Portal Platform&apos;s WSRP producer. </para> - <example> - <title>Example</title> - <para> + <example> + <title>Example</title> + <para> <programlisting><![CDATA[ <page> <name>Test</name> @@ -948,123 +868,107 @@ </portlet-application> </page>]]></programlisting> </para> - </example> - </section> - + </example> </section> - </section> - - <section> - <title>Consumers maintenance</title> - + </section> + </section> + <section> + <title>Consumers maintenance</title> + <section> + <title>Modifying a currently held registration</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 + <title>Registration modification for service upgrade</title> + <para> + Producers often offer several levels of service depending on consumers&apos; 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> + <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> + <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> + <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> + <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&gt;foo(a)example.com&lt;/literal&gt;, change its value in the field for the <literal>email</literal> registration property: <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/modify_reg_start.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - Now click on "Update properties" to save the change. A "Modify registration" button should now appear to + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_start.png" format="PNG"/> + </imageobject> + </mediaobject> + Now click on &quot;Update properties&quot; to save the change. A &quot;Modify registration&quot; button should now appear to let you send this new data to the remote producer: <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/modify_reg_modify.png" format="PNG" align="center" - valign="middle" scalefit="1"/> - </imageobject> - </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 fileref="images/WSRP/modify_reg_end.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </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> + </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 Enterprise 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 fileref="images/WSRP/config_self.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - - <para>Now suppose that the administrator of the producer now additionally requires a value to be provided for a + <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 Enterprise Portal Platform are outlined in the section on how to configure JBoss Enterprise Portal Platform's producer + in JBoss Enterprise Portal Platform are outlined in the section on how to configure JBoss Enterprise Portal Platform&apos;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 &amp; Save": + the consumer by pressing &quot;Refresh &amp; Save&quot;: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/modify_reg_self.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - - <para>As you can see, the configuration screen now shows the currently held registration information and + <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 + and then click on &quot;Modify registration&quot;. If all went well and the producer accepted your new registration data, you should see something similar to: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/modify_reg_self_end.png" format="PNG" align="center" - valign="middle" scalefit="1"/> - </imageobject> - </mediaobject> - - <note> - <title>Note</title> - <para>WSRP 1 makes it rather difficult to ascertain for sure what caused an + <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 @@ -1074,127 +978,121 @@ 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> + </note> </section> - - <section> - <title>Consumer operations</title> - <para> + </section> + <section> + <title>Consumer operations</title> + <para> Several operations are available from the consumer list view of the WSRP configuration portlet: <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/consumer_operations.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/consumer_operations.png" format="PNG"/> + </imageobject> + </mediaobject> </para> - <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 + <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 + </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 + </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 + </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&apos;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> + </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 functionalities added in WSRP 2. Exporting a portlet allows a consumer to get + </note> + </section> + <section> + <title>Importing and exporting portlets</title> + <para>Import and export are new functionalities 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 Enterprise 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 Enterprise Portal Platform allows users to export portlets + <para>The import/export implementation in JBoss Enterprise 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. + previously exported portlets to replace the content displayed by windows on the portal&apos;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 + <para>Clicking on the &quot;Export&quot; 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 fileref="images/WSRP/export_portlet_list.png" format="PNG" align="center" valign="middle"/> - </imageobject> - </mediaobject> - <para>Once portlets have been selected, they can be exported by clicking on the "Export" button thus making + <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 &quot;Export&quot; button thus making them available for later import: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/export_done.png" format="PNG" align="center" valign="middle"/> - </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 + <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 &quot;Use for import&quot; button or, on the Consumers list + page, using the &quot;Import&quot; 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 fileref="images/WSRP/export_list.png" format="PNG" align="center" valign="middle"/> - </imageobject> - </mediaobject> - <para>As you can see this screen presents the list of available exports with available operations for each: + <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 fileref="images/WSRP/import_start.png" format="PNG" align="center" valign="middle"/> - </imageobject> - </mediaobject> - <para>The screen displays the list of available exported portlets for the previously selected export. You can + <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 @@ -1205,12 +1103,12 @@ <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> as shown below: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/import_original_page.png" format="PNG" align="center" valign="middle"/> - </imageobject> - </mediaobject> - <para>In this example, you want to replace the content of the + <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> @@ -1221,24 +1119,24 @@ 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 fileref="images/WSRP/import_selected_page.png" format="PNG" align="center" valign="middle"/> - </imageobject> - </mediaobject> - <para>Note that, at this point, you still need to select the window which content you want to replace before + <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 + window, at which point the &quot;Import&quot; 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 fileref="images/WSRP/import_success.png" format="PNG" align="center" valign="middle"/> - </imageobject> - </mediaobject> - <para>If you now take a look at the + <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> @@ -1246,87 +1144,82 @@ <literal>/ajaxPortlet.JSFAJAXPortlet</literal> imported portlet and the window renamed appropriately: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/import_modified_page.png" format="PNG" align="center" valign="middle"/> - </imageobject> - </mediaobject> - </section> - - <section> - <title>Erasing local registration data</title> - <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 - deregister first. This is the case when a consumer is registered with a producer that has been modified by + 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 + the remote producer. To do so, click on &quot;Erase local registration&quot; button next to the registration context information on the consumer configuration screen: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/erase_registration.png" format="PNG" align="center" valign="middle"/> - </imageobject> - </mediaobject> - <warning> - <title>Warning:</title> - <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 fileref="images/WSRP/erase_registration_warning.png" format="PNG" align="center" - valign="middle"/> - </imageobject> - </mediaobject> - </warning> - </section> - </section> - - <section id="producer_config"> - <title>Configuring JBoss Enterprise Portal Platform's WSRP Producer</title> - <section> - <title>Overview</title> - <para> - The preferred way to configure the behavior of Portal's WSRP Producer is via the WSRP configuration portlet. + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/erase_registration_warning.png" format="PNG"/> + </imageobject> + </mediaobject> + </warning> + </section> + </section> + <section id="producer_config"> + <title>Configuring JBoss Enterprise Portal Platform&apos;s WSRP Producer</title> + <section> + <title>Overview</title> + <para> + The preferred way to configure the behavior of Portal&apos;s WSRP Producer is via the WSRP configuration portlet. Alternatively, it is possible to add an XML file called <filename>wsrp-producer-config.xml</filename> in the - <filename>$JBOSS_PROFILE_HOME/conf/gatein/</filename> + <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/conf/gatein/</filename> directory. Several aspects can be modified with respects to whether registration is required for consumers to access - the Producer's services. + the Producer&apos;s services. </para> - <note> - <title>Note</title> - <para>An XML Schema defining which elements are available to configure Consumers via XML can be found + <note> + <title>Note</title> + <para>An XML Schema defining which elements are available to configure Consumers via XML can be found in - <filename> $JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_producer_1_0.xsd - </filename> + <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-&WSRP_VERSION;.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename> </para> - </note> - <important> - <title>Important</title> - <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 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> - <note> - <title>Note</title> - <para> + </important> + <note> + <title>Note</title> + <para> The default configuration file for the producer can be found at - <filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-producer-config.xml</filename> + <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein-wsrp-integration.ear/lib/extension-component-&WSRP_VERSION;.jar/conf/wsrp-producer-config.xml</filename> </para> - </note> - - </section> - <section> - <title>Default configuration</title> - <para> + </note> + </section> + <section> + <title>Default configuration</title> + <para> The default producer configuration is to require 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 @@ -1336,119 +1229,108 @@ paired with the default <classname>RegistrationPropertyValidator</classname>. Property validators will be discussed in greater detail later in <xref linkend="registration-configuration"/>. Suffice to say for now - that this allows users to customize how Portal's WSRP Producer decides whether a given registration property + that this allows users to customize how Portal&apos;s WSRP Producer decides whether a given registration property is valid or not. </para> - <para> - JBoss Enterprise Portal Platform provides a web interface to configure the producer's behavior. You can access it - by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. The image below is what you + <para> + JBoss Enterprise Portal Platform provides a web interface to configure the producer&apos;s behavior. You can access it + by clicking on the &quot;Producer Configuration&quot; tab of the &quot;WSRP&quot; page of the &quot;admin&quot; portal. The image below is what you should see with the default configuration: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/producer_default.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - <para>As would be expected, you can specify whether or not the producer will send the full service description to + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_default.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>As would be expected, 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>New in JBoss Enterprise Portal Platform, the WSDL URLs to access the Portal's WSRP producer are now displayed either in WSRP 1 + <para>New in JBoss Enterprise Portal Platform, the WSDL URLs to access the Portal&apos;s WSRP producer are now 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 + </section> + <section id="registration-configuration"> + <title>Registration configuration</title> + <para> + In order to require consumers to register with Portal&apos;s producer before interacting with it, you need to + configure Portal&apos;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. To configure the producer starting with a blank state: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/producer_blank.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - <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, + (&quot;Access to full service description requires consumers to be registered.&quot;) 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: + checkbox (&quot;Requires registration. Modifying this information will trigger invalidation of consumer + registrations.&quot;). The screen should now refresh and display: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/producer_registration.png" format="PNG" align="center" - valign="middle" scalefit="1"/> - </imageobject> - </mediaobject> - <para>You can specify the fully-qualified name for your + <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 more details. Add, however, a registration property called - <literal>email</literal>. Click "Add property" and enter the appropriate information in the fields, + <literal>email</literal>. Click &quot;Add property&quot; 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 fileref="images/WSRP/producer_email.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - <para>Press "Save" to record your modifications. + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_email.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>Press &quot;Save&quot; to record your modifications. </para> - - <note> - <title>Note</title> - <para>At this time, only String (xsd:string) properties are supported. If your application requires more + <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 + </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> + </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 + interface. This interface defines methods that are called by Portal&apos;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> + <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. </para> - <para> + <para> Please refer to the <trademark class="trade">Javadoc</trademark> for @@ -1458,15 +1340,15 @@ 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. This is + <para>Defining a registration policy is required for the producer to be correctly configured. This is accomplished by specifying the qualified class name of the registration policy. Since it is anticipated that most users will use the default registration policy, it is possible to provide the class name of your custom property validator instead to customize the default registration policy behavior. Note that property validators are only used by the default policy. <note> - <title>Note</title> - <para>Since the policy or the validator are defined via their class name and dynamically loaded, it is + <title>Note</title> + <para>Since the policy or the validator are defined via their class name and dynamically loaded, it is important that you make sure that the identified class is available to the application server. One way to accomplish that is to deploy your policy implementation as JAR file in your AS instance deploy @@ -1474,25 +1356,24 @@ must provide a default, no-argument constructor. </para> - </note> + </note> </para> - </section> </section> - <section id="strict-mode"> - <title>WSRP validation mode</title> - <para>The lack of conformance kit and the wording of the WSRP specification leaves room for differing + </section> + <section id="strict-mode"> + <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. 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> + <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. + you might want to try to relax the validation mode. This is accomplished by unchecking the &quot;Use strict WSRP + compliance.&quot; checkbox on the Producer configuration screen. </para> - </section> - - </section> + </section> + </section> </chapter> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/backup-client.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/backup-client.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/backup-client.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,200 +1,169 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-HTTPBackupAgent_and_Backup_Client"> - <title><literal>HTTPBackupAgent</literal> and Backup Client</title> - <warning> - <title>Configuration Persistance</title> - <para> - To use this service, you should configure the <literal>org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister</literal> in order to save the changes of the repository configuration. - </para> + <title><literal>HTTPBackupAgent</literal> and Backup Client</title> + <warning> + <title>Configuration Persistence</title> + <para> + To use this service, you should configure the <literal>org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister</literal> in order to save the changes of the repository configuration. + </para> + </warning> + <note> + <title>URI Context</title> + <para> + JBoss Enterprise Portal Platform uses context <uri>/portal/rest</uri>, therefore you need to use <uri>http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/portal/rest/</uri> instead of <uri>http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/rest/</uri> + </para> + <para> + JBoss Enterprise Portal Platform uses form authentication, so first you need to login (<uri>http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/portal/login</uri>) and then perform requests. + </para> + </note> + <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Introduction"> + <title>Introduction</title> + <para> + The <literal>org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent</literal> service is REST-based front-end to <literal>rg.exoplatform.services.jcr.ext.backup.BackupManager</literal>. + </para> + <para> + <literal>HTTPBackupAgent</literal> is representation <literal>BackupManager</literal> to create backups, restore and/or fetch status of current or completed backup/restore, etc. + </para> + <para> + The backup client is an <literal>HTTP</literal> client for <literal>HTTPBackupAgent</literal>. + </para> + </section> + <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-HTTPBackupAgent_"> + <title> + <literal>HTTPBackupAgent</literal> + </title> + <para> + The <literal>HTTPBackupAgent</literal> is based on REST and uses <literal>POST</literal> and <literal>GET</literal> methods for request. + </para> + <para> + The <literal>HTTPBackupAgent</literal> allows you to: + </para> + <itemizedlist> + <listitem> + <para> + Start a backup. + </para> + </listitem> + <listitem> + <para> + Stop a backup. + </para> + </listitem> + <listitem> + <para> + Restore from a backup. + </para> + </listitem> + <listitem> + <para> + Delete the workspace. + </para> + </listitem> + <listitem> + <para> + Get information about backup service (via <application>BackupManager</application>) + </para> + </listitem> + <listitem> + <para> + Get information about current backup or restore processes as well as information about completed backups + </para> + </listitem> + </itemizedlist> + <section id="sect-Reference_Guide-HTTPBackupAgent_-Methods"> + <title>Methods</title> + <variablelist id="vari-Reference_Guide-Methods-Starting_Backup_Service"> + <title>Starting Backup Service</title> + <varlistentry> + <term>/rest/jcr-backup/start/{repo}/{ws}</term> + <listitem> + <para> + Start backup on specific workspace + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL:</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/start/{repo}/{ws}</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats:</term> + <listitem> + <para> + json. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Method:</term> + <listitem> + <para> + Post. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters:</term> + <listitem> + <variablelist> + <title/> + <varlistentry> + <term>{repo}</term> + <listitem> + <para> + The repository name; + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{ws}</term> + <listitem> + <para> + The workspace name; + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>BackupConfigBean</term> + <listitem> + <para> + The JSON to <literal>BackupConfigBean</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>The BackupConfigBean</term> + <listitem> + <programlisting language="Java" role="java">header : +&quot;Content-Type&quot; = &quot;application/json; charset=UTF-8&quot; - </warning> - <note> - <title>URI Context</title> - <para> - JBoss Enterprise Portal Platform uses context <uri>/portal/rest</uri>, therefore you need to use <uri>http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/portal/rest/</uri> instead of <uri>http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/rest/</uri> - </para> - <para> - JBoss Enterprise Portal Platform uses form authentication, so first you need to login (<uri>http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/portal/login</uri>) and then perform requests. - </para> - - </note> - <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Introduction"> - <title>Introduction</title> - <para> - The <literal>org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent</literal> service is REST-based front-end to <literal>rg.exoplatform.services.jcr.ext.backup.BackupManager</literal>. - </para> - <para> - <literal>HTTPBackupAgent</literal> is representation <literal>BackupManager</literal> to create backups, restore and/or fetch status of current or completed backup/restore, etc. - </para> - <para> - The backup client is an <literal>HTTP</literal> client for <literal>HTTPBackupAgent</literal>. - </para> - - </section> - - <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-HTTPBackupAgent_"> - <title><literal>HTTPBackupAgent</literal> </title> - <para> - The <literal>HTTPBackupAgent</literal> is based on REST and uses <literal>POST</literal> and <literal>GET</literal> methods for request. - </para> - <para> - The <literal>HTTPBackupAgent</literal> allows you to: - </para> - <itemizedlist> - <listitem> - <para> - Start a backup. - </para> - - </listitem> - <listitem> - <para> - Stop a backup. - </para> - - </listitem> - <listitem> - <para> - Restore from a backup. - </para> - - </listitem> - <listitem> - <para> - Delete the workspace. - </para> - - </listitem> - <listitem> - <para> - Get information about backup service (via <application>BackupManager</application>) - </para> - - </listitem> - <listitem> - <para> - Get information about current backup or restore processes as well as information about completed backups - </para> - - </listitem> - - </itemizedlist> - <section id="sect-Reference_Guide-HTTPBackupAgent_-Methods"> - <title>Methods</title> - <variablelist id="vari-Reference_Guide-Methods-Starting_Backup_Service"> - <title>Starting Backup Service</title> - <varlistentry> - <term>/rest/jcr-backup/start/{repo}/{ws}</term> - <listitem> - <para> - Start backup on specific workspace - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL:</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/start/{repo}/{ws}</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats:</term> - <listitem> - <para> - json. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Method:</term> - <listitem> - <para> - Post. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters:</term> - <listitem> - <variablelist> - <title></title> - <varlistentry> - <term>{repo}</term> - <listitem> - <para> - The repository name; - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>{ws}</term> - <listitem> - <para> - The workspace name; - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>BackupConfigBean</term> - <listitem> - <para> - The JSON to <literal>BackupConfigBean</literal>. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </listitem> - - </varlistentry> - <varlistentry> - <term>The BackupConfigBean</term> - <listitem> - -<programlisting language="Java" role="java">header : -"Content-Type" = "application/json; charset=UTF-8" - body: &lt;JSON to BackupConfigBean&gt; </programlisting> - - </listitem> - - </varlistentry> - <varlistentry> - <term>JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.BackupConfigBean</literal>:</term> - <listitem> - -<programlisting language="Java" role="java">{"incrementalRepetitionNumber":&lt;Integer&gt;,"incrementalBackupJobConfig":&lt;JSON to BackupJobConfig&gt;, -"backupType":&lt;Integer&gt;,"fullBackupJobConfig":&lt;JSON to BackupJobConfig&gt;, -"incrementalJobPeriod":&lt;Long&gt;,"backupDir":"&lt;String&gt;"} + </listitem> + </varlistentry> + <varlistentry> + <term>JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.BackupConfigBean</literal>:</term> + <listitem> + <programlisting language="Java" role="java">{&quot;incrementalRepetitionNumber&quot;:&lt;Integer&gt;,&quot;incrementalBackupJobConfig&quot;:&lt;JSON to BackupJobConfig&gt;, +&quot;backupType&quot;:&lt;Integer&gt;,&quot;fullBackupJobConfig&quot;:&lt;JSON to BackupJobConfig&gt;, +&quot;incrementalJobPeriod&quot;:&lt;Long&gt;,&quot;backupDir&quot;:&quot;&lt;String&gt;&quot;} </programlisting> - <para> - As explained by the following help output: - </para> - -<programlisting>backupType - the type of backup: + <para> + As explained by the following help output: + </para> + <programlisting>backupType - the type of backup: 0 - full backup only; 1 - full and incremental backup. backupDir - the path to backup folder; @@ -202,370 +171,296 @@ incrementalRepetitionNumber - the incremental repetition number; fullBackupJobConfig - the configuration to full backup, JSON to BackupJobConfig; incrementalJobPeriod - the configuration to incremental backup, JSON to BackupJobConfig.</programlisting> - - </listitem> - - </varlistentry> - <varlistentry> - <term>JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.BackupJobConfig</literal></term> - <listitem> - -<programlisting>{"parameters":[&lt;JSON to Pair&gt;, ..., &lt;JSON to pair&gt; ],"backupJob":"&lt;String&gt;"}</programlisting> - <para> - Where: - </para> - -<programlisting>backupJob - the FQN (fully qualified name) to BackupJob class; + </listitem> + </varlistentry> + <varlistentry> + <term>JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.BackupJobConfig</literal></term> + <listitem> + <programlisting>{&quot;parameters&quot;:[&lt;JSON to Pair&gt;, ..., &lt;JSON to pair&gt; ],&quot;backupJob&quot;:&quot;&lt;String&gt;&quot;}</programlisting> + <para> + Where: + </para> + <programlisting>backupJob - the FQN (fully qualified name) to BackupJob class; parameters - the list of JSON of Pair.</programlisting> - - </listitem> - - </varlistentry> - <varlistentry> - <term>The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.Pair</literal></term> - <listitem> - -<programlisting language="Java">{"name":"&lt;String&gt;","value":"&lt;String&gt;"}</programlisting> - <para> - Where: - </para> - -<programlisting>name - the name of parameter; + </listitem> + </varlistentry> + <varlistentry> + <term>The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.Pair</literal></term> + <listitem> + <programlisting language="Java">{&quot;name&quot;:&quot;&lt;String&gt;&quot;,&quot;value&quot;:&quot;&lt;String&gt;&quot;}</programlisting> + <para> + Where: + </para> + <programlisting>name - the name of parameter; value - the value of parameter.</programlisting> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns:</term> - <listitem> - <para> - When successful: - </para> - -<programlisting>status code = 200</programlisting> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 404 - the not found repository '{repo}' or workspace '{ws}' + </listitem> + </varlistentry> + <varlistentry> + <term>Returns:</term> + <listitem> + <para> + When successful: + </para> + <programlisting>status code = 200</programlisting> + <para> + When unsuccessful: + </para> + <programlisting>status code = 404 - the not found repository &apos;{repo}&apos; or workspace &apos;{ws}&apos; status code = 500 - the other unknown errors failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Stopping_Backup_Service"> - <title>Stopping Backup Service</title> - <varlistentry> - <term>/rest/jcr-backup/stop/{id}</term> - <listitem> - <para> - Stop backup with identifier {id}. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL:</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/stop/{id}</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - Plain text. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Method</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - {id} - the identifier of backup - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - -<programlisting>status code = 200</programlisting> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 404 - the no active backup with identifier {id} + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Stopping_Backup_Service"> + <title>Stopping Backup Service</title> + <varlistentry> + <term>/rest/jcr-backup/stop/{id}</term> + <listitem> + <para> + Stop backup with identifier {id}. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL:</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/stop/{id}</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + Plain text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Method</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + {id} - the identifier of backup + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <programlisting>status code = 200</programlisting> + <para> + When unsuccessful: + </para> + <programlisting>status code = 404 - the no active backup with identifier {id} status code = 500 - the other unknown errors failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Backup_Info_Service"> - <title>Backup Info Service</title> - <varlistentry> - <term>/rest/jcr-backup/info</term> - <listitem> - <para> - Information about the backup service. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/info</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - json - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Method</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - None - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - <para> - Return the JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.BackupServiceInfoBean</literal> - </para> - -<programlisting>{"backupLogDir":"&lt;String&gt;","defaultIncrementalJobPeriod":&lt;Long&gt;,"fullBackupType":"&lt;String&gt;","incrementalBackupType":"&lt;String&gt;"}</programlisting> - <para> - Where: - </para> - -<programlisting>fullBackupType - the FQN (fully qualified name) of BackupJob class for full backup type; + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Backup_Info_Service"> + <title>Backup Info Service</title> + <varlistentry> + <term>/rest/jcr-backup/info</term> + <listitem> + <para> + Information about the backup service. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/info</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + json + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Method</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + None + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <para> + Return the JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.BackupServiceInfoBean</literal> + </para> + <programlisting>{&quot;backupLogDir&quot;:&quot;&lt;String&gt;&quot;,&quot;defaultIncrementalJobPeriod&quot;:&lt;Long&gt;,&quot;fullBackupType&quot;:&quot;&lt;String&gt;&quot;,&quot;incrementalBackupType&quot;:&quot;&lt;String&gt;&quot;}</programlisting> + <para> + Where: + </para> + <programlisting>fullBackupType - the FQN (fully qualified name) of BackupJob class for full backup type; incrementalBackupType - the FQN (fully qualified name) of BackupJob class for incremental backup type; backupLogDir - path to backup folder; defaultIncrementalJobPeriod - the default incremental job period.</programlisting> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 500 - the unknown error + <para> + When unsuccessful: + </para> + <programlisting>status code = 500 - the unknown error failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Dropping_Workspace_Service"> - <title>Dropping Workspace Service</title> - <varlistentry> - <term>/rest/jcr-backup/drop-workspace/{repo}/{ws}/{force-session-close}</term> - <listitem> - <para> - Delete the workspace from repository /{repo}/{ws}. With this service, you can delete any workspaces regardless of whether the workspace is a backup or has been copied to a backup. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/drop-workspace/{repo}/{ws}/{force-session-close}</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - Plain text. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Methods</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - {repo} - the repository name; - </para> - <para> - {ws} - the workspace name - </para> - <para> - {force-session-close} - the boolean value : <emphasis role="bold">true</emphasis> - the open sessions on workspace will be closed; <emphasis role="bold">false</emphasis> - will not close open sessions. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - -<programlisting>status code = 200</programlisting> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 500 - the other unknown errors; - - not found repository '{repo}' or workspace '{ws}' + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Dropping_Workspace_Service"> + <title>Dropping Workspace Service</title> + <varlistentry> + <term>/rest/jcr-backup/drop-workspace/{repo}/{ws}/{force-session-close}</term> + <listitem> + <para> + Delete the workspace from repository /{repo}/{ws}. With this service, you can delete any workspaces regardless of whether the workspace is a backup or has been copied to a backup. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/drop-workspace/{repo}/{ws}/{force-session-close}</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + Plain text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Methods</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + {repo} - the repository name; + </para> + <para> + {ws} - the workspace name + </para> + <para> + {force-session-close} - the boolean value : <emphasis role="bold">true</emphasis> - the open sessions on workspace will be closed; <emphasis role="bold">false</emphasis> - will not close open sessions. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <programlisting>status code = 200</programlisting> + <para> + When unsuccessful: + </para> + <programlisting>status code = 500 - the other unknown errors; + - not found repository &apos;{repo}&apos; or workspace &apos;{ws}&apos; failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Backup_Info"> - <title>Backup Info</title> - <varlistentry> - <term>/rest/jcr-backup/info/backup</term> - <listitem> - <para> - Information about the current and completed backups. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/info/backup</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - json - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Method</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - None. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - <para> - The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList</literal>: - </para> - -<programlisting>{"backups":[&lt;JSON to ShortInfo&gt;,&lt;JSON to ShortInfo&gt;,...,&lt;JSON to ShortInfo&gt;]}</programlisting> - <para> - The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfo</literal>: - </para> - -<programlisting>{"startedTime":"&lt;String&gt;","backupId":"&lt;String&gt;","type":&lt;Integer&gt;,"state":&lt;Integer&gt;,"backupType":&lt;Integer&gt;, -"workspaceName":"&lt;String&gt;","finishedTime":"&lt;String&gt;","repositoryName":"&lt;String&gt;"}</programlisting> - <para> - Where: - </para> - -<programlisting>type - the type of ShortInfo : + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Backup_Info"> + <title>Backup Info</title> + <varlistentry> + <term>/rest/jcr-backup/info/backup</term> + <listitem> + <para> + Information about the current and completed backups. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/info/backup</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + json + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Method</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + None. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <para> + The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList</literal>: + </para> + <programlisting>{&quot;backups&quot;:[&lt;JSON to ShortInfo&gt;,&lt;JSON to ShortInfo&gt;,...,&lt;JSON to ShortInfo&gt;]}</programlisting> + <para> + The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfo</literal>: + </para> + <programlisting>{&quot;startedTime&quot;:&quot;&lt;String&gt;&quot;,&quot;backupId&quot;:&quot;&lt;String&gt;&quot;,&quot;type&quot;:&lt;Integer&gt;,&quot;state&quot;:&lt;Integer&gt;,&quot;backupType&quot;:&lt;Integer&gt;, +&quot;workspaceName&quot;:&quot;&lt;String&gt;&quot;,&quot;finishedTime&quot;:&quot;&lt;String&gt;&quot;,&quot;repositoryName&quot;:&quot;&lt;String&gt;&quot;}</programlisting> + <para> + Where: + </para> + <programlisting>type - the type of ShortInfo : 0 - the ShorInfo to completed backup; -1 - the ShorInfo to current (active) backup. 1 - the ShorInfo to current restore. @@ -575,10 +470,10 @@ backupId - the identifier of backup; workspaceName - the name of workspace; repositoryName - the name of repository. -startedTime - the date of started backup. The date in format RFC 1123 (for examle "Thu, 16 Apr 2009 14:56:49 EEST"). +startedTime - the date of started backup. The date in format RFC 1123 (for examle &quot;Thu, 16 Apr 2009 14:56:49 EEST&quot;). The ShorInfo to current (active) backup : - finishedTime - no applicable, always an empty string (""); + finishedTime - no applicable, always an empty string (&quot;&quot;); state - the state of full backup : 0 - starting; 1 - waiting; @@ -596,310 +491,252 @@ 2 - successful; 3 - failure; 4 - initialized.</programlisting> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 500 - the unknown error + <para> + When unsuccessful: + </para> + <programlisting>status code = 500 - the unknown error failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Current_Backups_Information"> - <title>Current Backups Information</title> - <varlistentry> - <term>/rest/jcr-backup/info/backup/current</term> - <listitem> - <para> - Information about the current backups. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/info/backup/current</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - json - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Method</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - None. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - <para> - The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList</literal> (see the <emphasis>role="bold"&gt;/rest/jcr-backup/info/backup</emphasis> item) - </para> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 500 - the unknown error + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Current_Backups_Information"> + <title>Current Backups Information</title> + <varlistentry> + <term>/rest/jcr-backup/info/backup/current</term> + <listitem> + <para> + Information about the current backups. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/info/backup/current</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + json + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Method</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + None. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <para> + The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList</literal> (see the <emphasis>role=&quot;bold&quot;&gt;/rest/jcr-backup/info/backup</emphasis> item) + </para> + <para> + When unsuccessful: + </para> + <programlisting>status code = 500 - the unknown error failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Completed_Backups_Information"> - <title>Completed Backups Information</title> - <varlistentry> - <term>/rest/jcr-backup/info/backup/completed</term> - <listitem> - <para> - Information about the completed backups. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/info/backup/completed</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - json - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Method</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - None - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - <para> - The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList</literal> (see item <emphasis role="bold">/rest/jcr-backup/info/backup</emphasis>). - </para> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 500 - the unknown error + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Completed_Backups_Information"> + <title>Completed Backups Information</title> + <varlistentry> + <term>/rest/jcr-backup/info/backup/completed</term> + <listitem> + <para> + Information about the completed backups. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/info/backup/completed</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + json + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Method</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + None + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <para> + The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList</literal> (see item <emphasis role="bold">/rest/jcr-backup/info/backup</emphasis>). + </para> + <para> + When unsuccessful: + </para> + <programlisting>status code = 500 - the unknown error failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Workspace_specific_Backup_Information"> - <title>Workspace-specific Backup Information</title> - <varlistentry> - <term>/rest/jcr-backup/info/backup/{repo}/{ws}</term> - <listitem> - <para> - Information about the current and completed backups for specific workspace. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URI</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/info/backup/{repo}/{ws}</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - json - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Method</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - {repo} - the repository name - </para> - <para> - {ws} - the workspace name - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - <para> - The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList</literal> (see item <emphasis role="bold">/rest/jcr-backup/info/backup</emphasis>). - </para> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 500 - the unknown error + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Workspace_specific_Backup_Information"> + <title>Workspace-specific Backup Information</title> + <varlistentry> + <term>/rest/jcr-backup/info/backup/{repo}/{ws}</term> + <listitem> + <para> + Information about the current and completed backups for specific workspace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URI</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/info/backup/{repo}/{ws}</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + json + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Method</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + {repo} - the repository name + </para> + <para> + {ws} - the workspace name + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <para> + The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList</literal> (see item <emphasis role="bold">/rest/jcr-backup/info/backup</emphasis>). + </para> + <para> + When unsuccessful: + </para> + <programlisting>status code = 500 - the unknown error failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Single_Backup_Information"> - <title>Single Backup Information</title> - <varlistentry> - <term>/rest/jcr-backup/info/backup/{id}</term> - <listitem> - <para> - Detailed information about a current or completed backup with identifier '{id}'. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/info/backup/{id}</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - json - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Method</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - {id} - the identifier of backup. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - <para> - The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.DetailedInfo</literal>: - </para> - -<programlisting>{"backupConfig":&lt;JSON to BackupConfigBean&gt;,"startedTime":"&lt;String&gt;","backupId":"&lt;String&gt;","type":&lt;Integer&gt;, -"state":&lt;Integer&gt;,"backupType":&lt;Integer&gt;,"workspaceName":"&lt;String&gt;","finishedTime":"&lt;String&gt;", -"repositoryName":"&lt;String&gt;"}</programlisting> - <para> - Where: - </para> - -<programlisting>type - the type of DetailedInfo : + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Single_Backup_Information"> + <title>Single Backup Information</title> + <varlistentry> + <term>/rest/jcr-backup/info/backup/{id}</term> + <listitem> + <para> + Detailed information about a current or completed backup with identifier &apos;{id}&apos;. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/info/backup/{id}</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + json + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Method</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + {id} - the identifier of backup. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <para> + The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.DetailedInfo</literal>: + </para> + <programlisting>{&quot;backupConfig&quot;:&lt;JSON to BackupConfigBean&gt;,&quot;startedTime&quot;:&quot;&lt;String&gt;&quot;,&quot;backupId&quot;:&quot;&lt;String&gt;&quot;,&quot;type&quot;:&lt;Integer&gt;, +&quot;state&quot;:&lt;Integer&gt;,&quot;backupType&quot;:&lt;Integer&gt;,&quot;workspaceName&quot;:&quot;&lt;String&gt;&quot;,&quot;finishedTime&quot;:&quot;&lt;String&gt;&quot;, +&quot;repositoryName&quot;:&quot;&lt;String&gt;&quot;}</programlisting> + <para> + Where: + </para> + <programlisting>type - the type of DetailedInfo : 0 - the DetailedInfo to completed backup; -1 - the DetailedInfo to current (active) backup; 1 - the DetailedInfo to restore. @@ -912,553 +749,486 @@ backupConfig - the JSON to BackupConfigBean. The DetailedInfo to current (active) backup : - startedTime - the date of started backup. The date in format RFC 1123 (for examle "Thu, 16 Apr 2009 14:56:49 EEST"); - finishedTime - no applicable, always an empty string (""); + startedTime - the date of started backup. The date in format RFC 1123 (for examle &quot;Thu, 16 Apr 2009 14:56:49 EEST&quot;); + finishedTime - no applicable, always an empty string (&quot;&quot;); state - the state of full backup : 0 - starting; 1 - waiting; 2 - working; 4 - finished. The DetailedInfo to completed backup : - startedTime - the date of started backup. The date in format RFC 1123 (for examle "Thu, 16 Apr 2009 14:56:49 EEST"); + startedTime - the date of started backup. The date in format RFC 1123 (for examle &quot;Thu, 16 Apr 2009 14:56:49 EEST&quot;); finishedTime - the date of finished backup. The date in format RFC 1123; state - no applicable, always zero (0). The DetailedInfo to restore : - startedTime - the date of started restore. The date in format RFC 1123 (for examle "Thu, 16 Apr 2009 14:56:49 EEST"); + startedTime - the date of started restore. The date in format RFC 1123 (for examle &quot;Thu, 16 Apr 2009 14:56:49 EEST&quot;); finishedTime - the date of finished restore; state - the state of restore : 1 - started; 2 - successful; 3 - failure; 4 - initialized.</programlisting> - <para> - The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.BackupConfigBean</literal> (see item <emphasis role="bold">/rest/jcr-backup/start/{repo}/{ws}</emphasis>). - </para> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 404 - not found the backup with {id} + <para> + The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.BackupConfigBean</literal> (see item <emphasis role="bold">/rest/jcr-backup/start/{repo}/{ws}</emphasis>). + </para> + <para> + When unsuccessful: + </para> + <programlisting>status code = 404 - not found the backup with {id} status code = 500 - the unknown error failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Restores_on_a_Workspace_Information"> - <title>Restores on a Workspace Information</title> - <varlistentry> - <term>/rest/jcr-backup/info/restore/{repo}/{ws}</term> - <listitem> - <para> - The information about the last restore on a specific workspace <literal>/{repo}/{ws}</literal>. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/info/restore/{repo}/{ws}</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - json - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Methods</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - {repo} - the repository name. - </para> - <para> - {ws} - the workspace name. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - <para> - The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.DetailedInfo</literal> (see item <emphasis role="bold">/rest/jcr-backup/info/backup/{id}</emphasis>). - </para> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 404 - the not found the restore for workspace /{repo}/{ws} + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Restores_on_a_Workspace_Information"> + <title>Restores on a Workspace Information</title> + <varlistentry> + <term>/rest/jcr-backup/info/restore/{repo}/{ws}</term> + <listitem> + <para> + The information about the last restore on a specific workspace <literal>/{repo}/{ws}</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/info/restore/{repo}/{ws}</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + json + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Methods</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + {repo} - the repository name. + </para> + <para> + {ws} - the workspace name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <para> + The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.DetailedInfo</literal> (see item <emphasis role="bold">/rest/jcr-backup/info/backup/{id}</emphasis>). + </para> + <para> + When unsuccessful: + </para> + <programlisting>status code = 404 - the not found the restore for workspace /{repo}/{ws} status code = 500 - the unknown error failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Restores_Information"> - <title>Restores Information</title> - <varlistentry> - <term>/rest/jcr-backup/info/restores</term> - <listitem> - <para> - The information about the last restores. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/info/restores</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - json - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Methods</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - None. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - <para> - The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList</literal> (see item <emphasis role="bold">/rest/jcr-backup/info/backup</emphasis>). - </para> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 500 - the unknown error + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Restores_Information"> + <title>Restores Information</title> + <varlistentry> + <term>/rest/jcr-backup/info/restores</term> + <listitem> + <para> + The information about the last restores. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/info/restores</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + json + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Methods</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + None. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <para> + The JSON bean of <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfoList</literal> (see item <emphasis role="bold">/rest/jcr-backup/info/backup</emphasis>). + </para> + <para> + When unsuccessful: + </para> + <programlisting>status code = 500 - the unknown error failure message in response - the description of failure</programlisting> + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Restoring_Service"> + <title>Restoring Service</title> + <varlistentry> + <term>/rest/jcr-backup/restore/{repo}/{id}</term> + <listitem> + <para> + Restore the workspace from specific backup. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/restore/{repo}/{id}</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + json + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Methods</term> + <listitem> + <para> + <literal>POST</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + {repo} - the repository name; + </para> + <para> + {id} - the identifier to backup; * WorkspaceEntry - the JSON to WorkspaceEntry. + </para> + <para> + The RestoreBean: + </para> + <programlisting>header : +&quot;Content-Type&quot; = &quot;application/json; charset=UTF-8&quot; - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Restoring_Service"> - <title>Restoring Service</title> - <varlistentry> - <term>/rest/jcr-backup/restore/{repo}/{id}</term> - <listitem> - <para> - Restore the workspace from specific backup. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/restore/{repo}/{id}</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - json - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Methods</term> - <listitem> - <para> - <literal>POST</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - {repo} - the repository name; - </para> - <para> - {id} - the identifier to backup; * WorkspaceEntry - the JSON to WorkspaceEntry. - </para> - <para> - The RestoreBean: - </para> - -<programlisting>header : -"Content-Type" = "application/json; charset=UTF-8" - body: &lt;JSON to WorkspaceEntry&gt;</programlisting> - <para> - The example of JSON bean to <literal>org.exoplatform.services.jcr.config.WorkspaceEntry</literal>: - </para> - -<programlisting>{ "accessManager" : null, - "autoInitPermissions" : null, - "autoInitializedRootNt" : null, - "cache" : { "parameters" : [ { "name" : "max-size", - "value" : "10k" + <para> + The example of JSON bean to <literal>org.exoplatform.services.jcr.config.WorkspaceEntry</literal>: + </para> + <programlisting>{ &quot;accessManager&quot; : null, + &quot;autoInitPermissions&quot; : null, + &quot;autoInitializedRootNt&quot; : null, + &quot;cache&quot; : { &quot;parameters&quot; : [ { &quot;name&quot; : &quot;max-size&quot;, + &quot;value&quot; : &quot;10k&quot; }, - { "name" : "live-time", - "value" : "1h" + { &quot;name&quot; : &quot;live-time&quot;, + &quot;value&quot; : &quot;1h&quot; } ], - "type" : "org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl" + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl&quot; }, - "container" : { "parameters" : [ { "name" : "source-name", - "value" : "jdbcjcr" + &quot;container&quot; : { &quot;parameters&quot; : [ { &quot;name&quot; : &quot;source-name&quot;, + &quot;value&quot; : &quot;jdbcjcr&quot; }, - { "name" : "dialect", - "value" : "hsqldb" + { &quot;name&quot; : &quot;dialect&quot;, + &quot;value&quot; : &quot;hsqldb&quot; }, - { "name" : "multi-db", - "value" : "false" + { &quot;name&quot; : &quot;multi-db&quot;, + &quot;value&quot; : &quot;false&quot; }, - { "name" : "update-storage", - "value" : "false" + { &quot;name&quot; : &quot;update-storage&quot;, + &quot;value&quot; : &quot;false&quot; }, - { "name" : "max-buffer-size", - "value" : "200k" + { &quot;name&quot; : &quot;max-buffer-size&quot;, + &quot;value&quot; : &quot;200k&quot; }, - { "name" : "swap-directory", - "value" : "../temp/swap/production" + { &quot;name&quot; : &quot;swap-directory&quot;, + &quot;value&quot; : &quot;../temp/swap/production&quot; } ], - "type" : "org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer", - "valueStorages" : [ { "filters" : [ { "ancestorPath" : null, - "minValueSize" : 0, - "propertyName" : null, - "propertyType" : "Binary" + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer&quot;, + &quot;valueStorages&quot; : [ { &quot;filters&quot; : [ { &quot;ancestorPath&quot; : null, + &quot;minValueSize&quot; : 0, + &quot;propertyName&quot; : null, + &quot;propertyType&quot; : &quot;Binary&quot; } ], - "id" : "system", - "parameters" : [ { "name" : "path", - "value" : "../temp/values/production" + &quot;id&quot; : &quot;system&quot;, + &quot;parameters&quot; : [ { &quot;name&quot; : &quot;path&quot;, + &quot;value&quot; : &quot;../temp/values/production&quot; } ], - "type" : "org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage" + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage&quot; } ] }, - "initializer" : { "parameters" : [ { "name" : "root-nodetype", - "value" : "nt:unstructured" + &quot;initializer&quot; : { &quot;parameters&quot; : [ { &quot;name&quot; : &quot;root-nodetype&quot;, + &quot;value&quot; : &quot;nt:unstructured&quot; } ], - "type" : "org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer" + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer&quot; }, - "lockManager" : { "persister" : { "parameters" : [ { "name" : "path", - "value" : "../temp/lock/system" + &quot;lockManager&quot; : { &quot;persister&quot; : { &quot;parameters&quot; : [ { &quot;name&quot; : &quot;path&quot;, + &quot;value&quot; : &quot;../temp/lock/system&quot; } ], - "type" : "org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister" + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister&quot; }, - "timeout" : 15728640 + &quot;timeout&quot; : 15728640 }, - "name" : "production", - "queryHandler" : { "analyzer" : { }, - "autoRepair" : true, - "bufferSize" : 10, - "cacheSize" : 1000, - "documentOrder" : true, - "errorLogSize" : 50, - "excerptProviderClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt", - "excludedNodeIdentifers" : null, - "extractorBackLogSize" : 100, - "extractorPoolSize" : 0, - "extractorTimeout" : 100, - "indexDir" : "../temp/jcrlucenedb/production", - "indexingConfigurationClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfigurationImpl", - "indexingConfigurationPath" : null, - "maxFieldLength" : 10000, - "maxMergeDocs" : 2147483647, - "mergeFactor" : 10, - "minMergeDocs" : 100, - "parameters" : [ { "name" : "index-dir", - "value" : "../temp/jcrlucenedb/production" + &quot;name&quot; : &quot;production&quot;, + &quot;queryHandler&quot; : { &quot;analyzer&quot; : { }, + &quot;autoRepair&quot; : true, + &quot;bufferSize&quot; : 10, + &quot;cacheSize&quot; : 1000, + &quot;documentOrder&quot; : true, + &quot;errorLogSize&quot; : 50, + &quot;excerptProviderClass&quot; : &quot;org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt&quot;, + &quot;excludedNodeIdentifers&quot; : null, + &quot;extractorBackLogSize&quot; : 100, + &quot;extractorPoolSize&quot; : 0, + &quot;extractorTimeout&quot; : 100, + &quot;indexDir&quot; : &quot;../temp/jcrlucenedb/production&quot;, + &quot;indexingConfigurationClass&quot; : &quot;org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfigurationImpl&quot;, + &quot;indexingConfigurationPath&quot; : null, + &quot;maxFieldLength&quot; : 10000, + &quot;maxMergeDocs&quot; : 2147483647, + &quot;mergeFactor&quot; : 10, + &quot;minMergeDocs&quot; : 100, + &quot;parameters&quot; : [ { &quot;name&quot; : &quot;index-dir&quot;, + &quot;value&quot; : &quot;../temp/jcrlucenedb/production&quot; } ], - "queryClass" : "org.exoplatform.services.jcr.impl.core.query.QueryImpl", - "queryHandler" : null, - "resultFetchSize" : 2147483647, - "rootNodeIdentifer" : "00exo0jcr0root0uuid0000000000000", - "spellCheckerClass" : null, - "supportHighlighting" : false, - "synonymProviderClass" : null, - "synonymProviderConfigPath" : null, - "type" : "org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex", - "useCompoundFile" : false, - "volatileIdleTime" : 3 + &quot;queryClass&quot; : &quot;org.exoplatform.services.jcr.impl.core.query.QueryImpl&quot;, + &quot;queryHandler&quot; : null, + &quot;resultFetchSize&quot; : 2147483647, + &quot;rootNodeIdentifer&quot; : &quot;00exo0jcr0root0uuid0000000000000&quot;, + &quot;spellCheckerClass&quot; : null, + &quot;supportHighlighting&quot; : false, + &quot;synonymProviderClass&quot; : null, + &quot;synonymProviderConfigPath&quot; : null, + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex&quot;, + &quot;useCompoundFile&quot; : false, + &quot;volatileIdleTime&quot; : 3 }, - "uniqueName" : "repository_production" + &quot;uniqueName&quot; : &quot;repository_production&quot; }</programlisting> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - -<programlisting>status code = 200</programlisting> - <para> - Return the JSON bean <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfo</literal> of just started restore. For JSON description see item <emphasis role="bold">/rest/jcr-backup/info/backup</emphasis>. - </para> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 403 - the already was restore to workspace /{repo}/{ws} -status code = 404 - the not found repository '{repo}' or unsupported encoding to workspaceConfig + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <programlisting>status code = 200</programlisting> + <para> + Return the JSON bean <literal>org.exoplatform.services.jcr.ext.backup.server.bean.response.ShortInfo</literal> of just started restore. For JSON description see item <emphasis role="bold">/rest/jcr-backup/info/backup</emphasis>. + </para> + <para> + When unsuccessful: + </para> + <programlisting>status code = 403 - the already was restore to workspace /{repo}/{ws} +status code = 404 - the not found repository &apos;{repo}&apos; or unsupported encoding to workspaceConfig status code = 500 - the other unknown errors failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - <variablelist id="vari-Reference_Guide-Methods-Default_Workspace_Information"> - <title>Default Workspace Information</title> - <varlistentry> - <term>/rest/jcr-backup/info/default-ws-config</term> - <listitem> - <para> - Will be returned the JSON bean to WorkspaceEntry for default workspace. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>URL</term> - <listitem> - <para> - <uri>http://host:port/rest/jcr-backup/info/default-ws-config</uri> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Formats</term> - <listitem> - <para> - json - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Methods</term> - <listitem> - <para> - <literal>GET</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Parameters</term> - <listitem> - <para> - None. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Returns</term> - <listitem> - <para> - When successful: - </para> - <para> - The JSON bean to <literal>org.exoplatform.services.jcr.config.WorkspaceEntry</literal>: - </para> - -<programlisting>{ "accessManager" : null, - "autoInitPermissions" : null, - "autoInitializedRootNt" : null, - "cache" : { "parameters" : [ { "name" : "max-size", - "value" : "10k" + </listitem> + </varlistentry> + </variablelist> + <variablelist id="vari-Reference_Guide-Methods-Default_Workspace_Information"> + <title>Default Workspace Information</title> + <varlistentry> + <term>/rest/jcr-backup/info/default-ws-config</term> + <listitem> + <para> + Will be returned the JSON bean to WorkspaceEntry for default workspace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>URL</term> + <listitem> + <para> + <uri>http://host:port/rest/jcr-backup/info/default-ws-config</uri> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Formats</term> + <listitem> + <para> + json + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Methods</term> + <listitem> + <para> + <literal>GET</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Parameters</term> + <listitem> + <para> + None. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Returns</term> + <listitem> + <para> + When successful: + </para> + <para> + The JSON bean to <literal>org.exoplatform.services.jcr.config.WorkspaceEntry</literal>: + </para> + <programlisting>{ &quot;accessManager&quot; : null, + &quot;autoInitPermissions&quot; : null, + &quot;autoInitializedRootNt&quot; : null, + &quot;cache&quot; : { &quot;parameters&quot; : [ { &quot;name&quot; : &quot;max-size&quot;, + &quot;value&quot; : &quot;10k&quot; }, - { "name" : "live-time", - "value" : "1h" + { &quot;name&quot; : &quot;live-time&quot;, + &quot;value&quot; : &quot;1h&quot; } ], - "type" : "org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl" + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl&quot; }, - "container" : { "parameters" : [ { "name" : "source-name", - "value" : "jdbcjcr" + &quot;container&quot; : { &quot;parameters&quot; : [ { &quot;name&quot; : &quot;source-name&quot;, + &quot;value&quot; : &quot;jdbcjcr&quot; }, - { "name" : "dialect", - "value" : "hsqldb" + { &quot;name&quot; : &quot;dialect&quot;, + &quot;value&quot; : &quot;hsqldb&quot; }, - { "name" : "multi-db", - "value" : "false" + { &quot;name&quot; : &quot;multi-db&quot;, + &quot;value&quot; : &quot;false&quot; }, - { "name" : "update-storage", - "value" : "false" + { &quot;name&quot; : &quot;update-storage&quot;, + &quot;value&quot; : &quot;false&quot; }, - { "name" : "max-buffer-size", - "value" : "200k" + { &quot;name&quot; : &quot;max-buffer-size&quot;, + &quot;value&quot; : &quot;200k&quot; }, - { "name" : "swap-directory", - "value" : "../temp/swap/production" + { &quot;name&quot; : &quot;swap-directory&quot;, + &quot;value&quot; : &quot;../temp/swap/production&quot; } ], - "type" : "org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer", - "valueStorages" : [ { "filters" : [ { "ancestorPath" : null, - "minValueSize" : 0, - "propertyName" : null, - "propertyType" : "Binary" + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer&quot;, + &quot;valueStorages&quot; : [ { &quot;filters&quot; : [ { &quot;ancestorPath&quot; : null, + &quot;minValueSize&quot; : 0, + &quot;propertyName&quot; : null, + &quot;propertyType&quot; : &quot;Binary&quot; } ], - "id" : "system", - "parameters" : [ { "name" : "path", - "value" : "../temp/values/production" + &quot;id&quot; : &quot;system&quot;, + &quot;parameters&quot; : [ { &quot;name&quot; : &quot;path&quot;, + &quot;value&quot; : &quot;../temp/values/production&quot; } ], - "type" : "org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage" + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage&quot; } ] }, - "initializer" : { "parameters" : [ { "name" : "root-nodetype", - "value" : "nt:unstructured" + &quot;initializer&quot; : { &quot;parameters&quot; : [ { &quot;name&quot; : &quot;root-nodetype&quot;, + &quot;value&quot; : &quot;nt:unstructured&quot; } ], - "type" : "org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer" + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer&quot; }, - "lockManager" : { "persister" : { "parameters" : [ { "name" : "path", - "value" : "../temp/lock/system" + &quot;lockManager&quot; : { &quot;persister&quot; : { &quot;parameters&quot; : [ { &quot;name&quot; : &quot;path&quot;, + &quot;value&quot; : &quot;../temp/lock/system&quot; } ], - "type" : "org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister" + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister&quot; }, - "timeout" : 15728640 + &quot;timeout&quot; : 15728640 }, - "name" : "production", - "queryHandler" : { "analyzer" : { }, - "autoRepair" : true, - "bufferSize" : 10, - "cacheSize" : 1000, - "documentOrder" : true, - "errorLogSize" : 50, - "excerptProviderClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt", - "excludedNodeIdentifers" : null, - "extractorBackLogSize" : 100, - "extractorPoolSize" : 0, - "extractorTimeout" : 100, - "indexDir" : "../temp/jcrlucenedb/production", - "indexingConfigurationClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfigurationImpl", - "indexingConfigurationPath" : null, - "maxFieldLength" : 10000, - "maxMergeDocs" : 2147483647, - "mergeFactor" : 10, - "minMergeDocs" : 100, - "parameters" : [ { "name" : "index-dir", - "value" : "../temp/jcrlucenedb/production" + &quot;name&quot; : &quot;production&quot;, + &quot;queryHandler&quot; : { &quot;analyzer&quot; : { }, + &quot;autoRepair&quot; : true, + &quot;bufferSize&quot; : 10, + &quot;cacheSize&quot; : 1000, + &quot;documentOrder&quot; : true, + &quot;errorLogSize&quot; : 50, + &quot;excerptProviderClass&quot; : &quot;org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt&quot;, + &quot;excludedNodeIdentifers&quot; : null, + &quot;extractorBackLogSize&quot; : 100, + &quot;extractorPoolSize&quot; : 0, + &quot;extractorTimeout&quot; : 100, + &quot;indexDir&quot; : &quot;../temp/jcrlucenedb/production&quot;, + &quot;indexingConfigurationClass&quot; : &quot;org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfigurationImpl&quot;, + &quot;indexingConfigurationPath&quot; : null, + &quot;maxFieldLength&quot; : 10000, + &quot;maxMergeDocs&quot; : 2147483647, + &quot;mergeFactor&quot; : 10, + &quot;minMergeDocs&quot; : 100, + &quot;parameters&quot; : [ { &quot;name&quot; : &quot;index-dir&quot;, + &quot;value&quot; : &quot;../temp/jcrlucenedb/production&quot; } ], - "queryClass" : "org.exoplatform.services.jcr.impl.core.query.QueryImpl", - "queryHandler" : null, - "resultFetchSize" : 2147483647, - "rootNodeIdentifer" : "00exo0jcr0root0uuid0000000000000", - "spellCheckerClass" : null, - "supportHighlighting" : false, - "synonymProviderClass" : null, - "synonymProviderConfigPath" : null, - "type" : "org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex", - "useCompoundFile" : false, - "volatileIdleTime" : 3 + &quot;queryClass&quot; : &quot;org.exoplatform.services.jcr.impl.core.query.QueryImpl&quot;, + &quot;queryHandler&quot; : null, + &quot;resultFetchSize&quot; : 2147483647, + &quot;rootNodeIdentifer&quot; : &quot;00exo0jcr0root0uuid0000000000000&quot;, + &quot;spellCheckerClass&quot; : null, + &quot;supportHighlighting&quot; : false, + &quot;synonymProviderClass&quot; : null, + &quot;synonymProviderConfigPath&quot; : null, + &quot;type&quot; : &quot;org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex&quot;, + &quot;useCompoundFile&quot; : false, + &quot;volatileIdleTime&quot; : 3 }, - "uniqueName" : "repository_production" + &quot;uniqueName&quot; : &quot;repository_production&quot; }</programlisting> - <para> - When unsuccessful: - </para> - -<programlisting>status code = 500 - the unknown error + <para> + When unsuccessful: + </para> + <programlisting>status code = 500 - the unknown error failure message in response - the description of failure</programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - <section id="sect-Reference_Guide-HTTPBackupAgent_-HTTPBackupAgent_Configuration"> - <title>HTTPBackupAgent Configuration</title> - <para> - Add the components <literal>org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent</literal> and <literal>org.exoplatform.services.jcr.ext.backup.BackupManager</literal> to services configuration: - </para> - -<programlisting language="XML">&lt;component&gt; + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-HTTPBackupAgent_-HTTPBackupAgent_Configuration"> + <title>HTTPBackupAgent Configuration</title> + <para> + Add the components <literal>org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent</literal> and <literal>org.exoplatform.services.jcr.ext.backup.BackupManager</literal> to services configuration: + </para> + <programlisting language="XML">&lt;component&gt; &lt;type&gt;org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent&lt;/type&gt; &lt;/component&gt; @@ -1472,15 +1242,14 @@ &lt;init-params&gt; &lt;properties-param&gt; &lt;name&gt;backup-properties&lt;/name&gt; - &lt;property name="backup-dir" value="../temp/backup" /&gt; + &lt;property name=&quot;backup-dir&quot; value=&quot;../temp/backup&quot; /&gt; &lt;/properties-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> - <para> - In case, if you will restore backup in same workspace (so you will drop previous workspace), you need configure <literal>RepositoryServiceConfiguration</literal> in order to save the changes of the repository configuration. For example: - </para> - -<programlisting language="XML">&lt;component&gt; + <para> + In case, if you will restore backup in same workspace (so you will drop previous workspace), you need configure <literal>RepositoryServiceConfiguration</literal> in order to save the changes of the repository configuration. For example: + </para> + <programlisting language="XML">&lt;component&gt; &lt;key&gt;org.exoplatform.services.jcr.config.RepositoryServiceConfiguration&lt;/key&gt; &lt;type&gt;org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl&lt;/type&gt; &lt;init-params&gt; @@ -1492,51 +1261,45 @@ &lt;properties-param&gt; &lt;name&gt;working-conf&lt;/name&gt; &lt;description&gt;working-conf&lt;/description&gt; - &lt;property name="source-name" value="jdbcjcr" /&gt; - &lt;property name="dialect" value="hsqldb" /&gt; - &lt;property name="persister-class-name" value="org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister" /&gt; + &lt;property name=&quot;source-name&quot; value=&quot;jdbcjcr&quot; /&gt; + &lt;property name=&quot;dialect&quot; value=&quot;hsqldb&quot; /&gt; + &lt;property name=&quot;persister-class-name&quot; value=&quot;org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister&quot; /&gt; &lt;/properties-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> - - </section> - - - </section> - - <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Backup_Client"> - <title>Backup Client</title> - <note> - <para> - For JBoss Enterprise Portal Platform you should use context "<emphasis>/portal/rest</emphasis>". JBoss Enterprise Portal Platform uses form authentication, so first you need to login (url to form authentication is <uri>http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/<replaceable>portal</replaceable>/login</uri>) and then perform requests. - </para> - <para> - The backup client supports form authentication. For example, the following would call the <emphasis>info</emphasis> command with form authentication to JBoss Enterprise Portal Platform : - </para> - <para> - <command>./jcrbackup.sh http://127.0.0.1:8080/portal/rest form POST "/portal/login?initialURI=/portal/private&amp;username=root&amp;password=gtn" info</command> - </para> - - </note> - <para> - The backup client is a console application. - </para> - <para> - The backup client is an <literal>HTTP</literal> client for <literal>HTTPBackupAgent</literal>. - </para> - <para> - Command signature: - </para> - -<screen>Help info: + </section> + </section> + <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Backup_Client"> + <title>Backup Client</title> + <note> + <para> + For JBoss Enterprise Portal Platform you should use context &quot;<emphasis>/portal/rest</emphasis>&quot;. JBoss Enterprise Portal Platform uses form authentication, so first you need to login (URL to form authentication is <uri>http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/<replaceable>portal</replaceable>/login</uri>) and then perform requests. + </para> + <para> + The backup client supports form authentication. For example, the following would call the <emphasis>info</emphasis> command with form authentication to JBoss Enterprise Portal Platform : + </para> + <para> + <command>./jcrbackup.sh http://127.0.0.1:8080/portal/rest form POST &quot;/portal/login?initialURI=/portal/private&amp;username=root&amp;password=gtn&quot; info</command> + </para> + </note> + <para> + The backup client is a console application. + </para> + <para> + The backup client is an <literal>HTTP</literal> client for <literal>HTTPBackupAgent</literal>. + </para> + <para> + Command signature: + </para> + <screen>Help info: &lt;url_basic_authentication&gt;|&lt;url form authentication&gt; &lt;cmd&gt; &lt;url_basic_authentication&gt; : http(s)//login:password@host:port/&lt;context&gt; - &lt;url form authentication&gt; : http(s)//host:port/&lt;context&gt; "&lt;form auth parm&gt;" + &lt;url form authentication&gt; : http(s)//host:port/&lt;context&gt; &quot;&lt;form auth parm&gt;&quot; &lt;form auth parm&gt; : form &lt;method&gt; &lt;form path&gt; &lt;method&gt; : POST or GET &lt;form path&gt; : /path/path?&lt;paramName1&gt;=&lt;paramValue1&gt;&amp;&lt;paramName2&gt;=&lt;paramValue2&gt;... - Example to &lt;url form authentication&gt; : http://127.0.0.1:8080/portal/rest form POST "/portal/login?initialURI=/portal/private&amp;username=root&amp;password=gtn" + Example to &lt;url form authentication&gt; : http://127.0.0.1:8080/portal/rest form POST &quot;/portal/login?initialURI=/portal/private&amp;username=root&amp;password=gtn&quot; &lt;cmd&gt; : start &lt;repo[/ws]&gt; &lt;backup_dir&gt; [&lt;incr&gt;] stop &lt;backup_id&gt; @@ -1550,7 +1313,7 @@ start - start backup of repository or workspace stop - stop backup - status - information about the current or completed backup by 'backup_id' + status - information about the current or completed backup by &apos;backup_id&apos; restores - information about the last restore on specific repository or workspace restore - restore the repository or workspace from specific backup list - information about the current backups (in progress) @@ -1559,11 +1322,11 @@ drop - delete the repository or workspace help - print help information about backup console - &lt;repo[/ws]&gt; - /&lt;reponsitory-name&gt;[/&lt;workspace-name&gt;] the repository or workspace + &lt;repo[/ws]&gt; - /&lt;repository-name&gt;[/&lt;workspace-name&gt;] the repository or workspace &lt;backup_dir&gt; - path to folder for backup on remote server &lt;backup_id&gt; - the identifier for backup &lt;backup_set_dir&gt; - path to folder with backup set on remote server - &lt;incr&gt; - incemental job period + &lt;incr&gt; - incremental job period &lt;pathToConfigFile&gt; - path (local) to repository or workspace configuration remove-exists - remove fully (db, value storage, index) exists repository/workspace force-close-session - close opened sessions on repository or workspace. @@ -1581,109 +1344,90 @@ 10. restore &lt;repo&gt; &lt;backup_set_path&gt; &lt;pathToConfigFile&gt; 11. restore &lt;backup_id&gt; 12. restore &lt;backup_set_path&gt;</screen> - - </section> - - <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Building_and_Running_Application"> - <title>Building and Running Application</title> - <note> - <title>Document Convention</title> - <para> - <filename><replaceable>&lt;JCR_SRC_HOME&gt;</replaceable></filename> the path where eXo JCR sources are located. - </para> - - </note> - <procedure> - <title></title> - <step> - <para> - Navigate to the backup client directory; <filename><replaceable>&lt;JCR_SRC_HOME&gt;</replaceable>/applications/exo.jcr.applications.backupconsole</filename>. - </para> - - </step> - <step> - <para> - Build the application with: - </para> - -<programlisting><command>mvn clean install -P deploy</command></programlisting> - - </step> - <step> - <para> - Navigate to <emphasis role="bold">${JCR-SRC-HOME}/applications/exo.jcr.applications.backupconsole/target/backupconsole-binary</emphasis>. - </para> - - </step> - <step> - <para> - Run the jar with: - </para> - -<programlisting><command>java -jar exo.jcr.applications.backupconsole-binary.jar &lt;command&gt;</command></programlisting> - <para> - Alternatively, use jcrbackup.cmd (or .sh); - </para> - - </step> - - </procedure> - - <para> - Get information about the backup service with: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 info</command></programlisting> - <para> - Which will return output similar to: - </para> - -<screen>The backup service information : + </section> + <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Building_and_Running_Application"> + <title>Building and Running Application</title> + <note> + <title>Document Convention</title> + <para> + <filename> + <replaceable>&lt;JCR_SRC_HOME&gt;</replaceable> + </filename> the path where eXo JCR sources are located. + </para> + </note> + <procedure> + <title/> + <step> + <para> + Navigate to the backup client directory; <filename><replaceable>&lt;JCR_SRC_HOME&gt;</replaceable>/applications/exo.jcr.applications.backupconsole</filename>. + </para> + </step> + <step> + <para> + Build the application with: + </para> + <programlisting><command>mvn clean install -P deploy</command></programlisting> + </step> + <step> + <para> + Navigate to <emphasis role="bold">${JCR-SRC-HOME}/applications/exo.jcr.applications.backupconsole/target/backupconsole-binary</emphasis>. + </para> + </step> + <step> + <para> + Run the jar with: + </para> + <programlisting><command>java -jar exo.jcr.applications.backupconsole-binary.jar &lt;command&gt;</command></programlisting> + <para> + Alternatively, use jcrbackup.cmd (or .sh); + </para> + </step> + </procedure> + <para> + Get information about the backup service with: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 info</command></programlisting> + <para> + Which will return output similar to: + </para> + <screen>The backup service information : full backup type : org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob - incremetal backup type : org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob + incremental backup type : org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob backup log folder : /path/to/backup/directory default incremental job period : 3600 </screen> - - </section> - - <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Starting_Backups"> - <title>Starting Backups</title> - <para> - To start a full backup only on the workspace called "backup", pass the parameter <parameter>&lt;bakcup_dir&gt;</parameter> (<parameter>../temp/backup</parameter>) to the command: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 start /repository/backup ../temp/backup</command></programlisting> - <para> - Which will return output similar to: - </para> - -<screen>Successful : + </section> + <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Starting_Backups"> + <title>Starting Backups</title> + <para> + To start a full backup only on the workspace called &quot;backup&quot;, pass the parameter <parameter>&lt;backup_dir&gt;</parameter> (<parameter>../temp/backup</parameter>) to the command: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 start /repository/backup ../temp/backup</command></programlisting> + <para> + Which will return output similar to: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To start a full and incremental backup on the workspace called "production" add the increment integer to the command: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 start /repository/production ../temp/backup 10000</command></programlisting> - <para> - Which will return output similar to: - </para> - -<screen> + <para> + To start a full and incremental backup on the workspace called &quot;production&quot; add the increment integer to the command: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 start /repository/production ../temp/backup 10000</command></programlisting> + <para> + Which will return output similar to: + </para> + <screen> Successful : - tatus code = 200 + status code = 200 </screen> - <para> - To get information about the current backups in progress, run the command: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 list</command></programlisting> - <para> - The output will look similar to: - </para> - -<screen>The current backups information : + <para> + To get information about the current backups in progress, run the command: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 list</command></programlisting> + <para> + The output will look similar to: + </para> + <screen>The current backups information : 1) Backup with id b46370107f000101014b03ea5fbe8d54 : repository name : repository workspace name : production @@ -1698,16 +1442,14 @@ full backup state : finished started time : Fri, 17 Apr 2009 17:02:41 EEST </screen> - <para> - To get information about individual backups, pass the id to the application: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 status b46370107f000101014b03ea5fbe8d54</command></programlisting> - <para> - Which will print the following details: - </para> - -<screen>The current backup information : + <para> + To get information about individual backups, pass the id to the application: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 status b46370107f000101014b03ea5fbe8d54</command></programlisting> + <para> + Which will print the following details: + </para> + <screen>The current backup information : backup id : b46370107f000101014b03ea5fbe8d54 backup folder : /home/rainf0x/java/exo-working/JCR-839/new_JCR/exo-tomcat/bin/../temp/backup repository name : repository @@ -1717,16 +1459,14 @@ incremental backup state : working started time : Fri, 17 Apr 2009 17:03:16 EEST </screen> - <para> - To get information about the completed (ready to restore) backups, use the following command: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 list completed</command></programlisting> - <para> - Which will return: - </para> - -<screen>The completed (ready to restore) backups information : + <para> + To get information about the completed (ready to restore) backups, use the following command: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 list completed</command></programlisting> + <para> + Which will return: + </para> + <screen>The completed (ready to restore) backups information : 1) Backup with id adf6fadc7f00010100053b2cba43513c : repository name : repository workspace name : backup @@ -1745,87 +1485,77 @@ backup type : full only started time : Thu, 16 Apr 2009 14:51:08 EEST </screen> - - </section> - - <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Stopping_Backups"> - <title>Stopping Backups</title> - <para> - Stop an individual backup with the following command: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 stop &lt;backup_id&gt;</command></programlisting> - <para> - You will see the following output: - </para> - -<screen>Successful : + </section> + <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Stopping_Backups"> + <title>Stopping Backups</title> + <para> + Stop an individual backup with the following command: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 stop &lt;backup_id&gt;</command></programlisting> + <para> + You will see the following output: + </para> + <screen>Successful : status code = 200 </screen> - - </section> - - <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Restoring"> - <title>Restoring</title> - <important> - <title>Linebreaks</title> - <para> - The linebreaks in the commands below are for rendering purposes only. Run the commands as a single line unless otherwise instructed. - </para> - - </important> - <para> - Restore to the workspace called "backup3", you need the <replaceable>&lt;backup_id&gt;</replaceable> of a completed backup and the path to the file with the workspace configuration: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository/backup3 &lt;backup_id&gt; /path/to/exo-jcr-config_backup.xml</command></programlisting> - <para> - An example configuration file is included for reference: - </para> - -<programlisting language="XML" role="XML">&lt;repository-service default-repository="repository"&gt; + </section> + <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Restoring"> + <title>Restoring</title> + <important> + <para> + The line breaks in the commands below are for rendering purposes only. Run the commands as a single line unless otherwise instructed. + </para> + </important> + <para> + Restore to the workspace called &quot;backup3&quot;, you need the <replaceable>&lt;backup_id&gt;</replaceable> of a completed backup and the path to the file with the workspace configuration: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository/backup3 &lt;backup_id&gt; /path/to/exo-jcr-config_backup.xml</command></programlisting> + <para> + An example configuration file is included for reference: + </para> + <programlisting language="XML" role="XML">&lt;repository-service default-repository=&quot;repository&quot;&gt; &lt;repositories&gt; - &lt;repository name="repository" system-workspace="production" default-workspace="production"&gt; + &lt;repository name=&quot;repository&quot; system-workspace=&quot;production&quot; default-workspace=&quot;production&quot;&gt; &lt;security-domain&gt;exo-domain&lt;/security-domain&gt; &lt;access-control&gt;optional&lt;/access-control&gt; &lt;authentication-policy&gt;org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator&lt;/authentication-policy&gt; &lt;workspaces&gt; - &lt;workspace name="backup"&gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; + &lt;workspace name=&quot;backup&quot;&gt; + &lt;container class=&quot;org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer&quot;&gt; &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr" /&gt; - &lt;property name="dialect" value="pgsql" /&gt; - &lt;property name="multi-db" value="false" /&gt; - &lt;property name="update-storage" value="false" /&gt; - &lt;property name="max-buffer-size" value="200k" /&gt; - &lt;property name="swap-directory" value="../temp/swap/backup" /&gt; + &lt;property name=&quot;source-name&quot; value=&quot;jdbcjcr&quot; /&gt; + &lt;property name=&quot;dialect&quot; value=&quot;pgsql&quot; /&gt; + &lt;property name=&quot;multi-db&quot; value=&quot;false&quot; /&gt; + &lt;property name=&quot;update-storage&quot; value=&quot;false&quot; /&gt; + &lt;property name=&quot;max-buffer-size&quot; value=&quot;200k&quot; /&gt; + &lt;property name=&quot;swap-directory&quot; value=&quot;../temp/swap/backup&quot; /&gt; &lt;/properties&gt; &lt;value-storages&gt; - &lt;value-storage id="draft" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; + &lt;value-storage id=&quot;draft&quot; class=&quot;org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage&quot;&gt; &lt;properties&gt; - &lt;property name="path" value="../temp/values/backup" /&gt; + &lt;property name=&quot;path&quot; value=&quot;../temp/values/backup&quot; /&gt; &lt;/properties&gt; &lt;filters&gt; - &lt;filter property-type="Binary"/&gt; + &lt;filter property-type=&quot;Binary&quot;/&gt; &lt;/filters&gt; &lt;/value-storage&gt; &lt;/value-storages&gt; &lt;/container&gt; - &lt;initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"&gt; + &lt;initializer class=&quot;org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer&quot;&gt; &lt;properties&gt; - &lt;property name="root-nodetype" value="nt:unstructured" /&gt; + &lt;property name=&quot;root-nodetype&quot; value=&quot;nt:unstructured&quot; /&gt; &lt;/properties&gt; &lt;/initializer&gt; - &lt;cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl"&gt; + &lt;cache enabled=&quot;true&quot; class=&quot;org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl&quot;&gt; &lt;properties&gt; - &lt;property name="max-size" value="10k" /&gt; - &lt;property name="live-time" value="1h" /&gt; + &lt;property name=&quot;max-size&quot; value=&quot;10k&quot; /&gt; + &lt;property name=&quot;live-time&quot; value=&quot;1h&quot; /&gt; &lt;/properties&gt; &lt;/cache&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + &lt;query-handler class=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex&quot;&gt; &lt;properties&gt; - &lt;property name="index-dir" value="../temp/jcrlucenedb/backup" /&gt; + &lt;property name=&quot;index-dir&quot; value=&quot;../temp/jcrlucenedb/backup&quot; /&gt; &lt;/properties&gt; &lt;/query-handler&gt; &lt;/workspace&gt; @@ -1834,23 +1564,20 @@ &lt;/repositories&gt; &lt;/repository-service&gt; </programlisting> - <para> - A successful restoration will return the following: - </para> - -<screen>Successful : + <para> + A successful restoration will return the following: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To get information about the current restore for <filename>/repository/backup3</filename> workspace: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restores</command></programlisting> - <para> - Which will print the following details: - </para> - -<screen>The current restores information : + <para> + To get information about the current restore for <filename>/repository/backup3</filename> workspace: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restores</command></programlisting> + <para> + Which will print the following details: + </para> + <screen>The current restores information : 1) Restore with id 6c302adc7f00010100df88d29535c6ee: full backup date : 2009-04-03T16:34:37.394+03:00 backup log file : /home/rainf0x/java/exo-working/JCR-839/exo-tomcat/bin/../temp/backup/backup-6c302adc7f00010100df88d29535c6ee.xml @@ -1860,183 +1587,151 @@ path to backup folder : /home/rainf0x/java/exo-working/JCR-839/exo-tomcat/bin/../temp/backup restore state : successful </screen> - <para> - To restore to the workspace "backup" and completely remove an existing workspace from the database, value storage and index, you need the <replaceable>&lt;backup_id&gt;</replaceable> of a completed backup and path to the file with the workspace configuration: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists /repository/backup &lt;backup_id&gt; /path/to/exo-jcr-config_backup.xml</command></programlisting> - <para> - A successful restoration will return: - </para> - -<screen>Successful : + <para> + To restore to the workspace &quot;backup&quot; and completely remove an existing workspace from the database, value storage and index, you need the <replaceable>&lt;backup_id&gt;</replaceable> of a completed backup and path to the file with the workspace configuration: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists /repository/backup &lt;backup_id&gt; /path/to/exo-jcr-config_backup.xml</command></programlisting> + <para> + A successful restoration will return: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To restore to the "backup" workspace from a backup set, you need the <replaceable>&lt;backup_set_path&gt;</replaceable> (the path to the backup set folder on the server side) of completed backups and the path to the configuration file for the workspace: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository/backup /tmp/123/repository_backup-20101220_114156 /path/to/exo-jcr-config_backup.xml</command></programlisting> - <para> - A successful restoration will return: - </para> - -<screen>Successful : + <para> + To restore to the &quot;backup&quot; workspace from a backup set, you need the <replaceable>&lt;backup_set_path&gt;</replaceable> (the path to the backup set folder on the server side) of completed backups and the path to the configuration file for the workspace: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository/backup /tmp/123/repository_backup-20101220_114156 /path/to/exo-jcr-config_backup.xml</command></programlisting> + <para> + A successful restoration will return: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To restore to the workspace "backup" and completely remove an existing workspace, you need the <replaceable>&lt;backup_set_path&gt;</replaceable> (the path to the backup set folder on the server side) of completed backups and the path to the configuration file for the workspace: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists /repository/backup /repository/backup /tmp/123/repository_backup-20101220_114156 /path/to/exo-jcr-config_backup.xml</command></programlisting> - <para> - A successful restoration will return: - </para> - -<screen>Successful : + <para> + To restore to the workspace &quot;backup&quot; and completely remove an existing workspace, you need the <replaceable>&lt;backup_set_path&gt;</replaceable> (the path to the backup set folder on the server side) of completed backups and the path to the configuration file for the workspace: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists /repository/backup /repository/backup /tmp/123/repository_backup-20101220_114156 /path/to/exo-jcr-config_backup.xml</command></programlisting> + <para> + A successful restoration will return: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To restore to the "backup" workspace with an original configuration (which was stored in backup set), you need the <replaceable>&lt;backup_id&gt;</replaceable> of the appropriate completed backup: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore &lt;backup_id&gt;</command></programlisting> - <para> - A successful restoration will return: - </para> - -<screen>Successful : + <para> + To restore to the &quot;backup&quot; workspace with an original configuration (which was stored in backup set), you need the <replaceable>&lt;backup_id&gt;</replaceable> of the appropriate completed backup: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore &lt;backup_id&gt;</command></programlisting> + <para> + A successful restoration will return: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To restore to the workspace "backup" with an original configuration and completely remove the existing workspace, execute the above command and include the <parameter>remove-exists</parameter> switch: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists &lt;backup_id&gt;</command></programlisting> - <para> - A successful restoration will output: - </para> - -<screen>Successful : + <para> + To restore to the workspace &quot;backup&quot; with an original configuration and completely remove the existing workspace, execute the above command and include the <parameter>remove-exists</parameter> switch: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists &lt;backup_id&gt;</command></programlisting> + <para> + A successful restoration will output: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To restore a repository you will need the <replaceable>&lt;backup_id&gt;</replaceable> of a completed backup and path to the configuration file of the repository: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository &lt;backup_id&gt; /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config.xml</command></programlisting> - <para> - A successful restoration will print: - </para> - -<screen>Successful : + <para> + To restore a repository you will need the <replaceable>&lt;backup_id&gt;</replaceable> of a completed backup and path to the configuration file of the repository: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository &lt;backup_id&gt; /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config.xml</command></programlisting> + <para> + A successful restoration will print: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To restore a repository and completely remove an existing repository, add the <parameter>remove-exists</parameter> parameter to the above command: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists /repository &lt;backup_id&gt; /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config.xml</command></programlisting> - <para> - Return: - </para> - -<programlisting>Successful : + <para> + To restore a repository and completely remove an existing repository, add the <parameter>remove-exists</parameter> parameter to the above command: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists /repository &lt;backup_id&gt; /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config.xml</command></programlisting> + <para> + Return: + </para> + <programlisting>Successful : status code = 200</programlisting> - <para> - To restore to a repository called "repository" from backup set, you need the <replaceable>&lt;backup_set_path&gt;</replaceable> (the path to the backup set folder, on the server side) of a completed backup and the path to the repository configuration file: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository /tmp/123/repository_repository_backup_1292833493681 /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config.xml</command></programlisting> - <para> - If successful the above command will return: - </para> - -<screen>Successful : + <para> + To restore to a repository called &quot;repository&quot; from backup set, you need the <replaceable>&lt;backup_set_path&gt;</replaceable> (the path to the backup set folder, on the server side) of a completed backup and the path to the repository configuration file: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository /tmp/123/repository_repository_backup_1292833493681 /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config.xml</command></programlisting> + <para> + If successful the above command will return: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To restore to a repository called "repository" from a backup set and completely remove an existing repository from the database, value storage and index, you will need the <replaceable>&lt;backup_set_path&gt;</replaceable> of a completed backup and the path to the file with repository's configuration: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists /repository /repository/backup /tmp/123/repository_repository_backup_1292833493681 /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config.xml</command></programlisting> - <para> - The application will print the following if successful: - </para> - -<screen>Successful : + <para> + To restore to a repository called &quot;repository&quot; from a backup set and completely remove an existing repository from the database, value storage and index, you will need the <replaceable>&lt;backup_set_path&gt;</replaceable> of a completed backup and the path to the file with repository&apos;s configuration: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists /repository /repository/backup /tmp/123/repository_repository_backup_1292833493681 /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config.xml</command></programlisting> + <para> + The application will print the following if successful: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To restore to a repository called "repository" with an original configuration of repository (provided the original configuration was stored in a backup set): - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore &lt;backup_id&gt;</command></programlisting> - <para> - Which, if successful, will return: - </para> - -<screen>Successful : + <para> + To restore to a repository called &quot;repository&quot; with an original configuration of repository (provided the original configuration was stored in a backup set): + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore &lt;backup_id&gt;</command></programlisting> + <para> + Which, if successful, will return: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To restore to a repository "repository" with original configuration (as above) and completely remove an existing repository: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists &lt;backup_id&gt;</command></programlisting> - <para> - Which will print the following message if successful: - </para> - -<screen>Successful : + <para> + To restore to a repository &quot;repository&quot; with original configuration (as above) and completely remove an existing repository: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists &lt;backup_id&gt;</command></programlisting> + <para> + Which will print the following message if successful: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To restore to a repository "repository" from a backup set with an original configuration, you will need the <replaceable>&lt;backup_set_path&gt;</replaceable> (the path to the backup set folder on the server) of completed backup: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /tmp/123/repository_repository_backup_1292833493681</command></programlisting> - <para> - The following message will print on success: - </para> - -<screen>Successful : + <para> + To restore to a repository &quot;repository&quot; from a backup set with an original configuration, you will need the <replaceable>&lt;backup_set_path&gt;</replaceable> (the path to the backup set folder on the server) of completed backup: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /tmp/123/repository_repository_backup_1292833493681</command></programlisting> + <para> + The following message will print on success: + </para> + <screen>Successful : status code = 200 </screen> - <para> - To perform the above (restore a repository with an original configuration from a backup set) and completely remove an existing repository from the underlying database, value storage and index, add the <parameter>remove-exists</parameter> parameter to the command: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists /tmp/123/repository_repository_backup_1292833493681</command></programlisting> - <para> - The same success message will be printed if there were no errors. - </para> - - </section> - - <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Walkthrough_Creating_a_Backup_and_Restoring_a_Workspace"> - <title>Walkthrough: Creating a Backup and Restoring a Workspace</title> - <procedure> - <title></title> - <step> - <title>Create the backup:</title> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 start /repository/backup ../temp/backup 10000</command></programlisting> - <para> - You will see the following message if the task executes successfully: - </para> - -<screen>Successful : + <para> + To perform the above (restore a repository with an original configuration from a backup set) and completely remove an existing repository from the underlying database, value storage and index, add the <parameter>remove-exists</parameter> parameter to the command: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore remove-exists /tmp/123/repository_repository_backup_1292833493681</command></programlisting> + <para> + The same success message will be printed if there were no errors. + </para> + </section> + <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Walkthrough_Creating_a_Backup_and_Restoring_a_Workspace"> + <title>Walk-through: Creating a Backup and Restoring a Workspace</title> + <procedure> + <title/> + <step> + <title>Create the backup:</title> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 start /repository/backup ../temp/backup 10000</command></programlisting> + <para> + You will see the following message if the task executes successfully: + </para> + <screen>Successful : status code = 200 </screen> - - </step> - <step> - <title>Get information about current backups:</title> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 list</command></programlisting> - -<screen>The current backups information : + </step> + <step> + <title>Get information about current backups:</title> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 list</command></programlisting> + <screen>The current backups information : 1) Backup with id b469ba957f0001010178febaedf20eb7 : repository name : repository workspace name : backup @@ -2045,76 +1740,61 @@ incremental backup state : working started time : Fri, 17 Apr 2009 17:10:09 EEST </screen> - - </step> - <step> - <title><emphasis role="bold">Optional:</emphasis> Stop a backup</title> - <para> - If you need to, you can stop a backup with its <replaceable>&lt;backup_id&gt;</replaceable>: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 stop &lt;backup_id&gt;</command></programlisting> - <para> - You will get a success message once the nominated backup has been stopped. - </para> - - </step> - <step> - <title>Deleting the workspace and close any opened sessions on it</title> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 drop force-close-session /repository/backup</command></programlisting> - <para> - A success message will be printed once all actions are completed. - </para> - - </step> - <step> - <title>Restore the workspace</title> - <substeps> - <step> - <para> - Cleanse the database of references to the old workspace (<emphasis role="bold">"backup"</emphasis>, for example): When we use "single-db", then we will run the SQL queries for clean database: - </para> - -<programlisting>delete from JCR_SREF where NODE_ID in (select ID from JCR_SITEM where CONTAINER_NAME = 'backup') -delete from JCR_SVALUE where PROPERTY_ID in (select ID from JCR_SITEM where CONTAINER_NAME = 'backup') -delete from JCR_SITEM where CONTAINER_NAME='backup'</programlisting> - - </step> - <step> - <para> - Delete the value storage and the index data for the old workspace. - </para> - - </step> - <step> - <para> - Restore the workspace: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository/backup &lt;backup_id&gt; /path/to/exo-jcr-config_backup.xml</command></programlisting> - <para> - A success message will print if successful: - </para> - -<screen>Successful : + </step> + <step> + <title><emphasis role="bold">Optional:</emphasis> Stop a backup</title> + <para> + If you need to, you can stop a backup with its <replaceable>&lt;backup_id&gt;</replaceable>: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 stop &lt;backup_id&gt;</command></programlisting> + <para> + You will get a success message once the nominated backup has been stopped. + </para> + </step> + <step> + <title>Deleting the workspace and close any opened sessions on it</title> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 drop force-close-session /repository/backup</command></programlisting> + <para> + A success message will be printed once all actions are completed. + </para> + </step> + <step> + <title>Restore the workspace</title> + <substeps> + <step> + <para> + Cleanse the database of references to the old workspace (<emphasis role="bold">&quot;backup&quot;</emphasis>, for example): When we use &quot;single-db&quot;, then we will run the SQL queries for clean database: + </para> + <programlisting>delete from JCR_SREF where NODE_ID in (select ID from JCR_SITEM where CONTAINER_NAME = &apos;backup&apos;) +delete from JCR_SVALUE where PROPERTY_ID in (select ID from JCR_SITEM where CONTAINER_NAME = &apos;backup&apos;) +delete from JCR_SITEM where CONTAINER_NAME=&apos;backup&apos;</programlisting> + </step> + <step> + <para> + Delete the value storage and the index data for the old workspace. + </para> + </step> + <step> + <para> + Restore the workspace: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository/backup &lt;backup_id&gt; /path/to/exo-jcr-config_backup.xml</command></programlisting> + <para> + A success message will print if successful: + </para> + <screen>Successful : status code = 200 </screen> - - </step> - - </substeps> - - </step> - <step> - <title>Get information about the workspace restore</title> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restores /repository/backup</command></programlisting> - <para> - Which will output the following details: - </para> - -<screen>The current restores information : + </step> + </substeps> + </step> + <step> + <title>Get information about the workspace restore</title> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restores /repository/backup</command></programlisting> + <para> + Which will output the following details: + </para> + <screen>The current restores information : Restore with id b469ba957f0001010178febaedf20eb7: backup folder : /home/rainf0x/java/exo-working/JCR-839/new_JCR/exo-tomcat/bin/../temp/backup repository name : repository @@ -2124,51 +1804,39 @@ started time : Fri, 17 Apr 2009 16:38:00 EEST finished time : Fri, 17 Apr 2009 16:38:00 EEST </screen> - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Walkthrough_Creating_a_Backup_and_Restoring_a_Repository"> - <title>Walkthrough: Creating a Backup and Restoring a Repository</title> - <note> - <title>Default Repository</title> - <para> - If you delete the default repository, it should be restored with the name <emphasis>default</emphasis>. - </para> - - </note> - <important> - <title>Required Components</title> - <para> - This usecase requires <literal>RestRepositoryService</literal> to be enabled as it is needed to delete a repository: - </para> - -<programlisting language="XML">&lt;component&gt; + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-HTTPBackupAgent_and_Backup_Client-Walkthrough_Creating_a_Backup_and_Restoring_a_Repository"> + <title>Walk-through: Creating a Backup and Restoring a Repository</title> + <note> + <title>Default Repository</title> + <para> + If you delete the default repository, it should be restored with the name <emphasis>default</emphasis>. + </para> + </note> + <important> + <title>Required Components</title> + <para> + This use-case requires <literal>RestRepositoryService</literal> to be enabled as it is needed to delete a repository: + </para> + <programlisting language="XML">&lt;component&gt; &lt;type&gt;org.exoplatform.services.jcr.ext.repository.RestRepositoryService&lt;/type&gt; &lt;/component&gt;</programlisting> - - </important> - <procedure id="proc-Reference_Guide-Walkthrough_Creating_a_Backup_and_Restoring_a_Repository-Backup_and_Restore_a_Repository"> - <title>Backup and Restore a Repository</title> - <step> - <title>Creating a backup</title> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 start /repository ../temp/backup 10000</command></programlisting> - - </step> - <step> - <title>Get information about current backups</title> - -<programlisting>jcrbackup http://root:exo@127.0.0.1:8080 list</programlisting> - <para> - This will return the following details: - </para> - -<screen>The current backups information : + </important> + <procedure id="proc-Reference_Guide-Walkthrough_Creating_a_Backup_and_Restoring_a_Repository-Backup_and_Restore_a_Repository"> + <title>Backup and Restore a Repository</title> + <step> + <title>Creating a backup</title> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 start /repository ../temp/backup 10000</command></programlisting> + </step> + <step> + <title>Get information about current backups</title> + <programlisting>jcrbackup http://root:exo@127.0.0.1:8080 list</programlisting> + <para> + This will return the following details: + </para> + <screen>The current backups information : 1) Repository backup with id 9a4d40fb7f0000012ec8f0a4ec70b3da : repository name : repository backup type : full + incremetal @@ -2176,95 +1844,72 @@ incremental backups state : working started time : Mon, 11 Oct 2010 10:59:35 EEST </screen> - - </step> - <step> - <title><emphasis role="bold">Optional:</emphasis> Stopping the backup</title> - <para> - If you should need to, you can stop a backup with the <replaceable>&lt;backup_id&gt;</replaceable> 9a4d40fb7f0000012ec8f0a4ec70b3da with the following command: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 stop 9a4d40fb7f0000012ec8f0a4ec70b3da</command></programlisting> - <para> - You will get a confirmation message once the backup is successfully stopped. - </para> - - </step> - <step> - <title>Deleting a repository and close all opened sessions</title> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 drop force-close-session /repository</command></programlisting> - <para> - You will get a confirmation message once the backup is successfully stopped. - </para> - - </step> - <step> - <title>Restore the repository</title> - <substeps> - <step> - <para> - Cleanse the database of references to the workspace: When we use "single-db", then we will run the SQL queries for clean database : - </para> - -<programlisting>drop table JCR_SREF; + </step> + <step> + <title><emphasis role="bold">Optional:</emphasis> Stopping the backup</title> + <para> + If you should need to, you can stop a backup with the <replaceable>&lt;backup_id&gt;</replaceable> 9a4d40fb7f0000012ec8f0a4ec70b3da with the following command: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 stop 9a4d40fb7f0000012ec8f0a4ec70b3da</command></programlisting> + <para> + You will get a confirmation message once the backup is successfully stopped. + </para> + </step> + <step> + <title>Deleting a repository and close all opened sessions</title> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 drop force-close-session /repository</command></programlisting> + <para> + You will get a confirmation message once the backup is successfully stopped. + </para> + </step> + <step> + <title>Restore the repository</title> + <substeps> + <step> + <para> + Cleanse the database of references to the workspace: When we use &quot;single-db&quot;, then we will run the SQL queries for clean database : + </para> + <programlisting>drop table JCR_SREF; drop table JCR_SVALUE; drop table JCR_SITEM;</programlisting> - - </step> - <step> - <para> - Delete the value storage for repository. - </para> - - </step> - <step> - <para> - Delete the index data for repository. - </para> - - </step> - <step> - <para> - Restore: - </para> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository &lt;backup_id&gt; /path/to/exo-jcr-config_backup.xml</command></programlisting> - <para> - A successful operation will return: - </para> - -<screen>Successful : + </step> + <step> + <para> + Delete the value storage for repository. + </para> + </step> + <step> + <para> + Delete the index data for repository. + </para> + </step> + <step> + <para> + Restore: + </para> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restore /repository &lt;backup_id&gt; /path/to/exo-jcr-config_backup.xml</command></programlisting> + <para> + A successful operation will return: + </para> + <screen>Successful : status code = 200</screen> - - </step> - - </substeps> - - </step> - <step> - <title>Get information about the restored repository</title> - -<programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restores /repository</command></programlisting> - <para> - Which will return the following details: - </para> - -<screen>Repository restore with id 9a6dba327f000001325dfb228a181b07: + </step> + </substeps> + </step> + <step> + <title>Get information about the restored repository</title> + <programlisting><command>jcrbackup http://root:exo@127.0.0.1:8080 restores /repository</command></programlisting> + <para> + Which will return the following details: + </para> + <screen>Repository restore with id 9a6dba327f000001325dfb228a181b07: backup folder : /home/rainf0x/java/exo-working/JCR-1459/exo-tomcat/bin/../temp/backup/repository_repository_backup_1286786103858 repository name : repository backup type : full + incremetal restore state : successful started time : Mon, 11 Oct 2010 11:51:15 EEST finished time : Mon, 11 Oct 2010 11:51:17 EEST</screen> - - </step> - - </procedure> - - - </section> - - + </step> + </procedure> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/exojcr-backup-service.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/exojcr-backup-service.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/exojcr-backup-service.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,337 +1,290 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-eXo_JCR_Backup_Service"> - <title>eXo JCR Backup Service</title> - <note> - <para> + <title>eXo JCR Backup Service</title> + <note> + <para> Restoration of system workspaces is not supported. Workspaces can only be restored as part of a complete repository restoration. </para> - - </note> - <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Concept"> - <title>Concept</title> - <para> + </note> + <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Concept"> + <title>Concept</title> + <para> The main purpose of this feature is to restore data in case of system faults and repository crashes. Also, the backup results may be used as a content history. </para> - <para> + <para> The concept is based on the export of a workspace unit in the <emphasis>Full</emphasis>, or <emphasis>Full + Incremental</emphasis> model. A repository workspace can be backup and restored using a combination of these modes. </para> - <para> + <para> In all cases, however, at least one <emphasis>Full</emphasis> (initial) backup must be executed to mark a starting point of the backup history. An <emphasis>Incremental</emphasis> backup is not a complete image of the workspace. It contains only changes for some period. So it is not possible to perform an <emphasis>Incremental</emphasis> backup without an initial <emphasis>Full</emphasis> backup. </para> - <para> + <para> The Backup service may operate as a hot-backup process at runtime on an in-use workspace. In this case the <emphasis>Full</emphasis> + <emphasis>Incremental</emphasis> model should be used to ensure data consistency during restoration. </para> - <para> + <para> An <emphasis>Incremental</emphasis> backup will be run starting from the start point of the <emphasis>Full</emphasis> backup and will contain changes that have occurred during the <emphasis>Full</emphasis> backup, too. </para> - <para> + <para> A <emphasis role="bold">restore</emphasis> operation is a mirror of a backup one. At least one <emphasis>Full</emphasis> backup should be restored to obtain a workspace saved at some time in the past. </para> - <para> + <para> However, <emphasis>Incremental</emphasis> backups may be restored in the order of creation to reach a required state of a content. If the <emphasis>Incremental</emphasis> contains the same data as the <emphasis>Full</emphasis> backup (hot-backup), the changes will be applied again as if they were made in a normal way via API calls. </para> - <para> + <para> According to the model there are several modes for backup logic: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <emphasis role="bold">Full backup only</emphasis>: Single operation, runs once </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">Full + Incrementas</emphasis>: Start with an initial <emphasis>Full</emphasis> backup and then keep incrementals changes in one file. Run until it is stopped. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">Full + Incremental(periodic)</emphasis>: Start with an initial <emphasis>Full</emphasis> backup and then keep incrementals with periodic result file rotation. Run until it is stopped. </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-How_it_works"> - <title>How it works</title> - <section id="sect-Reference_Guide-How_it_works-Implementation_details"> - <title>Implementation details</title> - <para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-How_it_works"> + <title>How it works</title> + <section id="sect-Reference_Guide-How_it_works-Implementation_details"> + <title>Implementation details</title> + <para> <emphasis>Full</emphasis> backup/restore is implemented using the JCR SysView Export/Import. Workspace data will be exported into Sysview XML data from root node. </para> - <para> + <para> Restoring is implemented, using the special eXo JCR API feature: a dynamic workspace creation. Restoring of the workspace <emphasis>Full</emphasis> backup will create one new workspace in the repository. Then, the SysView XML data will be imported as the root node. </para> - <para> + <para> <emphasis>Incremental</emphasis> backup is implemented using the eXo JCR ChangesLog API. This API allows to record each JCR API call as atomic entries in a changelog. Hence, the <emphasis>Incremental</emphasis> backup uses a listener that collects these logs and stores them in a file. </para> - <para> + <para> Restoring an incremental backup consists in applying the collected set of ChangesLogs to a workspace in the correct order. </para> - <note> - <title>Note</title> - <para> + <note> + <title>Note</title> + <para> Incremental backup is an experimental feature and not supported. Please use it with caution. </para> - - </note> - - </section> - - <section id="sect-Reference_Guide-How_it_works-Work_basics"> - <title>Work basics</title> - <para> + </note> + </section> + <section id="sect-Reference_Guide-How_it_works-Work_basics"> + <title>Work basics</title> + <para> The work of Backup is based on the BackupConfig configuration and the BackupChain logical unit. </para> - <para> + <para> BackupConfig describes the backup operation chain that will be performed by the service. When you intend to work with it, the configuration should be prepared before the backup is started. </para> - <para> + <para> The configuration contains such values as: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <emphasis role="bold">Types of full and incremental backup</emphasis> (fullBackupType, incrementalBackupType): Strings with full names of classes which will cover the type functional. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">Incremental period</emphasis>: A period after that a current backup will be stopped and a new one will be started in seconds (long). </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">Target repository and workspace names</emphasis>: Strings with described names </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">Destination directory</emphasis> for result files: String with a path to a folder where operation result files will be stored. </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> <literal>BackupChain</literal> is a unit performing the backup process and it covers the principle of initial <emphasis>Full</emphasis> backup execution and manages <emphasis>Incremental</emphasis> operations. </para> - <para> + <para> <literal>BackupChain</literal> is used as a key object for accessing current backups during runtime via <literal>BackupManager</literal>. Each <literal>BackupJob</literal> performs a single atomic operation - a <emphasis>Full</emphasis> or <emphasis>Incremental</emphasis> process. The result of that operation is data for a Restore. </para> - <para> + <para> <literal>BackupChain</literal> can contain one or more <literal>BackupJobs</literal>. The initial <emphasis>Full</emphasis> job is always there. Each <literal>BackupJobs</literal> has its own unique number which means its Job order in the chain, the initial <emphasis>Full</emphasis> job always has the number <literal>0</literal>. </para> - <formalpara id="form-Reference_Guide-Work_basics-Backup_process_result_data_and_file_location"> - <title>Backup process, result data and file location</title> - <para> + <formalpara id="form-Reference_Guide-Work_basics-Backup_process_result_data_and_file_location"> + <title>Backup process, result data and file location</title> + <para> To start the backup process, it is necessary to create the <literal>BackupConfig</literal> and call the <literal>BackupManager.startBackup(BackupConfig)</literal> method. This method will return <literal>BackupChain</literal> created according to the configuration. At the same time, the chain creates a <literal>BackupChainLog</literal> which persists <literal>BackupConfig</literal> content and <literal>BackupChain</literal> operation states to the file in the service working directory (see Configuration). </para> - - </formalpara> - <para> + </formalpara> + <para> When the chain starts the work and the initial <literal>BackupJob</literal> starts, the job will create a result data file using the destination directory path from <literal>BackupConfig</literal>. </para> - <para> + <para> The destination directory will contain a directory with an automatically created name using the pattern <parameter>repository_workspace-timestamp</parameter> where <literal>timestamp</literal> is current time in the format of <literal>yyyyMMdd_hhmmss</literal> (for example; <literal>db1_ws1-20080306_055404</literal>). </para> - <para> + <para> The directory will contain the results of all Jobs configured for execution. Each Job stores the backup result in its own file with the name <parameter>repository_workspace-timestamp.jobNumber</parameter>. <literal>BackupChain</literal> saves each state (<literal>STARTING</literal>, <literal>WAITING</literal>, <literal>WORKING</literal>, <literal>FINISHED</literal>) of its Jobs in the <literal>BackupChainLog</literal>, which has a current result full file path. </para> - <para> + <para> <literal>BackupChain</literal> log file and job result files are a whole and consistent unit, that is a source for a Restore. </para> - <note> - <para> - <literal>BackupChain</literal> log contains absolute paths to job result files. Don't move these files to another location. + <note> + <para> + <literal>BackupChain</literal> log contains absolute paths to job result files. do not move these files to another location. </para> - - </note> - <formalpara id="form-Reference_Guide-Work_basics-Restore_requirements"> - <title>Restore requirements</title> - <para> - As outlined earlier, a Restore operation is a mirror of a Backup. The process is a <emphasis>Full</emphasis> restore of a root node with restoring an additional <emphasis>Incremental</emphasis> backup to reach a desired workspace state. Restoring the workspace <emphasis>Full</emphasis> backup will create a new workspace in the repository using given <literal>RepositoryEntry</literal> of existing repository and given (preconfigured) WorkspaceEntry for a new target workspace. A Restore process will restore a root node from the SysView XML data. + </note> + <formalpara id="form-Reference_Guide-Work_basics-Restore_requirements"> + <title>Restore requirements</title> + <para> + As outlined earlier, a Restore operation is a mirror of a Backup. The process is a <emphasis>Full</emphasis> restore of a root node with restoring an additional <emphasis>Incremental</emphasis> backup to reach a desired workspace state. Restoring the workspace <emphasis>Full</emphasis> backup will create a new workspace in the repository using given <literal>RepositoryEntry</literal> of existing repository and given (pre-configured) WorkspaceEntry for a new target workspace. A Restore process will restore a root node from the SysView XML data. </para> - - </formalpara> - <note> - <title>Exceptions</title> - <para> + </formalpara> + <note> + <title>Exceptions</title> + <para> The target workspace should not be in the repository. Otherwise, a <literal>BackupConfigurationException</literal> exception will be thrown. </para> - - </note> - <para> + </note> + <para> In case you already have a target Workspace (with the same name) in a Repository, you have to configure a new name for it. If no target workspace exists in the Repository, you may use the same name as the Backup one. </para> - - </section> - - </section> - - <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Configuration"> - <title>Configuration</title> - <para> + </section> + <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Configuration"> + <title>Configuration</title> + <para> As an optional extension, the Backup service is not enabled by default. <emphasis role="bold">You need to enable it via configuration</emphasis>. </para> - <para> + <para> The following is an example configuration: </para> - <programlistingco> - <areaspec> - <area coords="9" id="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-incremental-backup-type" /> - <area coords="8" id="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-full-backup-type" /> - <area coords="7" id="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-default-incremental-job-period" /> - <area coords="10" id="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-backup-dir" /> - - </areaspec> - -<programlisting language="XML">&lt;component&gt; + <programlistingco> + <areaspec> + <area coords="9" id="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-incremental-backup-type"/> + <area coords="8" id="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-full-backup-type"/> + <area coords="7" id="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-default-incremental-job-period"/> + <area coords="10" id="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-backup-dir"/> + </areaspec> + <programlisting language="XML">&lt;component&gt; &lt;key&gt;org.exoplatform.services.jcr.ext.backup.BackupManager&lt;/key&gt; &lt;type&gt;org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl&lt;/type&gt; &lt;init-params&gt; &lt;properties-param&gt; &lt;name&gt;backup-properties&lt;/name&gt; - &lt;property name="backup-dir" value="target/backup" /&gt; + &lt;property name=&quot;backup-dir&quot; value=&quot;target/backup&quot; /&gt; &lt;/properties-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> - <calloutlist id="call-Reference_Guide-Configuration-Mandatory_parameter"> - <title>Mandatory parameter</title> - <callout arearefs="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-backup-dir"> - <para> + <calloutlist id="call-Reference_Guide-Configuration-Mandatory_parameter"> + <title>Mandatory parameter</title> + <callout arearefs="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-backup-dir"> + <para> <parameter>backup-dir</parameter> is the path to a working directory where the service will store internal files and chain logs. </para> - - </callout> - - </calloutlist> - <calloutlist id="call-Reference_Guide-Configuration-Optional_parameters"> - <title>Optional parameters</title> - <callout arearefs="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-incremental-backup-type"> - <para> + </callout> + </calloutlist> + <calloutlist id="call-Reference_Guide-Configuration-Optional_parameters"> + <title>Optional parameters</title> + <callout arearefs="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-incremental-backup-type"> + <para> <parameter>incremental-backup-type</parameter> The FQN of incremental job class. Must implement <literal>org.exoplatform.services.jcr.ext.backup.BackupJob</literal>. By default, <literal>org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob</literal> is used. </para> - - </callout> - <callout arearefs="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-full-backup-type"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-full-backup-type"> + <para> <parameter>full-backup-type</parameter> is the FQN of the full backup job class. It must implement <literal>org.exoplatform.services.jcr.ext.backup.BackupJob</literal>. By default, <literal>org.exoplatform.services.jcr.ext.backup.impl.rdbms.FullBackupJob</literal> is used. Please, notice that file-system based implementation <literal>org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob</literal> is deprecated and not recommended for use.. </para> - - </callout> - <callout arearefs="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-default-incremental-job-period"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-eXo_JCR_Backup_Service-Configuration-default-incremental-job-period"> + <para> <parameter>default-incremental-job-period</parameter> is the period between incremental flushes (in seconds). Default is <literal>3600</literal> seconds. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - - </section> - - <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-RDBMS_backup"> - <title>RDBMS backup</title> - <para> + </callout> + </calloutlist> + </programlistingco> + </section> + <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-RDBMS_backup"> + <title>RDBMS backup</title> + <para> RDBMS backup It is the latest, currently supported used by default and recommended implementation of full backup job for BackupManager service. It is useful in case when database is used to store data. </para> - <para> + <para> Brings such advantages: </para> - <para> + <para> <itemizedlist> - <listitem> - <para> + <listitem> + <para> fast: backup takes only several minutes to perform full backup of repository with 1 million rows in tables; </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> atomic restore: restore process into existing workspace/repository with same configuration is atomic, it means you don’t loose the data when restore failed, the original data remains; </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> cluster aware: it is possible to make backup/restore in cluster environment into existing workspace/repository with same configuration; </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> consistence backup: all threads make waiting until backup is finished and then continue to work, so, there are no data modification during backup process; </para> + </listitem> + </itemizedlist> - </listitem> - - </itemizedlist> - </para> - - </section> - - <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Usage"> - <title>Usage</title> - <section id="sect-Reference_Guide-Usage-Performing_a_Backup"> - <title>Performing a Backup</title> - <para> + </section> + <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Usage"> + <title>Usage</title> + <section id="sect-Reference_Guide-Usage-Performing_a_Backup"> + <title>Performing a Backup</title> + <para> In the following example, we create a <literal>BackupConfig</literal> bean for the <emphasis>Full</emphasis> + <emphasis>Incremental</emphasis>s mode, then we ask the BackupManager to start the backup process. </para> - -<programlisting language="Java">// Obtaining the backup service from the eXo container. + <programlisting language="Java">// Obtaining the backup service from the eXo container. BackupManager backup = (BackupManager) container.getComponentInstanceOfType(BackupManager.class); // And prepare the BackupConfig instance with custom parameters. // full backup &amp; incremental -File backDir = new File("/backup/ws1"); // the destination path for result files +File backDir = new File(&quot;/backup/ws1&quot;); // the destination path for result files backDir.mkdirs(); BackupConfig config = new BackupConfig(); config.setRepository(repository.getName()); -config.setWorkspace("ws1"); +config.setWorkspace(&quot;ws1&quot;); config.setBackupDir(backDir); // Before 1.9.3, you also need to indicate the backupjobs class FDNs -// config.setFullBackupType("org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob"); -// config.setIncrementalBackupType("org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob"); +// config.setFullBackupType(&quot;org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob&quot;); +// config.setIncrementalBackupType(&quot;org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob&quot;); // start backup using the service manager BackupChain chain = backup.startBackup(config);</programlisting> - <para> + <para> To stop the backup operation, you must use the <literal>BackupChain</literal> instance. </para> - -<programlisting language="Java">// stop backup + <programlisting language="Java">// stop backup backup.stopBackup(chain);</programlisting> - - </section> - - <section id="sect-Reference_Guide-Usage-Performing_a_Restore"> - <title>Performing a Restore</title> - <para> + </section> + <section id="sect-Reference_Guide-Usage-Performing_a_Restore"> + <title>Performing a Restore</title> + <para> Restoration involves reloading the backup file into a <literal>BackupChainLog</literal> and applying appropriate workspace initialization. The following snippet shows the typical sequence for restoring a workspace: </para> - -<programlisting language="Java">// find BackupChain using the repository and workspace names (return null if not found) -BackupChain chain = backup.findBackup("db1", "ws1"); + <programlisting language="Java">// find BackupChain using the repository and workspace names (return null if not found) +BackupChain chain = backup.findBackup(&quot;db1&quot;, &quot;ws1&quot;); // Get the RepositoryEntry and WorkspaceEntry ManageableRepository repo = repositoryService.getRepository(repository); @@ -348,375 +301,313 @@ // run restoration backup.restore(bchLog, repositoryEntry, workspaceEntry);</programlisting> - <section id="sect-Reference_Guide-Performing_a_Restore-Restoring_Into_An_Existing_Workspace"> - <title>Restoring Into An Existing Workspace</title> - <note> - <para> + <section id="sect-Reference_Guide-Performing_a_Restore-Restoring_Into_An_Existing_Workspace"> + <title>Restoring Into An Existing Workspace</title> + <note> + <para> These instructions only applies to regular workspace. Special instructions are provided below for System workspace. </para> - - </note> - <para> + </note> + <para> To restore a backup over an existing workspace, you are required to clear its data. Your backup process should follow these steps: </para> - <procedure id="proc-Reference_Guide-Restoring_Into_An_Existing_Workspace-Restore_Over_a_Workspace"> - <title>Restore Over a Workspace</title> - <step> - <para> + <procedure id="proc-Reference_Guide-Restoring_Into_An_Existing_Workspace-Restore_Over_a_Workspace"> + <title>Restore Over a Workspace</title> + <step> + <para> Remove the workspace: </para> - -<programlisting language="Java">ManageableRepository repo = repositoryService.getRepository(repository); + <programlisting language="Java">ManageableRepository repo = repositoryService.getRepository(repository); repo.removeWorkspace(workspace);</programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Clean the database, value storage and index of references to the workspace. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Perform the Restore. Refer to the snippet above. </para> - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide-Performing_a_Restore-System_workspace"> - <title>System workspace</title> - <note> - <para> + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-Performing_a_Restore-System_workspace"> + <title>System workspace</title> + <note> + <para> The <literal>BackupWorkspaceInitializer</literal> is available in JCR 1.9 and later. </para> - - </note> - <para> + </note> + <para> Restoring the JCR System workspace requires you to shut down the system and use of a special initializer. </para> - <para> + <para> Follow these steps (this will also work for normal workspaces): </para> - <procedure> - <title></title> - <step> - <para> + <procedure> + <title/> + <step> + <para> Stop the repository (or portal). </para> - - </step> - <step> - <para> + </step> + <step> + <para> Clean the database, value storage, index. </para> - - </step> - <step> - <para> + </step> + <step> + <para> In the configuration, set the workspace <literal>BackupWorkspaceInitializer</literal> to refer to your backup. </para> - <para> + <para> For example: </para> - -<programlisting language="XML">&lt;workspaces&gt; - &lt;workspace name="production" ... &gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; + <programlisting language="XML">&lt;workspaces&gt; + &lt;workspace name=&quot;production&quot; ... &gt; + &lt;container class=&quot;org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer&quot;&gt; ... &lt;/container&gt; - &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt; + &lt;initializer class=&quot;org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer&quot;&gt; &lt;properties&gt; - &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_production-20090527_030434"/&gt; + &lt;property name=&quot;restore-path&quot; value=&quot;D:\java\exo-working\backup\repository_production-20090527_030434&quot;/&gt; &lt;/properties&gt; &lt;/initializer&gt; ... &lt;/workspace&gt; </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Restart the repository (or portal). </para> - - </step> - - </procedure> - - - </section> - - - </section> - - <section id="sect-Reference_Guide-Usage-Repository_and_Workspace_Initialization_From_Backup"> - <title>Repository and Workspace Initialization From Backup</title> - <para> + </step> + </procedure> + </section> + </section> + <section id="sect-Reference_Guide-Usage-Repository_and_Workspace_Initialization_From_Backup"> + <title>Repository and Workspace Initialization From Backup</title> + <para> Repository and Workspace initialization from backup can use the <literal>BackupWorkspaceInitializer</literal>. </para> - <para> + <para> Will be configured <literal>BackupWorkspaceInitializer</literal> in configuration of workspace to restore the Workspace from backup over initializer. </para> - <para> + <para> Will be configured <literal>BackupWorkspaceInitializer</literal> in all configurations workspaces of the Repository to restore the Repository from backup over initializer. </para> - <para> + <para> Restoring the repository or workspace requires to shutdown the repository. </para> - <para> + <para> Follow these steps: </para> - <procedure> - <title></title> - <step> - <para> + <procedure> + <title/> + <step> + <para> Stop the repository. This step can be skipped if the repository or workspace does not exist. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Clean the database, value storage and index. This step can be skipped if repository or workspace is new. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Set the <literal>BackupWorkspaceInitializerIn</literal> in the workspace(s) configuration to refer to your backup. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Start repository </para> - - </step> - - </procedure> - - <para> - Below is an example of a configuration initializer set to restore the workspace "<emphasis>backup</emphasis>" over <literal>BackupWorkspaceInitializer</literal>: + </step> + </procedure> + <para> + Below is an example of a configuration initializer set to restore the workspace &quot;<emphasis>backup</emphasis>&quot; over <literal>BackupWorkspaceInitializer</literal>: </para> - -<programlisting language="XML">&lt;workspaces&gt; - &lt;workspace name="backup" ... &gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; + <programlisting language="XML">&lt;workspaces&gt; + &lt;workspace name=&quot;backup&quot; ... &gt; + &lt;container class=&quot;org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer&quot;&gt; ... &lt;/container&gt; - &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt; + &lt;initializer class=&quot;org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer&quot;&gt; &lt;properties&gt; - &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_backup-20110120_044734"/&gt; + &lt;property name=&quot;restore-path&quot; value=&quot;D:\java\exo-working\backup\repository_backup-20110120_044734&quot;/&gt; &lt;/properties&gt; &lt;/initializer&gt; ... &lt;/workspace&gt;</programlisting> - <section id="sect-Reference_Guide-Repository_and_Workspace_Initialization_From_Backup-Restore_the_Workspace_over_BackupWorkspaceInitializer"> - <title>Restore the Workspace over BackupWorkspaceInitializer</title> - <para> - Below is an example of configuration initializer to restore the workspace "<emphasis>backup</emphasis>" over <literal>BackupWorkspaceInitializer</literal>: + <section id="sect-Reference_Guide-Repository_and_Workspace_Initialization_From_Backup-Restore_the_Workspace_over_BackupWorkspaceInitializer"> + <title>Restore the Workspace over BackupWorkspaceInitializer</title> + <para> + Below is an example of configuration initializer to restore the workspace &quot;<emphasis>backup</emphasis>&quot; over <literal>BackupWorkspaceInitializer</literal>: </para> - <procedure> - <title></title> - <step> - <para> + <procedure> + <title/> + <step> + <para> Stop the repository. This can be skipped if the repository does not yet exist. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Clean the database, value storage and index. This step can be skipped if the workspace is new. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Set <parameter>BackupWorkspaceInitializer</parameter> in the workspace configuration to refer to your backup. </para> - -<programlisting language="XML">&lt;workspaces&gt; - &lt;workspace name="backup" ... &gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; + <programlisting language="XML">&lt;workspaces&gt; + &lt;workspace name=&quot;backup&quot; ... &gt; + &lt;container class=&quot;org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer&quot;&gt; ... &lt;/container&gt; - &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt; + &lt;initializer class=&quot;org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer&quot;&gt; &lt;properties&gt; - &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_backup-20110120_044734"/&gt; + &lt;property name=&quot;restore-path&quot; value=&quot;D:\java\exo-working\backup\repository_backup-20110120_044734&quot;/&gt; &lt;/properties&gt; &lt;/initializer&gt; ... &lt;/workspace&gt;</programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Start the repository. </para> - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide-Repository_and_Workspace_Initialization_From_Backup-Restore_the_Repository_over_BackupWorkspaceInitializer"> - <title>Restore the Repository over BackupWorkspaceInitializer</title> - <para> - Below is an example of configuration initializers to restore the repository "<emphasis>repository</emphasis>" over <literal>BackupWorkspaceInitializer</literal>: + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-Repository_and_Workspace_Initialization_From_Backup-Restore_the_Repository_over_BackupWorkspaceInitializer"> + <title>Restore the Repository over BackupWorkspaceInitializer</title> + <para> + Below is an example of configuration initializers to restore the repository &quot;<emphasis>repository</emphasis>&quot; over <literal>BackupWorkspaceInitializer</literal>: </para> - <procedure> - <title></title> - <step> - <para> + <procedure> + <title/> + <step> + <para> Stop the repository. This can be skipped if the repository does not yet exist. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Clean the database, value storage and index. This step can be skipped if the workspace is new. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Configure workspace initializers in the repository configuration to refer to your backup. </para> - -<programlisting language="XML">... + <programlisting language="XML">... &lt;workspaces&gt; - &lt;workspace name="system" ... &gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; + &lt;workspace name=&quot;system&quot; ... &gt; + &lt;container class=&quot;org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer&quot;&gt; ... &lt;/container&gt; - &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt; + &lt;initializer class=&quot;org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer&quot;&gt; &lt;properties&gt; - &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_system-20110120_052334"/&gt; + &lt;property name=&quot;restore-path&quot; value=&quot;D:\java\exo-working\backup\repository_system-20110120_052334&quot;/&gt; &lt;/properties&gt; &lt;/initializer&gt; ... &lt;/workspace&gt; - &lt;workspace name="collaboration" ... &gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; + &lt;workspace name=&quot;collaboration&quot; ... &gt; + &lt;container class=&quot;org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer&quot;&gt; ... &lt;/container&gt; - &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt; + &lt;initializer class=&quot;org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer&quot;&gt; &lt;properties&gt; - &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_collaboration-20110120_052341"/&gt; + &lt;property name=&quot;restore-path&quot; value=&quot;D:\java\exo-working\backup\repository_collaboration-20110120_052341&quot;/&gt; &lt;/properties&gt; &lt;/initializer&gt; ... &lt;/workspace&gt; - &lt;workspace name="backup" ... &gt; - &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; + &lt;workspace name=&quot;backup&quot; ... &gt; + &lt;container class=&quot;org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer&quot;&gt; ... &lt;/container&gt; - &lt;initializer class="org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer"&gt; + &lt;initializer class=&quot;org.exoplatform.services.jcr.impl.core.BackupWorkspaceInitializer&quot;&gt; &lt;properties&gt; - &lt;property name="restore-path" value="D:\java\exo-working\backup\repository_backup-20110120_052417"/&gt; + &lt;property name=&quot;restore-path&quot; value=&quot;D:\java\exo-working\backup\repository_backup-20110120_052417&quot;/&gt; &lt;/properties&gt; &lt;/initializer&gt; ... &lt;/workspace&gt; &lt;/workspaces&gt; </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Start the repository. </para> - - </step> - - </procedure> - - - </section> - - - </section> - - + </step> + </procedure> + </section> </section> - - <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Scheduling_experimental"> - <title>Scheduling (experimental)</title> - <para> + </section> + <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Scheduling_experimental"> + <title>Scheduling (experimental)</title> + <para> The Backup service has an additional feature that can be useful for a production level backup implementation. When you need to organize a backup of a repository, it is necessary to have a tool which will be able to create and manage a cycle of <emphasis>Full</emphasis> and <emphasis>Incremental</emphasis> backups in a periodic manner. </para> - <para> + <para> The service has an internal <literal>BackupScheduler</literal> which can run a configurable cycle of <literal>BackupChains</literal> as if they have been executed by a user during some period of time. The <literal>BackupScheduler</literal> is essentially a user-like daemon which asks the <literal>BackupManager</literal> to start or stop backup operations. </para> - <para> + <para> For that purpose, <literal>BackupScheduler</literal> has the method: <parameter>BackupScheduler.schedule(backupConfig, startDate, stopDate, chainPeriod, incrementalPeriod)</parameter> </para> - <variablelist id="vari-Reference_Guide-Scheduling_experimental-BackupScheduler_Method"> - <title>BackupScheduler Method</title> - <varlistentry> - <term>backupConfig</term> - <listitem> - <para> + <variablelist id="vari-Reference_Guide-Scheduling_experimental-BackupScheduler_Method"> + <title>BackupScheduler Method</title> + <varlistentry> + <term>backupConfig</term> + <listitem> + <para> A ready configuration which will be given to the <literal>BackupManager.startBackup()</literal> method. </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>startDate</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>startDate</term> + <listitem> + <para> The date and time of the backup start. </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>stopDate</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>stopDate</term> + <listitem> + <para> The date and time of the backup stop. </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>chainPeriod</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>chainPeriod</term> + <listitem> + <para> A period after which a current <literal>BackupChain</literal> will be stopped and a new one will be started in seconds. </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>incrementalPeriod</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>incrementalPeriod</term> + <listitem> + <para> If it is greater than <literal>0</literal>, it will be used to override the same value in <literal>backupConfig</literal>. </para> - - </listitem> - - </varlistentry> - - </variablelist> - -<programlisting language="Java">// geting the scheduler from the BackupManager + </listitem> + </varlistentry> + </variablelist> + <programlisting language="Java">// geting the scheduler from the BackupManager BackupScheduler scheduler = backup.getScheduler(); // schedule backup using a ready configuration (Full + Incrementals) to run from startTime @@ -724,7 +615,7 @@ // incremental will rotate result files every 3 hours. scheduler.schedule(config, startTime, stopTime, 3600 * 24, 3600 * 3); -// it's possible to run the scheduler for an uncertain period of time (i.e. without stop time). +// it&apos;s possible to run the scheduler for an uncertain period of time (i.e. without stop time). // schedule backup to run from startTime till it will be stopped manually // also there, the incremental will rotate result files as it configured in BackupConfig scheduler.schedule(config, startTime, null, 3600 * 24, 0); @@ -734,34 +625,31 @@ // the scheduler will search in internal tasks list for task with repository and // workspace name from the configuration and will stop that task. scheduler.unschedule(config);</programlisting> - <para> + <para> When the <literal>BackupScheduler</literal> starts the scheduling, it uses the internal an Timer with <literal>startDate</literal> for the first (or just once) execution. If <literal>chainPeriod</literal> is greater than <literal>0</literal>, then the task is repeated with this value used as a period starting from <literal>startDate</literal>. </para> - <para> + <para> Otherwise, the task will be executed once at <literal>startDate</literal> time. If the scheduler has <literal>stopDate</literal>, it will stop the task (the chain cycle) after <literal>stopDate</literal>. And the last parameter <literal>incrementalPeriod</literal> will be used instead of the same from <literal>BackupConfig</literal> if its values are greater than <literal>0</literal>. </para> - <para> + <para> Starting each task (<literal>BackupScheduler.schedule(...)</literal>), the scheduler creates a task file in the service working directory (see <emphasis role="bold">Configuration</emphasis>, <parameter>backup-dir</parameter>) which describes the task backup configuration and periodic values. These files will be used at the backup service start (JVM start) to reinitialize <literal>BackupScheduler</literal> for continuous task scheduling. Only tasks that do not have a <literal>stopDate</literal> or a <literal>stopDate</literal> not expired will be reinitialized. </para> - <para> - There is one notice about <literal>BackupScheduler</literal> task reinitialization in the current implementation. It comes from the <literal>BackupScheduler</literal> nature and its implemented behavior. As the scheduler is just a virtual user which asks the <literal>BackupManager</literal> to start or stop backup operations, it is not able to reinitialize each existing <literal>BackupChain</literal> before the service (JVM) is stopped. But it's possible to start a new operation with the same configuration via <literal>BackupManager</literal> (that was configured before and stored in a task file). + <para> + There is one notice about <literal>BackupScheduler</literal> task reinitialization in the current implementation. It comes from the <literal>BackupScheduler</literal> nature and its implemented behavior. As the scheduler is just a virtual user which asks the <literal>BackupManager</literal> to start or stop backup operations, it is not able to reinitialize each existing <literal>BackupChain</literal> before the service (JVM) is stopped. But it&apos;s possible to start a new operation with the same configuration via <literal>BackupManager</literal> (that was configured before and stored in a task file). </para> - <para> + <para> This is a main detail of the <literal>BackupScheduler</literal> which should be taken into suggestion of a backup operation design now. In case of reinitialization, the task will have new time values for the backup operation cycle as the <literal>chainPeriod</literal> and <literal>incrementalPeriod</literal> will be applied again. That behavior may be changed in the future. </para> - - </section> - - <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Restore_existing_workspace_or_repository"> - <title>Restore existing workspace or repository</title> - <para> + </section> + <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Restore_existing_workspace_or_repository"> + <title>Restore existing workspace or repository</title> + <para> The restore of existing workspace or repository is available. </para> - <para> + <para> For restore will be used special methods: </para> - -<programlisting language="Java"> /** + <programlisting language="Java"> /** * Restore existing workspace. Previous data will be deleted. * For getting status of workspace restore can use * BackupManager.getLastRestore(String repositoryName, String workspaceName) method @@ -771,7 +659,7 @@ * @param workspaceEntry * new workspace configuration * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -790,7 +678,7 @@ * @param workspaceEntry * new workspace configuration * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -808,7 +696,7 @@ * @param repositoryEntry * new repository configuration * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -826,7 +714,7 @@ * @param repositoryEntry * new repository configuration * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -834,52 +722,43 @@ */ void restoreExistingRepository(RepositoryBackupChainLog log, RepositoryEntry repositoryEntry, boolean asynchronous) throws BackupOperationException, BackupConfigurationException;</programlisting> - <para> + <para> These methods for restore will: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Remove existed workspace or repository; </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Clean database; </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Clean index data; </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Clean value storage; </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Restore from backup. </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Restore_a_workspace_or_a_repository_using_original_configuration"> - <title>Restore a workspace or a repository using original configuration</title> - <para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Restore_a_workspace_or_a_repository_using_original_configuration"> + <title>Restore a workspace or a repository using original configuration</title> + <para> The Backup manager allows you to restore a repository or a workspace using the original configuration stored into the backup log: </para> - -<programlisting language="Java">/** + <programlisting language="Java">/** * Restore existing workspace. Previous data will be deleted. * For getting status of workspace restore can use * BackupManager.getLastRestore(String repositoryName, String workspaceName) method @@ -888,7 +767,7 @@ * @param workspaceBackupIdentifier * identifier to workspace backup. * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -907,7 +786,7 @@ * @param repositoryBackupIdentifier * identifier to repository backup. * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -923,7 +802,7 @@ * @param workspaceBackupIdentifier * identifier to workspace backup. * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -938,7 +817,7 @@ * @param repositoryBackupIdentifier * identifier to repository backup. * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -956,7 +835,7 @@ * @param workspaceBackupSetDir * the directory with backup set * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -974,7 +853,7 @@ * @param repositoryBackupSetDir * the directory with backup set * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -989,7 +868,7 @@ * @param workspaceBackupSetDir * the directory with backup set * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -1004,7 +883,7 @@ * @param repositoryBackupSetDir * the directory with backup set * @param asynchronous - * if 'true' restore will be in asynchronous mode (i.e. in separated thread) + * if &apos;true&apos; restore will be in asynchronous mode (i.e. in separated thread) * @throws BackupOperationException * if backup operation exception occurred * @throws BackupConfigurationException @@ -1012,17 +891,11 @@ */ void restoreRepository(File repositoryBackupSetDir, boolean asynchronous) throws BackupOperationException, BackupConfigurationException;</programlisting> - - </section> - - <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Backup_set_portability"> - <title>Backup set portability</title> - <para> + </section> + <section id="sect-Reference_Guide-eXo_JCR_Backup_Service-Backup_set_portability"> + <title>Backup set portability</title> + <para> The Backup log is stored during the Backup operation into two different locations: <parameter>backup-dir</parameter> directory of <literal>BackupService</literal> to support interactive operations via Backup API (e.g. console) and backup set files for portability (e.g. on another server). </para> - - </section> - - + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/use-external-backup-tool.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/use-external-backup-tool.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/backup/use-external-backup-tool.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,82 +1,67 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter 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 suspened. 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> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/repository-suspend-controller.png" width="444" /> - </imageobject> - - </mediaobject> - <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> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/repository-suspend-controller-suspended.png" /> - </imageobject> - - </mediaobject> - <para> - An "<emphasis>undefined</emphasis>" result means not all components were successfully suspended. Check the console to review the stacktraces. - </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 online. The returned result will be "<emphasis>online</emphasis>". - </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/repository-suspend-controller-online.png" /> - </imageobject> - - </mediaobject> - - </section> - - + <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> + <mediaobject> + <imageobject> + <imagedata width="444" fileref="images/eXoJCR/repository-suspend-controller.png"/> + </imageobject> + </mediaobject> + <para> + To suspend repository you need to invoke the <literal>suspend()</literal> operation. The returned result will be &quot;<emphasis>suspended</emphasis>&quot; if everything passed successfully. + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/eXoJCR/repository-suspend-controller-suspended.png"/> + </imageobject> + </mediaobject> + <para> + An &quot;<emphasis>undefined</emphasis>&quot; 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 &quot;<emphasis>on-line</emphasis>&quot;. + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/eXoJCR/repository-suspend-controller-online.png"/> + </imageobject> + </mediaobject> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/cluster-config.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/cluster-config.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/cluster-config.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Cluster_Configuration"> - <title>Cluster Configuration</title> + <title>Configuring Cluster</title> <section id="sect-Reference_Guide-Cluster_Configuration-Launching_Cluster"> <title>Launching Cluster</title> <section id="sect-Reference_Guide-Launching_Cluster-Deploying_eXo_JCR_to_JBoss_Application_Server"> @@ -21,17 +21,17 @@ </step> <step> <para> - Copy the file into <filename>EPP_HOME/server/<replaceable>PROFILE</replaceable>/deploy</filename> directory. + Copy the file into <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy</filename> directory. </para> </step> <step> <para> - Drop <filename>exo-configuration.xml</filename> into your root <replaceable>EPP_HOME</replaceable> directory. + Drop <filename>exo-configuration.xml</filename> into your root <filename><replaceable>EPP_DIST</replaceable>/jboss-as/</filename> directory. </para> </step> <step> <para> - Configure JAAS by inserting the XML fragment shown below into <filename>EPP_HOME/server/<replaceable>PROFILE</replaceable>/conf/login-config.xml</filename> + Configure JAAS by inserting the XML fragment shown below into <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/conf/login-config.xml</filename> </para> <programlisting language="XML" role="XML">&lt;application-policy name=&quot;exo-domain&quot;&gt; &lt;authentication&gt; Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -54,7 +54,7 @@ JCR services are registered in the Portal container. </para> <para> - Below is an example configuration from the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration.xml</filename> file. + Below is an example configuration from the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration.xml</filename> file. </para> <programlisting linenumbering="numbered" 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"> @@ -63,7 +63,7 @@ The JCR Service can use multiple <emphasis>Repositories</emphasis> and each repository can have multiple <emphasis>Workspaces</emphasis>. </para> <para> - Configure the workspaces by locating the workspace you need to modify in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + Configure the workspaces by locating the workspace you need to modify in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> <para> The repository configuration supports human-readable values. They are not case-sensitive. @@ -406,7 +406,7 @@ <title>Value Storage plug-in configuration (for data container):</title> <note> <para> - The value-storage element is optional. If you don&apos;t include it, the values will be stored as BLOBs inside the database. + 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> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/jdbc-data-container-config.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/jdbc-data-container-config.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/jdbc-data-container-config.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-JDBC_Data_Container_Config"> - <title>JDBC Data Container Config</title> + <title>Configuring the JDBC Data Container</title> <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Introduction"> <title>Introduction</title> <para> @@ -109,7 +109,7 @@ Each database software supports ANSI SQL standards but also has its own specifics. Therefore each database has its own configuration setting in the eXo JCR as a database dialect parameter. More detailed configuration of the database can be set by editing the metadata SQL-script files. </para> <para> - You can find SQL-scripts in <filename>conf/storage/</filename> directory of the <filename><replaceable>EPP_HOME</replaceable>jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib/exo.jcr.component.core-XXX.XXX.jar</filename> file . + You can find SQL-scripts in <filename>conf/storage/</filename> directory of the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib/exo.jcr.component.core-XXX.XXX.jar</filename> file . </para> <para> The following tables show the correspondence between the scripts and databases: Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/multilanguage-support.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/multilanguage-support.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/multilanguage-support.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -37,7 +37,7 @@ <itemizedlist> <listitem> <para> - The configuration file to be modified for these changes is <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + The configuration file to be modified for these changes is <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> </listitem> <listitem> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/search-configuration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/search-configuration.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/search-configuration.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Search_Configuration"> - <title>Search Configuration</title> + <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> @@ -12,7 +12,7 @@ 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>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + The JCR index configuration file is located at <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.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. @@ -528,7 +528,7 @@ </calloutlist> </programlistingco> <para> - The global search index is configured in the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>&lt;VERSION&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the &quot;query-handler&quot; tag. + The global search index is configured in the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>VERSION</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the &quot;query-handler&quot; tag. </para> <programlisting language="XML" role="XML">&lt;query-handler class=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex&quot;&gt; </programlisting> @@ -628,13 +628,13 @@ </programlisting> <para> - in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>&lt;VERSION&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> with the new class: + in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> with the new class: </para> <programlisting language="XML" role="XML">&lt;query-handler class=&quot;mypackage.indexation.MySearchIndex&gt; </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>EPP_HOME</replaceable>/server/<replaceable>&lt;VERSION&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>: + To configure an application to use a new analyzer, add the <parameter>analyzer</parameter> parameter to each query-handler configuration in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.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> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-JBoss_Cache_configuration"> - <title>JBoss Cache configuration</title> + <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> @@ -70,7 +70,7 @@ <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&apos;s components. They are located in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/jbosscache</filename> directory, inside either the <filename>cluster</filename> or <filename>local</filename> directory. + The eXo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR&apos;s components. They are located in <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.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> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/other/link-producer.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/other/link-producer.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/other/link-producer.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,96 +1,83 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Link_Producer_Service"> - <title>Link Producer Service</title> - <para> - The Link Producer Service is a simple service which generates an file that is compatible with the Microsoft link file format. It is an extension of the REST Framework library and is included into the WebDav service. On dispatching a <literal>GET</literal> request the service generates the content of an <filename>.lnk</filename> file, which points to a JCR resource via WebDav. + <title>Link Producer Service</title> + <para> + The Link Producer Service is a simple service which generates an file that is compatible with the Microsoft link file format. It is an extension of the REST Framework library and is included into the WebDAV service. On dispatching a <literal>GET</literal> request the service generates the content of an <filename>.lnk</filename> file, which points to a JCR resource via WebDAV. </para> - <para> + <para> Link Producer has a simple configuration which is described below: </para> - -<programlisting language="XML" role="XML">&lt;component&gt; + <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;org.exoplatform.services.webdav.lnkproducer.LnkProducer&lt;/key&gt; &lt;type&gt;org.exoplatform.services.webdav.lnkproducer.LnkProducer&lt;/type&gt; &lt;/component&gt;</programlisting> - <para> - When using JCR the resource can be addressed by WebDav reference (href) like <uri>http://host:port/rest/jcr/repository/workspace/somenode/somefile.extension</uri> , the link servlet must be called for this resource by several hrefs, like <uri>http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extension</uri> + <para> + When using JCR the resource can be addressed by WebDAV reference (href) like <uri>http://host:port/rest/jcr/repository/workspace/<replaceable>somenode</replaceable><replaceable>/somefile</replaceable><replaceable>.extension</replaceable></uri> , the link servlet must be called for this resource by several hrefs, like <uri>http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/<replaceable>somenode</replaceable>/<replaceable>somefile.extension</replaceable></uri> </para> - <para> + <para> Please note, that when using the portal mode the REST servlet is available using a reference (href) like <uri>http://localhost:8080/portal/rest/...</uri> </para> - <para> + <para> The name of the <filename>.lnk</filename> file can be any. But for the best compatibility it must be the same as the name of the JCR resource. </para> - <para> + <para> Here is a step by step sample of a use case of the link producer. </para> - <procedure> - <title></title> - <step> - <para> - Type valid reference to the resource, using the link producer in your browser's adress field: + <procedure> + <title/> + <step> + <para> + Type valid reference to the resource, using the link producer in your browser&apos;s address field: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/other/lnkproducer1.JPG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - <step> - <para> + <mediaobject> + <imageobject> + <imagedata width="444" fileref="images/eXoJCR/other/lnkproducer1.JPG"/> + </imageobject> + </mediaobject> + </step> + <step> + <para> Internet Explorer will give a dialog window requesting to Open a file or to Save it. Click on the Open button </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/other/lnkproducer2.JPG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - <step> - <para> + <mediaobject> + <imageobject> + <imagedata width="444" fileref="images/eXoJCR/other/lnkproducer2.JPG"/> + </imageobject> + </mediaobject> + </step> + <step> + <para> In Windows system an <filename>.lnk</filename> file will be downloaded and opened with the application which is registered to open the files, which are pointed to by the <filename>.lnk</filename> file. In case of a .doc file, Windows opens Microsoft Office Word which will try to open a remote file (test0000.doc). Maybe it will be necessary to enter USERNAME and PASSWORD. </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/other/lnkproducer3.JPG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - <step> - <para> + <mediaobject> + <imageobject> + <imagedata width="444" fileref="images/eXoJCR/other/lnkproducer3.JPG"/> + </imageobject> + </mediaobject> + </step> + <step> + <para> Edit the file in Microsoft Word. </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/other/lnkproducer4.JPG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - - </procedure> - - <para> + <mediaobject> + <imageobject> + <imagedata width="444" fileref="images/eXoJCR/other/lnkproducer4.JPG"/> + </imageobject> + </mediaobject> + </step> + </procedure> + <para> The Link Producer is necessary for opening/editing and then saving the remote files in Microsoft Office Word, without any further updates. </para> - <para> + <para> Also the Link Producer can be referenced to from an HTML page. If page contains code such as... </para> - -<programlisting language="HTML" role="HTML">&lt;a href="http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extension"&gt;somefile.extension&lt;/a&gt;</programlisting> - <para> - ...the file "somefile.extension" will open directly. + <programlisting language="HTML" role="HTML">&lt;a href=&quot;http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extension&quot;&gt;somefile.extension&lt;/a&gt;</programlisting> + <para> + ...the file &quot;somefile.extension&quot; will open directly. </para> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/performance-tuning-guide.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/performance-tuning-guide.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/performance-tuning-guide.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,442 +1,281 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter 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> + <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 AS 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> - </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> - <colspec colname="2"></colspec> - <spanspec nameend="2" namest="1" spanname="hspan"></spanspec> <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 AS 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> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/perf_EC2_results.jpg" /> - </imageobject> - - </mediaobject> - <table> - <title></title> - <tgroup cols="4"> - <thead> - <row> - <entry> - Nodes count - </entry> - <entry> - tps - </entry> - <entry> - Responses &gt;2s - </entry> - <entry> - Responses &gt;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> - <mediaobject> - <imageobject> - <imagedata fileref="images/eXoJCR/perf_EC2_results_2.jpg" /> - </imageobject> - - </mediaobject> - <table> - <title></title> - <tgroup cols="4"> - <thead> - <row> - <entry> - Nodes count - </entry> - <entry> - tps - </entry> - <entry> - Responses &gt;2s - </entry> - <entry> - Responses &gt;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 AS 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 loadbalacer, 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"> &lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/eXoJCR/perf_EC2_results.jpg"/> + </imageobject> + </mediaobject> + <table> + <title/> + <tgroup cols="4"> + <thead> + <row> + <entry> Nodes count </entry> + <entry> tps </entry> + <entry> Responses &gt;2s </entry> + <entry> Responses &gt;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> + <mediaobject> + <imageobject> + <imagedata fileref="images/eXoJCR/perf_EC2_results_2.jpg"/> + </imageobject> + </mediaobject> + <table> + <title/> + <tgroup cols="4"> + <thead> + <row> + <entry> Nodes count </entry> + <entry> tps </entry> + <entry> Responses &gt;2s </entry> + <entry> Responses &gt;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 AS 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&apos;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&apos;s recommended to use &quot;multiplexer stack&quot; 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"> &lt;clustering mode=&quot;replication&quot; clusterName=&quot;${jbosscache-cluster-name}&quot;&gt; ... - &lt;sync replTimeout="60000" /&gt; + &lt;sync replTimeout=&quot;60000&quot; /&gt; &lt;/clustering&gt; </programlisting> - <para> - value is set in miliseconds. - </para> - - </section> - - <!-- <section id="sect-Reference_Guide-Performance_Tuning_Guide-JVM_parameters"> + <para> + value is set in milliseconds. + </para> + </section> +<!-- <section id="sect-Reference_Guide-Performance_Tuning_Guide-JVM_parameters"> <title>JVM parameters</title> <para> <citetitle>PermGen space size</citetitle> @@ -445,9 +284,5 @@ If you intend to use Infinispan, you will have to increase the PermGen size to at least 256 Mo due to the latest versions of JGroups that are needed by Infinispan (please note that Infinspan is only dedicated to the community for now, no support will be provided). In case, you intend to use JBoss Cache, you can keep on using JGroups 2.6.13.GA which means that you don't need to increase the PermGen size. </para> - </section> --> - </section> - - + </section> --> </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/protocols/webdav.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/protocols/webdav.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/protocols/webdav.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,54 +1,52 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-WebDAV"> - <title>WebDAV</title> - <section id="sect-Reference_Guide-WebDAV-Introduction"> - <title>Introduction</title> - <para> + <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> + <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> + 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> + <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 type="http" url="http://host:port/portal/rest/private/jcr/{RepositoryName}/{WorkspaceName}/{Path}" /> + <para> + <ulink url="http://host:port/portal/rest/private/jcr/{RepositoryName}/{WorkspaceName}/{Path}" type="http"/> </para> - <para> - When accessing the WebDAV server via <ulink type="http" url="http://localhost:8080/rest/jcr/repository/production" />, you can substitute <ulink type="http" url="http://localhost:8080/rest/jcr/repository/production">production</ulink> with <ulink type="http" url="http://localhost:8080/rest/jcr/repository/collaboration">collaboration</ulink>. + <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> + <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: + <note> + <title>Note:</title> + <para> + If you try the &quot;in ECM&quot; option, add &quot;@ecm&quot; to the user&apos;s password. Alternatively, you may modify jaas.conf by adding the <emphasis role="bold">domain=ecm</emphasis> option as follows: </para> - -<programlisting>exo-domain { + <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> + </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">&lt;component&gt; + <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;org.exoplatform.services.webdav.WebDavServiceImpl&lt;/key&gt; &lt;type&gt;org.exoplatform.services.webdav.WebDavServiceImpl&lt;/type&gt; &lt;init-params&gt; @@ -63,7 +61,7 @@ &lt;!-- this is the value of WWW-Authenticate header --&gt; &lt;value-param&gt; &lt;name&gt;auth-header&lt;/name&gt; - &lt;value&gt;Basic realm="eXo-Platform Webdav Server 1.6.1"&lt;/value&gt; + &lt;value&gt;Basic realm=&quot;eXo-Platform Webdav Server 1.6.1&quot;&lt;/value&gt; &lt;/value-param&gt; &lt;!-- default node type which is used for the creation of collections --&gt; @@ -78,7 +76,7 @@ &lt;value&gt;nt:file&lt;/value&gt; &lt;/value-param&gt; - &lt;!-- if MimeTypeResolver can't find the required mime type, + &lt;!-- if MimeTypeResolver can&apos;t find the required mime type, which conforms with the file extension, and the mimeType header is absent in the HTTP request header, this parameter is used as the default mime type--&gt; @@ -88,9 +86,9 @@ &lt;/value-param&gt; &lt;!-- This parameter indicates one of the three cases when you update the content of the resource by PUT command. - In case of "create-version", PUT command creates the new version of the resource if this resource exists. - In case of "replace" - if the resource exists, PUT command updates the content of the resource and its last modification date. - In case of "add", the PUT command tries to create the new resource with the same name (if the parent node allows same-name siblings).--&gt; + In case of &quot;create-version&quot;, PUT command creates the new version of the resource if this resource exists. + In case of &quot;replace&quot; - if the resource exists, PUT command updates the content of the resource and its last modification date. + In case of &quot;add&quot;, the PUT command tries to create the new resource with the same name (if the parent node allows same-name siblings).--&gt; &lt;value-param&gt; &lt;name&gt;update-policy&lt;/name&gt; @@ -101,8 +99,8 @@ &lt;!-- This parameter determines how service responds to a method that attempts to modify file content. - In case of "checkout-checkin" value, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout and followed by a checkin operation. - In case of "checkout" value, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation. + In case of &quot;checkout-checkin&quot; value, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout and followed by a checkin operation. + In case of &quot;checkout&quot; value, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation. --&gt; &lt;value-param&gt; &lt;name&gt;auto-version&lt;/name&gt; @@ -112,7 +110,7 @@ &lt;!-- This parameter is responsible for managing Cache-Control header value which will be returned to the client. - You can use patterns like "text/*", "image/*" or wildcard to define the type of content. + You can use patterns like &quot;text/*&quot;, &quot;image/*&quot; or wildcard to define the type of content. --&gt; &lt;value-param&gt; &lt;name&gt;cache-control&lt;/name&gt; @@ -130,357 +128,221 @@ &lt;/init-params&gt; &lt;/component&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-WebDAV-Corresponding_WebDav_and_JCR_actions"> - <title>Corresponding WebDav and JCR actions</title> - <table> - <title></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> - <!-- DOCS NOTE: This content is duplicated in the Site Publisher User Guide to avoid cross-document linking. - Any changes here should also be made there--> - <para> + </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(&quot;node&quot;,&quot;nt:file&quot;); Node.setProperty(&quot;jcr:data&quot;, &quot;data&quot;) </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(&quot;mix:versionable&quot;) </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> +<!-- DOCS NOTE: This content is duplicated in the Site Publisher User Guide to avoid cross-document linking. + Any changes here should also be made there--> <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> + <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> + </formalpara> + <para> To fix this, do as follows: </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> Go to Windows Registry Editor. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Find a key: \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlset\services\WebClient\Parameters\BasicAuthLevel . </para> - - </step> - <step> - <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> + </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> + </formalpara> + <itemizedlist> + <listitem> + <para> Microsoft Office 2007/2010 applications installed on a client computer AND... </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> The client computer is connected to a web server configured for Basic authentication VIA... </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> A connection that does not use Secure Sockets Layer (SSL) AND... </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> You try to access an Office file that is stored on the remote server... </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> You might experience the following symptoms when you try to open or to download the file: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> The Office file does not open or download. </para> - - </listitem> - <listitem> - <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> + </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> - + </listitem> </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> These outcomes can be circumvented by enabling Basic authentication on the client machine. </para> - <para> + <para> To enable Basic authentication on the client computer, follow these steps: </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> Click Start, type <literal>regedit</literal> in the Start Search box, and then press Enter. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Locate and then click the following registry subkey: </para> - <para> + <para> <envar>HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Common\Internet</envar> </para> - - </step> - <step> - <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> + </step> + <step> + <para> Type <literal>BasicAuthLevel</literal>, and then press <keycap>Enter</keycap>. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Right-click <literal>BasicAuthLevel</literal>, and then click <guilabel>Modify</guilabel>. </para> - - </step> - <step> - <para> + </step> + <step> + <para> In the Value data box, type <literal>2</literal>, and then click <guilabel>OK</guilabel>. </para> - - </step> - - </procedure> - - </section> - - + </step> + </procedure> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/query-handler-config.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/query-handler-config.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/query-handler-config.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,588 +1,455 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-QueryHandler_configuration"> - <title>QueryHandler configuration</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. + <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&apos;s why eXo JCR offers two strategies that are suitable for it&apos;s own usecases. They are clustered with shared index and clustered with local indexes. Each one has it&apos;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> + Clustered implementation with local indexes combines in-memory buffer index directory with delayed file-system flushing. This index is called &quot;Volatile&quot; and it is invoked in searches also. Within some conditions volatile index is flushed to the persistent storage (file system) as new index directory. This allows to achieve great results for write operations. </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/eXoJCR/diagram-local-index.png" width="444" /> - </imageobject> - - </mediaobject> - <para> - As this implementation designed for clustered environment it has additional mechanisms for data delivery within cluster. Actual text extraction jobs done on the same node that does content operations (i.e. write operation). Prepared "documents" (Lucene term that means block of data ready for indexing) are replicated withing cluster nodes and processed by local indexes. So each cluster instance has the same index content. When new node joins the cluster it has no initial index, so it must be created. There are some supported ways of doing this operation. The simplest is to simply copy the index manually but this is not intended for use. If no initial index found JCR uses automated scenarios. They are controlled via configuration (see "index-recovery-mode" parameter) offering full re-indexing from database or copying from another cluster node. + <mediaobject> + <imageobject> + <imagedata width="444" align="center" fileref="images/eXoJCR/diagram-local-index.png"/> + </imageobject> + </mediaobject> + <para> + As this implementation designed for clustered environment it has additional mechanisms for data delivery within cluster. Actual text extraction jobs done on the same node that does content operations (i.e. write operation). Prepared &quot;documents&quot; (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 &quot;index-recovery-mode&quot; parameter) offering full re-indexing from database or copying from another cluster node. </para> - <para> + <para> For some reasons having a multiple index copies on each instance can be costly. So shared index can be used instead (see diagram below). </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/eXoJCR/diagram-shared-index.png" width="444" /> - </imageobject> - - </mediaobject> - <para> - This indexing strategy combines advantages of in-memory index along with shared persistent index offering "near" real time search capabilities. This means that newly added content is accessible via search practically immediately. This strategy allows nodes to index data in their own volatile (in-memory) indexes, but persistent indexes are managed by single "coordinator" node only. Each cluster instance has a read access for shared index to perform queries combining search results found in own in-memory index also. Take in account that shared folder must be configured in your system environment (i.e. mounted NFS folder). But this strategy in some extremely rare cases can have a bit different volatile indexes within cluster instances for a while. In a few seconds they will be up2date. + <mediaobject> + <imageobject> + <imagedata width="444" align="center" fileref="images/eXoJCR/diagram-shared-index.png"/> + </imageobject> + </mediaobject> + <para> + This indexing strategy combines advantages of in-memory index along with shared persistent index offering &quot;near&quot; 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 &quot;coordinator&quot; 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> + 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> + </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">&lt;workspace name="ws"&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + <programlisting language="XML" role="XML">&lt;workspace name=&quot;ws&quot;&gt; + &lt;query-handler class=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex&quot;&gt; &lt;properties&gt; - &lt;property name="index-dir" value="shareddir/index/db1/ws" /&gt; - &lt;property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /&gt; - &lt;property name="jbosscache-configuration" value="jbosscache-indexer.xml" /&gt; - &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /&gt; - &lt;property name="max-volatile-time" value="60" /&gt; - &lt;property name="rdbms-reindexing" value="true" /&gt; - &lt;property name="reindexing-page-size" value="1000" /&gt; - &lt;property name="index-recovery-mode" value="from-coordinator" /&gt; - &lt;property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /&gt; + &lt;property name=&quot;index-dir&quot; value=&quot;shareddir/index/db1/ws&quot; /&gt; + &lt;property name=&quot;changesfilter-class&quot; + value=&quot;org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter&quot; /&gt; + &lt;property name=&quot;jbosscache-configuration&quot; value=&quot;jbosscache-indexer.xml&quot; /&gt; + &lt;property name=&quot;jgroups-configuration&quot; value=&quot;udp-mux.xml&quot; /&gt; + &lt;property name=&quot;jgroups-multiplexer-stack&quot; value=&quot;true&quot; /&gt; + &lt;property name=&quot;jbosscache-cluster-name&quot; value=&quot;JCR-cluster-indexer-ws&quot; /&gt; + &lt;property name=&quot;max-volatile-time&quot; value=&quot;60&quot; /&gt; + &lt;property name=&quot;rdbms-reindexing&quot; value=&quot;true&quot; /&gt; + &lt;property name=&quot;reindexing-page-size&quot; value=&quot;1000&quot; /&gt; + &lt;property name=&quot;index-recovery-mode&quot; value=&quot;from-coordinator&quot; /&gt; + &lt;property name=&quot;index-recovery-filter&quot; value=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter&quot; /&gt; &lt;/properties&gt; &lt;/query-handler&gt; &lt;/workspace&gt; </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> + <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&apos;s startup. If this flag is set, indexing will be launched asynchronously, without blocking the JCR. Default is &quot;<literal>false</literal>&quot;. </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></title> - <step> - <para> - Set the parameter "<parameter>enable_seqscan</parameter>" to "<literal>off</literal>" + </formalpara> + <procedure> + <title/> + <step> + <para> + Set the parameter &quot;<parameter>enable_seqscan</parameter>&quot; to &quot;<literal>off</literal>&quot; </para> - <para> + <para> <emphasis role="bold">OR</emphasis> </para> - <para> - Set "<parameter>default_statistics_target</parameter>" to at least "<literal>50</literal>". + <para> + Set &quot;<parameter>default_statistics_target</parameter>&quot; to at least &quot;<literal>50</literal>&quot;. </para> - - </step> - <step> - <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> + </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></title> - <step> - <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 &lt;scheme&gt;.&lt;table&gt; 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. + <programlisting><code>RUNSTATS ON TABLE &lt;scheme&gt;.&lt;table&gt; 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 (&quot;indexDir&quot; value) must point to it. Setting &quot;changesfilter-class&quot; to &quot;org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter&quot; will enable shared index implementation. </para> - -<programlisting language="XML" role="XML">&lt;workspace name="ws"&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + <programlisting language="XML" role="XML">&lt;workspace name=&quot;ws&quot;&gt; + &lt;query-handler class=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex&quot;&gt; &lt;properties&gt; - &lt;property name="index-dir" value="/mnt/nfs_drive/index/db1/ws" /&gt; - &lt;property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" /&gt; - &lt;property name="jbosscache-configuration" value="jbosscache-indexer.xml" /&gt; - &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /&gt; - &lt;property name="max-volatile-time" value="60" /&gt; - &lt;property name="rdbms-reindexing" value="true" /&gt; - &lt;property name="reindexing-page-size" value="1000" /&gt; - &lt;property name="index-recovery-mode" value="from-coordinator" /&gt; + &lt;property name=&quot;index-dir&quot; value=&quot;/mnt/nfs_drive/index/db1/ws&quot; /&gt; + &lt;property name=&quot;changesfilter-class&quot; + value=&quot;org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter&quot; /&gt; + &lt;property name=&quot;jbosscache-configuration&quot; value=&quot;jbosscache-indexer.xml&quot; /&gt; + &lt;property name=&quot;jgroups-configuration&quot; value=&quot;udp-mux.xml&quot; /&gt; + &lt;property name=&quot;jgroups-multiplexer-stack&quot; value=&quot;true&quot; /&gt; + &lt;property name=&quot;jbosscache-cluster-name&quot; value=&quot;JCR-cluster-indexer-ws&quot; /&gt; + &lt;property name=&quot;max-volatile-time&quot; value=&quot;60&quot; /&gt; + &lt;property name=&quot;rdbms-reindexing&quot; value=&quot;true&quot; /&gt; + &lt;property name=&quot;reindexing-page-size&quot; value=&quot;1000&quot; /&gt; + &lt;property name=&quot;index-recovery-mode&quot; value=&quot;from-coordinator&quot; /&gt; &lt;/properties&gt; &lt;/query-handler&gt; &lt;/workspace&gt;</programlisting> - <para> - In order to use cluster-ready strategy based on local indexes, when each node has own copy of index on local file system, the following configuration must be applied. Indexing directory must point to any folder on local file system and "changesfilter-class" must be set to "org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter". + <para> + 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 &quot;changesfilter-class&quot; must be set to &quot;org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter&quot;. </para> - -<programlisting language="XML" role="XML">&lt;workspace name="ws"&gt; - &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; + <programlisting language="XML" role="XML">&lt;workspace name=&quot;ws&quot;&gt; + &lt;query-handler class=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex&quot;&gt; &lt;properties&gt; - &lt;property name="index-dir" value="/mnt/nfs_drive/index/db1/ws" /&gt; - &lt;property name="changesfilter-class" - value="org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter" /&gt; - &lt;property name="jbosscache-configuration" value="jbosscache-indexer.xml" /&gt; - &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="JCR-cluster-indexer-ws" /&gt; - &lt;property name="max-volatile-time" value="60" /&gt; - &lt;property name="rdbms-reindexing" value="true" /&gt; - &lt;property name="reindexing-page-size" value="1000" /&gt; - &lt;property name="index-recovery-mode" value="from-coordinator" /&gt; + &lt;property name=&quot;index-dir&quot; value=&quot;/mnt/nfs_drive/index/db1/ws&quot; /&gt; + &lt;property name=&quot;changesfilter-class&quot; + value=&quot;org.exoplatform.services.jcr.impl.core.query.jbosscache.LocalIndexChangesFilter&quot; /&gt; + &lt;property name=&quot;jbosscache-configuration&quot; value=&quot;jbosscache-indexer.xml&quot; /&gt; + &lt;property name=&quot;jgroups-configuration&quot; value=&quot;udp-mux.xml&quot; /&gt; + &lt;property name=&quot;jgroups-multiplexer-stack&quot; value=&quot;true&quot; /&gt; + &lt;property name=&quot;jbosscache-cluster-name&quot; value=&quot;JCR-cluster-indexer-ws&quot; /&gt; + &lt;property name=&quot;max-volatile-time&quot; value=&quot;60&quot; /&gt; + &lt;property name=&quot;rdbms-reindexing&quot; value=&quot;true&quot; /&gt; + &lt;property name=&quot;reindexing-page-size&quot; value=&quot;1000&quot; /&gt; + &lt;property name=&quot;index-recovery-mode&quot; value=&quot;from-coordinator&quot; /&gt; &lt;/properties&gt; &lt;/query-handler&gt; &lt;/workspace&gt; </programlisting> - - </section> - - <section id="sect-Reference_Guide-Configuration-Local_Index_Recovery_Filters"> - <title>Local Index Recovery Filters</title> - <para> + </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> + <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> + <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> + <para> The JBoss Enterprise 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">&lt;property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /&gt;</programlisting> - <para> + <programlisting language="XML">&lt;property name=&quot;index-recovery-filter&quot; value=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter&quot; /&gt;</programlisting> + <para> Filter numbers are not limited so they can be combined: </para> - -<programlisting language="XML">&lt;property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter" /&gt; - &lt;property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.SystemPropertyRecoveryFilter" /&gt; + <programlisting language="XML">&lt;property name=&quot;index-recovery-filter&quot; value=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter&quot; /&gt; + &lt;property name=&quot;index-recovery-filter&quot; value=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.SystemPropertyRecoveryFilter&quot; /&gt; </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> + If any one returns fires, the index is re-synchronized. This feature uses standard index recovery mode defined by previously described parameter (can be &quot;from-indexing&quot; (default) or &quot;from-coordinator&quot;) </para> - -<programlisting language="XML">&lt;property name="index-recovery-mode" value="from-coordinator" /&gt; + <programlisting language="XML">&lt;property name=&quot;index-recovery-mode&quot; value=&quot;from-coordinator&quot; /&gt; </programlisting> - <para> + <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></term> - <listitem> - <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. + </listitem> + </varlistentry> + <varlistentry> + <term>org.exoplatform.services.jcr.impl.core.query.lucene.SystemPropertyRecoveryFilter</term> + <listitem> + <para> + Returns value of system property &quot;<literal>org.exoplatform.jcr.recoveryfilter.forcereindexing</literal>&quot;. 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: + </listitem> + </varlistentry> + <varlistentry> + <term>org.exoplatform.services.jcr.impl.core.query.lucene.ConfigurationPropertyRecoveryFilter</term> + <listitem> + <para> + Returns value of <literal>QueryHandler</literal> configuration property &quot;<literal>index-recovery-filter-forcereindexing</literal>&quot;. So index recovery can be controlled from configuration separately for each workspace. For example: </para> - -<programlisting language="XML">&lt;property name="index-recovery-filter" value="org.exoplatform.services.jcr.impl.core.query.lucene.ConfigurationPropertyRecoveryFilter" /&gt; - &lt;property name="index-recovery-filter-forcereindexing" value="true" /&gt; + <programlisting language="XML">&lt;property name=&quot;index-recovery-filter&quot; value=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.ConfigurationPropertyRecoveryFilter&quot; /&gt; + &lt;property name=&quot;index-recovery-filter-forcereindexing&quot; value=&quot;true&quot; /&gt; </programlisting> - - </listitem> - - </varlistentry> - <varlistentry> - <term>org.exoplatform.services.jcr.impl.core.query.lucene.DocNumberRecoveryFilter</term> - <listitem> - <para> + </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> + <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> + <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> + <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> + </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">&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; - &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" - lockAcquisitionTimeout="20000" /&gt; + <example id="exam-Reference_Guide-JBoss_Cache_template_configuration-jbosscache_indexer.xml"> + <title>jbosscache-indexer.xml</title> + <programlisting language="XML" role="XML">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; +&lt;jbosscache xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; xmlns=&quot;urn:jboss:jbosscache-core:config:3.1&quot;&gt; + &lt;locking useLockStriping=&quot;false&quot; concurrencyLevel=&quot;50000&quot; lockParentForChildInsertRemove=&quot;false&quot; + lockAcquisitionTimeout=&quot;20000&quot; /&gt; &lt;!-- Configure the TransactionManager --&gt; - &lt;transaction transactionManagerLookupClass="org.jboss.cache.transaction.JBossStandalone - JTAManagerLookup" /&gt; - &lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; - &lt;jgroupsConfig multiplexerStack="jcr.stack" /&gt; + &lt;transaction transactionManagerLookupClass=&quot;org.jboss.cache.transaction.JBossStandalone + JTAManagerLookup&quot; /&gt; + &lt;clustering mode=&quot;replication&quot; clusterName=&quot;${jbosscache-cluster-name}&quot;&gt; + &lt;stateRetrieval timeout=&quot;20000&quot; fetchInMemoryState=&quot;false&quot; /&gt; + &lt;jgroupsConfig multiplexerStack=&quot;jcr.stack&quot; /&gt; &lt;sync /&gt; &lt;/clustering&gt; &lt;!-- Eviction configuration --&gt; - &lt;eviction wakeUpInterval="5000"&gt; - &lt;default algorithmClass="org.jboss.cache.eviction.FIFOAlgorithm" eventQueueSize="1000000"&gt; - &lt;property name="maxNodes" value="10000" /&gt; - &lt;property name="minTimeToLive" value="60000" /&gt; + &lt;eviction wakeUpInterval=&quot;5000&quot;&gt; + &lt;default algorithmClass=&quot;org.jboss.cache.eviction.FIFOAlgorithm&quot; eventQueueSize=&quot;1000000&quot;&gt; + &lt;property name=&quot;maxNodes&quot; value=&quot;10000&quot; /&gt; + &lt;property name=&quot;minTimeToLive&quot; value=&quot;60000&quot; /&gt; &lt;/default&gt; &lt;/eviction&gt; &lt;/jbosscache&gt;</programlisting> - - </example> - <para> - Read more about template configurations <xref linkend="chap-Reference_Guide-JBoss_Cache_configuration" />. + </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 Reindexing</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. + </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 &quot;re-indexing&quot;. There are various usecases when it&apos;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&apos;s startup or in runtime. </para> - <section id="sect-Reference_Guide-Asynchronous_Reindexing-On_startup_indexing"> - <title>On startup indexing</title> - <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> + <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> + <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> + <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> + <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> + <para> The index state check is accomplished via <literal>QueryManagerImpl</literal>: </para> - <para> + <para> <programlisting lang="java">boolean online = ((QueryManagerImpl)Workspace.getQueryManager()).getQueryHandeler().isOnline();</programlisting> </para> - <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> + <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]). + <programlisting>[INFO] Created initial index for 143018 nodes (repository/production[system]). [INFO] Setting index ONLINE (repository/production[system]).</programlisting> - <para> + <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 Reindexing via JMX</title> - <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> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/eXoJCR/jmx-jconsole.png" /> - </imageobject> - - </mediaobject> - <para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/eXoJCR/jmx-jconsole.png"/> + </imageobject> + </mediaobject> + <para> The server can continue working as expected while the index is recreated. </para> - <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> + <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> + <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> + <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> + <para> When the operation is finished, the stale index is replaced by the newly created index, which included any newly added data. </para> - <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> + <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> + </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> + Also; <emphasis>Hot Asynchronous Reindexing via JMX</emphasis> and <literal>on startup</literal> reindexing are different features. So you can&apos;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> + <itemizedlist> + <listitem> + <para> getIOMode - returns current index IO mode (READ_ONLY / READ_WRITE), belongs to clustered configuration states; </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> getState - returns current state: ONLINE / OFFLINE. </para> - - </listitem> - - </itemizedlist> - - </section> - - + </listitem> + </itemizedlist> </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> + </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> + <para> By default, the JCR implementation uses optimal combination of Directory implementation and Lock Factory implementation. </para> - <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> + <para> <literal>NativeFSLockFactory</literal> is an optimal solution for a wide variety of cases including clustered environment with NFS shared resources. </para> - <para> + <para> But those defaults can be overridden in the system properties. </para> - <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> + <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> + <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> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/repository-check-controller.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/repository-check-controller.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/repository-check-controller.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,107 +1,82 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter 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 Enterprise 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 app directory and named as per the following convention: <code> report-<replaceable>&lt;repository name&gt;</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> - <title></title> - <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 reindexing 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> - - + <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 Enterprise 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>&lt;repository name&gt;</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 &quot;Reindex&quot; 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> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/fulltext-search-and-settings.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/fulltext-search-and-settings.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/fulltext-search-and-settings.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,296 +1,179 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Fulltext_Search_And_Affecting_Settings"> - <title>Fulltext 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&amp;Z Corporation - xyz(a)example.com&quot;&lt;/title&gt; - <tgroup cols="2"> - <thead> - <row> - <entry> - Analyzer - </entry> - <entry> - Parsed - </entry> - - </row> - - </thead> - <tbody> - <row> - <entry> - org.apache.lucene.analysis.WhitespaceAnalyzer - </entry> - <entry> - [XY&amp;Z] [Corporation] [-] [xyz(a)example.com] - </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&amp;z] [corporation] [xyz@example] [com] - </entry> - - </row> - <row> - <entry> - org.apache.lucene.analysis.snowball.SnowballAnalyzer - </entry> - <entry> - [xy&amp;z] [corpor] [xyz@exampl] [com] - </entry> - - </row> - <row> - <entry> - org.apache.lucene.analysis.standard.StandardAnalyzer (configured without stop word - jcr default analyzer) - </entry> - <entry> - [xy&amp;z] [corporation] [xyz@example] [com] - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <note> - <para> - <literal>StandardAnalyzer</literal> is the default analyzer in the JBoss Enterprise 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." + <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>&quot;The quick brown fox jumped over the lazy dogs&quot;</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>&quot;XY&amp;Z Corporation - xyz(a)example.com&amp;quot;&lt;/title&gt; + <tgroup cols="2"> + <thead> + <row> + <entry> Analyzer </entry> + <entry> Parsed </entry> + </row> + </thead> + <tbody> + <row> + <entry> org.apache.lucene.analysis.WhitespaceAnalyzer </entry> + <entry> [XY&amp;Z] [Corporation] [-] [xyz(a)example.com] </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&amp;z] [corporation] [xyz@example] [com] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.snowball.SnowballAnalyzer </entry> + <entry> [xy&amp;z] [corpor] [xyz@exampl] [com] </entry> + </row> + <row> + <entry> org.apache.lucene.analysis.standard.StandardAnalyzer (configured without stop word - jcr default analyzer) </entry> + <entry> [xy&amp;z] [corporation] [xyz@example] [com] </entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <para> + <literal>StandardAnalyzer</literal> is the default analyzer in the JBoss Enterprise 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, &apos;some string&apos;)</programlisting> + <para> + This is because,&#160;<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( * , &apos;some string&apos;)</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 &apos;mix:title&apos; and different values of &apos;jcr:description&apos; property. + </para> + <programlisting>root + ├── document1 (mix:title) jcr:description = &quot;The quick brown fox jumped over the lazy dogs&quot; + ├── document2 (mix:title) jcr:description = &quot;Brown fox live in forest.&quot; + └── document3 (mix:title) jcr:description = &quot;Fox is a nice animal.&quot; </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 + <para> + The example below shows different Analyzers in action. The first instance uses base JCR settings, so the string; &quot;<emphasis>The quick brown fox jumped over the lazy dogs</emphasis>&quot; 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')"; +String sqlStatement = &quot;SELECT * FROM mix:title WHERE CONTAINS(jcr:description, &apos;the&apos;)&quot;; // 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> - - + <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 &quot;<emphasis>the</emphasis>&quot; will be excluded from parsed string set. + </para> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/jcr-query-usecases.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/jcr-query-usecases.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/jcr-query-usecases.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,62 +1,51 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-JCR_Query_Usecases"> - <title>JCR Query Usecases</title> - <section id="sect-Reference_Guide-JCR_Query_Usecases-Introduction"> - <title>Introduction</title> - <para> + <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();  + </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();&#160; // make SQL query -Query query = queryManager.createQuery("SELECT * FROM nt:base ", Query.SQL); +Query query = queryManager.createQuery(&quot;SELECT * FROM nt:base &quot;, 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 + </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); +Query query = queryManager.createQuery(&quot;//element(*,nt:base)&quot;, 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 + </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> + <para> To fetch the nodes: </para> - -<programlisting language="Java" role="Java">NodeIterator it = result.getNodes();</programlisting> - <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 + <programlisting language="Java" role="Java">// get column names String[] columnNames = result.getColumnNames(); // get column rows RowIterator rowIterator = result.getRows(); @@ -66,38 +55,27 @@ // get all values of row Value[] values = row.getValues(); }</programlisting> - - </section> - - <section id="sect-Reference_Guide-Query_Lifecycle-Scoring"> - <title>Scoring</title> - <para> + </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> + <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> + <para> The <literal>jcr:score</literal> is calculated as; <literal>(lucene score)*1000f</literal>. </para> - <!--<para> +<!--<para> Score may be increased for specified nodes, see <xref linkend="sect-Reference_Guide-Changing_Priority_of_Node" /> </para> <para> Also, see an example in sect-Reference_Guide-Ordering_by_Score /> - </para>--> - - </section> - - - </section> - - <section id="sect-Reference_Guide-JCR_Query_Usecases-Tips_and_tricks"> - <title>Tips and tricks</title> - <xi:include href="tip-nodename-with-number.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - </section> - - + </para>--> </section> + </section> + <section id="sect-Reference_Guide-JCR_Query_Usecases-Tips_and_tricks"> + <title>Tips and tricks</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tip-nodename-with-number.xml"/> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/searching-repository-content.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/searching-repository-content.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/searching-repository-content.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -8,7 +8,7 @@ <section id="sect-Reference_Guide-Searching_Repository_Content-Introduction"> <title>Introduction</title> <para> - You can find the JCR configuration file here: <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + You can find the JCR configuration file here: <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.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. Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/statistics.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/statistics.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/statistics.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -1,297 +1,189 @@ -<?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 "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter 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> + <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> + <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> + <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> + <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> + <itemizedlist> + <listitem> + <para> The minimum time spent into the method. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> The maximum time spent into the method. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> The average time spent into the method. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> The total amount of time spent into the method. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> The total amount of time the method has been called. </para> - - </listitem> - - </itemizedlist> - <para> - Those figures are also available globaly for all the methods which gives us the global behavior of this layer. + </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> + 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> + <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> + <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> + <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> + <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> + <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/ex...;. + <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/ex...;. </para> - - </listitem> - <listitem> - <para> - aspectjrt-1.6.8.jar that you can get from the main maven repository <ulink url="http://repo2.maven.org/maven2/org/aspectj/aspectjrt">&l...;. + </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> + </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"&g...;. </para> - <para> + <para> At this stage, to enable the statistics on the JCR API accesses, you will need to add the JVM parameter <parameter>-javaagent:${pathto}/aspectjweaver-1.6.8.jar</parameter> to your command line, for more details please refer to <ulink url="http://www.eclipse.org/aspectj/doc/released/devguide/ltw-config...;. </para> - <para> + <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> + <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> + <para> The file content below is the content of <filename>conf/configuration.xml</filename> that you will need to modify to add and/or remove the full qualified name of the interfaces to monitor, into the list of parameter values of the init param called <literal>targetInterfaces</literal>. </para> - -<programlisting language="XML" role="XML">&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"&gt; + <programlisting language="XML" role="XML">&lt;configuration xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; xsi:schemaLocation=&quot;http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd&quot; + xmlns=&quot;http://www.exoplaform.org/xml/ns/kernel_1_2.xsd&quot;... &lt;component&gt; &lt;type&gt;org.exoplatform.services.jcr.statistics.JCRAPIAspectConfig&lt;/type&gt; @@ -305,197 +197,123 @@ &lt;/init-params&gt; &lt;/component&gt; &lt;/configuration&gt;</programlisting> - <para> + <para> The file content below is the content of <filename>META-INF/aop.xml</filename> that you will to need to modify to add and/or remove the full qualified name of the interfaces to monitor, into the expression filter of the pointcut called <literal>JCRAPIPointcut</literal>. </para> - <para> + <para> By default only JCR API calls from the <literal>exoplatform</literal> packages are taken into account. This filter can be modified to add other package names. </para> - -<programlisting language="XML" role="XML">&lt;aspectj&gt; + <programlisting language="XML" role="XML">&lt;aspectj&gt; &lt;aspects&gt; - &lt;concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect"&gt; - &lt;pointcut name="JCRAPIPointcut" - expression="(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) &amp;&amp; call(public * *(..))" /&gt; + &lt;concrete-aspect name=&quot;org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl&quot; extends=&quot;org.exoplatform.services.jcr.statistics.JCRAPIAspect&quot;&gt; + &lt;pointcut name=&quot;JCRAPIPointcut&quot; + expression=&quot;(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) &amp;&amp; call(public * *(..))&quot; /&gt; &lt;/concrete-aspect&gt; &lt;/aspects&gt; - &lt;weaver options="-XnoInline"&gt; - &lt;include within="org.exoplatform..*" /&gt; + &lt;weaver options=&quot;-XnoInline&quot;&gt; + &lt;include within=&quot;org.exoplatform..*&quot; /&gt; &lt;/weaver&gt; &lt;/aspectj&gt;</programlisting> - <para> + <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> + <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> + <para> The metric alias are described in the statistics manager section. </para> - <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> + <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> + </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> + <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> + <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> + <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> + <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> + <para> You can also access to the statistics via JMX. The available methods are: </para> - <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> + <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> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gtn/managed-datasources-under-jboss-as.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gtn/managed-datasources-under-jboss-as.xml 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gtn/managed-datasources-under-jboss-as.xml 2012-07-11 06:00:45 UTC (rev 8781) @@ -59,7 +59,7 @@ <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. Edit the <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/conf/gatein/configuration.properties</filename> and comment out the following rows in the JCR section: + Do not let the portal explicitly bind datasources. Edit the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/conf/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} Modified: epp/docs/branches/5.2/Reference_Guide/publican.cfg =================================================================== --- epp/docs/branches/5.2/Reference_Guide/publican.cfg 2012-07-10 12:17:37 UTC (rev 8780) +++ epp/docs/branches/5.2/Reference_Guide/publican.cfg 2012-07-11 06:00:45 UTC (rev 8781) @@ -4,4 +4,6 @@ type: Book git_branch: docs-rhel-6 show_remarks: 1 +# web formats turns of PDF generation, because FOP is causing builds to die. Stupid FOP. Enable when Publican 3 is released +web_formats: "epub,html,html-single"