[gatein-commits] gatein SVN: r5437 - in epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US: extras/Authentication_Identity_PredefinedUserConfiguration and 10 other directories.

Author: smumford Date: 2010-12-02 01:17:20 -0500 (Thu, 02 Dec 2010) New Revision: 5437 Added: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/Authentication_Identity_PredefinedUserConfiguration/default101.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_DefaultPortalPermissionConfiguration/default145.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_DefaultPortalPermissionConfiguration/default146.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_InternationalizationConfiguration/default148.java epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortletDevelopment_Standard/JSPHelloUserPortlet.java epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/Foundations.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/intro.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/lock-manager-config.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/BackendConfiguration.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/GadgetDevelopment/SetupGadgetServer.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/WSRP.xml Log: : Incorporated editoral feedback from 5.0.1 reviews for re-publish Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/Revision_History.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/Revision_History.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -7,7 +7,21 @@ <title>Revision History</title> <simpara> <revhistory> - <revision> + <revision> + <revnumber>1-1.2</revnumber> + <date>Thu Dec 02 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Incorporated editorial feedback from QA reviews.</member> + </simplelist> + </revdescription> + </revision> +<!-- <revision> <revnumber>1.11</revnumber> <date>Thu Sep 30 2010</date> <author> @@ -48,8 +62,8 @@ <member>Started content for &#34;Debugging Resource Bundle Usage&#34; section. Started homoginizing filepath variables.</member> </simplelist> </revdescription> - </revision> - <revision> + </revision>--> + <revision> <revnumber>1.8</revnumber> <date>Fri Aug 27 2010</date> <author> @@ -64,7 +78,7 @@ </revdescription> </revision> <revision> - <revnumber>1.7</revnumber> +<!-- <revnumber>1.7</revnumber> <date>Mon Aug 9 2010</date> <author> <firstname>Scott</firstname> @@ -90,7 +104,7 @@ <member>Extracted code snippets.</member> </simplelist> </revdescription> - </revision> + </revision> --> <revision> <revnumber>1.5</revnumber> <date>Thu Jul 29 2010</date> @@ -105,7 +119,7 @@ </simplelist> </revdescription> </revision> - <revision> +<!-- <revision> <revnumber>1.1</revnumber> <date>Sat Mar 20 2010</date> <author> @@ -132,7 +146,7 @@ <member>First complete edit</member> </simplelist> </revdescription> - </revision> + </revision> --> <revision> <revnumber>0</revnumber> <date>Wed Nov 11 2009</date> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/Authentication_Identity_PredefinedUserConfiguration/default101.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/Authentication_Identity_PredefinedUserConfiguration/default101.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/Authentication_Identity_PredefinedUserConfiguration/default101.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -1,32 +1,32 @@ <component-plugin> -<name>new.user.event.listener</name> -<set-method>addListenerPlugin</set-method> -<type>org.exoplatform.services.organization.impl.NewUserEventListener</type> -<description>this listener assign group and membership to a new created user</description> -<init-params> -<object-param> -<name>configuration</name> -<description>description</description> -<object type="org.exoplatform.services.organization.impl.NewUserConfig"> -<field name="group"> -<collection type="java.util.ArrayList"> -<value> -<object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup"> -<field name="groupId"><string>/user</string></field> -<field name="membership"><string>member</string></field> -</object> -</value> -</collection> -</field> -<field name="ignoredUser"> -<collection type="java.util.HashSet"> -<value><string>exo</string></value> -<value><string>root</string></value> -<value><string>company</string></value> -<value><string>community</string></value> -</collection> -</field> -</object> -</object-param> -</init-params> + <name>new.user.event.listener</name> + <set-method>addListenerPlugin</set-method> + <type>org.exoplatform.services.organization.impl.NewUserEventListener</type> + <description>this listener assign group and membership to a new created user</description> + <init-params> + <object-param> + <name>configuration</name> + <description>description</description> + <object type="org.exoplatform.services.organization.impl.NewUserConfig"> + <field name="group"> + <collection type="java.util.ArrayList"> + <value> + <object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup"> + <field name="groupId"><string>/platform/users</string></field> + <field name="membership"><string>member</string></field> + </object> + </value> + </collection> + </field> + <field name="ignoredUser"> + <collection type="java.util.HashSet"> + <value><string>exo</string></value> + <value><string>root</string></value> + <value><string>company</string></value> + <value><string>community</string></value> + </collection> + </field> + </object> + </object-param> + </init-params> </component-plugin> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_DefaultPortalPermissionConfiguration/default145.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_DefaultPortalPermissionConfiguration/default145.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_DefaultPortalPermissionConfiguration/default145.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -1,31 +1,40 @@ <component> -<key>org.exoplatform.portal.config.UserACL</key> -<type>org.exoplatform.portal.config.UserACL</type> -<init-params> -<value-param> -<name>super.user</name> -<description>administrator</description> -<value>root</value> -</value-param> -<value-param> -<name>portal.creator.groups</name> -<description>groups with membership type have permission to manage portal</description> -<value>*:/platform/administrators,*:/organization/management/executive-board</value> -</value-param> -<value-param> -<name>navigation.creator.membership.type</name> -<description>specific membership type have full permission with group navigation</description> -<value>manager</value> -</value-param> -<value-param> -<name>guests.group</name> -<description>guests group</description> -<value>/platform/guests</value> -</value-param> -<value-param> -<name>access.control.workspace</name> -<description>groups with memberships that have the right to access the User Control Workspace</description> -<value>*:/platform/administrators,*:/organization/management/executive-board</value> -</value-param> -</init-params> + <key>org.exoplatform.portal.config.UserACL</key> + <type>org.exoplatform.portal.config.UserACL</type> + <init-params> + <value-param> + <name>super.user</name> + <description>administrator</description> + <value>root</value> + </value-param> + + <value-param> + <name>portal.creator.groups</name> + <description>groups with membership type have permission to manage portal</description> + <value>*:/platform/administrators,*:/organization/management/executive-board</value> + </value-param> + + <value-param> + <name>navigation.creator.membership.type</name> + <description>specific membership type have full permission with group navigation</description> + <value>manager</value> + </value-param> + <value-param> + <name>guests.group</name> + <description>guests group</description> + <value>/platform/guests</value> + </value-param> + <values-param> + <name>mandatory.groups</name> + <description>Groups that can not be deleted.</description> + <value>/platform/administrators</value> + <value>/platform/users</value> + <value>/platform/guests</value> + </values-param> + <values-param> + <name>mandatory.mstypes</name> + <description>Membership type that can not be deleted.</description> + <value>member</value> + </values-param> + </init-params> </component> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_DefaultPortalPermissionConfiguration/default146.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_DefaultPortalPermissionConfiguration/default146.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_DefaultPortalPermissionConfiguration/default146.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -1,21 +1,20 @@ <external-component-plugins> -<target-component>org.exoplatform.portal.config.UserACL</target-component> -<component-plugin> -<name>addPortalACLPlugin</name> -<set-method>addPortalACLPlugin</set-method> -<type>org.exoplatform.portal.config.PortalACLPlugin</type> -<description>setting some permission for portal</description> -<init-params> -<values-param> -<name>access.control.workspace.roles</name> -<value>*:/platform/administrators</value> -<value>*:/organization/management/executive-board</value> -</values-param> -<values-param> -<name>portal.creation.roles</name> -<value>*:/platform/administrators</value> -<value>*:/organization/management/executive-board</value> -</values-param> -</init-params> -</component-plugin> -</external-component-plugins> + <target-component>org.exoplatform.portal.config.UserACL</target-component> + <component-plugin> + <name>addPortalACLPlugin</name> + <set-method>addPortalACLPlugin</set-method> + <type>org.exoplatform.portal.config.PortalACLPlugin</type> + <description>setting some permission for portal</description> + <init-params> + <values-param> + <name>super.user</name> + <value>root</value> + </values-param> + <values-param> + <name>portal.creation.roles</name> + <value>*:/platform/administrators</value> + <value>*:/organization/management/executive-board</value> + </values-param> + </init-params> + </component-plugin> +</external-component-plugins> \ No newline at end of file Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_InternationalizationConfiguration/default148.java =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_InternationalizationConfiguration/default148.java 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortalDevelopment_InternationalizationConfiguration/default148.java 2010-12-02 06:17:20 UTC (rev 5437) @@ -1 +1 @@ -javax.portlet.title=Portlet Navigation +javax.portlet.title=Portlet de navegaci\u00f3n \ No newline at end of file Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortletDevelopment_Standard/JSPHelloUserPortlet.java =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortletDevelopment_Standard/JSPHelloUserPortlet.java 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/extras/PortletDevelopment_Standard/JSPHelloUserPortlet.java 2010-12-02 06:17:20 UTC (rev 5437) @@ -1,4 +1,4 @@ -package org.jboss.portal.portlet.portlets; +package org.jboss.portal.portlet.samples; import java.io.IOException; Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/Foundations.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/Foundations.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/Foundations.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -5,8 +5,8 @@ ]> <chapter id="chap-Reference_Guide-Foundations"> <title>Foundations</title> - <section id="sect-Reference_Guide-Foundations-The_Exo_Kernel"> - <title>The Exo Kernel</title> + <section id="sect-Reference_Guide-Foundations-The_eXo_Kernel"> + <title>The eXo Kernel</title> <para> &PRODUCT; is built as a set of services on top of a dependency injection kernel. The kernel provides configuration, lifecycle handling, component scopes, and some core services. </para> @@ -33,12 +33,11 @@ &PRODUCT; can have default instances of a certain component in the <literal>RootContainer</literal>, and portal specific instances in some or all <literal>PortalContainers</literal>, that override the default instance. </para> <para> - Whenever your portal application has to be integrated more closely with Exo services, these services can be looked up through the <literal>PortalContainer</literal>. + Whenever your portal application has to be integrated more closely with eXo services, these services can be looked up through the <literal>PortalContainer</literal>. </para> - <!-- This Note has been flagged in a review by Andrew Ross BNE QE. Currently unsure as to why. --> <important> <para> - Only officially documented services should be accessed this way, and used according to documentation, as most of the services are an implementation detail of Exo, and subject to change without notice. + Only officially documented services should be accessed this way, and used according to documentation, as most of the services are an implementation detail of eXo, and subject to change without notice. </para> </important> </section> @@ -47,13 +46,13 @@ <section id="sect-Reference_Guide-Foundations-Configuring_services"> <title>Configuring services</title> <para> - Exo Kernel uses dependency injection to create services based on <filename>configuration.xml</filename> configuration files. The location of the configuration files determines if services are placed into the <literal>RootContainer</literal> scope, or into the <literal>PortalContainer</literal> scope. + The eXo Kernel uses dependency injection to create services based on <filename>configuration.xml</filename> configuration files. The location of the configuration files determines if services are placed into the <literal>RootContainer</literal> scope, or into the <literal>PortalContainer</literal> scope. </para> <para> All <filename>configuration.xml</filename> files located at <filename>conf/configuration.xml</filename> in the classpath (any directory, or any jar in the classpath) will have their services configured in the <literal>RootContainer</literal> scope. 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 contain configuration in <filename>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 contain configuration in <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</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> <note> <para> @@ -87,7 +86,7 @@ <section id="sect-Reference_Guide-Configuration_syntax-External_Plugins"> <title>External Plugins</title> <para> - The Exo Kernel supports non-component objects that can be configured, instantiated, and injected into registered components using method calls. This &#39;<emphasis>plugin</emphasis>&#39; method allows portal extensions to add additional configurations to core services. + The eXo Kernel supports non-component objects that can be configured, instantiated, and injected into registered components using method calls. This &#39;<emphasis>plugin</emphasis>&#39; method allows portal extensions to add additional configurations to core services. </para> <para> An external plugin is defined by using the <literal>&#60;external-component-plugin&#62;</literal> wrapper element which contains one or more <literal>&#60;component-plugin&#62;</literal> definitions. @@ -96,10 +95,10 @@ The <literal>&#60;external-component-plugin&#62;</literal> element uses <literal>&#60;target-component&#62;</literal> to specify a target service component that will receive injected objects. </para> <para> - Every <literal>&#60;component-plugin&#62;</literal> defines an implementation type, and a method on target component to use for injection (<literal>&#60;set-method&#62;</literal>). + Every <literal>&#60;component-plugin&#62;</literal> defines an implementation type, and a method on the target component to use for injection (<literal>&#60;set-method&#62;</literal>). </para> <para> - A plugin implementation class has to implement the <emphasis role="bold">org.exoplatform.container.component. ComponentPlugin</emphasis> interface. + A plugin implementation class has to implement the <emphasis role="bold">org.eXoplatform.container.component. ComponentPlugin</emphasis> interface. </para> <para> In the following example the <literal>PortalContainerDefinitionPlugin</literal> implements the <literal>ComponentPlugin</literal>: @@ -182,7 +181,7 @@ If the service component&#39;s constructor takes <parameter>InitParams</parameter> 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>&#60;init-params&#62;</parameter> element present, however this element can be left empt + The XML configuration for a service component that expects an <parameter>InitParams</parameter> element must have an <parameter>&#60;init-params&#62;</parameter> 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: @@ -226,7 +225,7 @@ Each of these child elements takes a <parameter>&#60;name&#62;</parameter> that serves as a map entry key, and an optional <parameter>&#60;description&#62;</parameter>. It also takes a type-specific <emphasis role="bold">value</emphasis> specification. </para> <para> - The value specification for the <parameter>&#60;properties-param&#62;</parameter> defines one or more <parameter>&#60;property&#62;</parameter> element, 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 <parameter>&#60;properties-param&#62;</parameter> defines one or more <parameter>&#60;property&#62;</parameter> 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>&#60;properties-params&#62;</parameter> defines one <literal>java.util.Properties</literal> instance. @@ -237,12 +236,12 @@ <programlisting language="XML" role="XML"><xi:include href="../../extras/Advanced_Development_Foundations/default5.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - The value specification for <parameter>&#60;values-param&#62;</parameter> requires one or more <parameter>&#60;value&#62;</parameter> element. Each <parameter>&#60;value&#62;</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 <parameter>&#60;values-param&#62;</parameter> requires one or more <parameter>&#60;value&#62;</parameter> elements. Each <parameter>&#60;value&#62;</parameter> 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 href="../../extras/Advanced_Development_Foundations/default6.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - For <parameter>&#60;object-param&#62;</parameter> entries, the value specification consists of an <parameter>&#60;object&#62;</parameter> element which is used for plain java style object specification (specifying an implementation <emphasis>class - <parameter>&#60;type&#62;</parameter></emphasis>, and <emphasis>property values - <parameter>&#60;field&#62;</parameter></emphasis>). + For <parameter>&#60;object-param&#62;</parameter> entries, the value specification consists of an <parameter>&#60;object&#62;</parameter> element which is used for plain Java style object specification (specifying an implementation <emphasis>class - <parameter>&#60;type&#62;</parameter></emphasis>, and <emphasis>property values - <parameter>&#60;field&#62;</parameter></emphasis>). </para> <para> The following section has an example of specifying a field of with a <literal>Collection</literal> type. @@ -302,7 +301,7 @@ </para> <variablelist> <varlistentry> - <term>ExoContainerContext</term> + <term>eXoContainerContext</term> <listitem> <para> This contains information about the portal. @@ -334,12 +333,11 @@ </varlistentry> </variablelist> <para> - The <emphasis role="bold">Unified servlet context</emphasis>, and <emphasis role="bold">unified classloader</emphasis> are part of the <emphasis role="bold">extension mechanism</emphasis> (which is detailed in the next section). + The <emphasis role="bold">Unified servlet context</emphasis> and <emphasis role="bold">unified classloader</emphasis> are part of the <emphasis role="bold">extension mechanism</emphasis> (which is detailed in the next section). </para> <para> - They provide the standard API (<literal>ServletContext</literal>, <literal>ClassLoader</literal>) with specific resource loading behavior, such as visibility into associated web application archives, configured with dependencies property of <literal>PortalContainerDefinition</literal>. + They provide the standard API (<literal>ServletContext</literal>, <literal>ClassLoader</literal>) with specific resource loading behavior, such as visibility into associated web application archives, configured with the dependencies property of <literal>PortalContainerDefinition</literal>. </para> - <!-- DOC TODO: Confirm if 'visibility into' is the approapriate phrase to use here --> <para> Resources from other web applications are queried in the order specified by the dependencies. The later entries in the list override the previous ones. </para> @@ -352,7 +350,7 @@ The <emphasis role="bold">Extension mechanism</emphasis> makes it possible to override portal resources in a way similar to hardware plug-and-play functionalities. </para> <para> - Customizations can be implemented without unpacking and repacking the original portal <code>.war</code> archives, by adding a <code>.war</code> archive to the resources and configuring its position in the portal&#39;s classpath. Custom <code>.war</code> archives can be created with new resources that override the resources in the original archive. + Customizations can be implemented without unpacking and repacking the original portal <code>.war</code> archives by adding a <code>.war</code> archive to the resources and configuring its position in the portal&#39;s classpath. Custom <code>.war</code> archives can be created with new resources that override the resources in the original archive. </para> <para> These archives, packaged for use through the extension mechanism, are called <emphasis role="bold">portal extensions</emphasis>. @@ -392,7 +390,6 @@ </note> </section> - <section id="sect-Reference_Guide-Foundations-Running_Multiple_Portals"> <title>Running Multiple Portals</title> <!-- DOC TODO: This section requires more work to structure the information effectively. Consider sub-sections --> @@ -409,22 +406,22 @@ In order for a portal application to function correctly when deployed within a multiple portal deployment, it may have to dynamically query the information about the current portal container. The application should not make any assumptions about the name, and other information of the current portal, as there are now multiple different portals in play. </para> <para> - At any point during request processing, or life-cycle event processing, an application can retrieve this information through <literal>org.exoplatform.container. ExoContainerContext</literal>. + At any point during request processing, or life-cycle event processing, an application can retrieve this information through <literal>org.exoplatform.container.eXoContainerContext</literal>. </para> <para> - Sometimes an application must ensure that the proper <literal>PortalContainer</literal> is associated with the current <literal>ExoContainerContext</literal> call. + Sometimes an application must ensure that the proper <literal>PortalContainer</literal> is associated with the current <literal>eXoContainerContext</literal> call. </para> <para> If the portal application contains servlets or servlet filters that need to access portal specific resources during their request processing, the servlet or filter must be associated with the current container. </para> <para> - A servlet in this instance should extend the <literal>org.exoplatform.container.web. AbstractHttpServlet</literal> class so as to properly initialize the current <literal>PortalContainer</literal>. + A servlet in this instance should extend the <literal>org.exoplatform.container.web.AbstractHttpServlet</literal> class so as to properly initialize the current <literal>PortalContainer</literal>. </para> <para> This will also set the current thread&#39;s context classloader to one that looks for resources in associated web applications in the order specified by the <emphasis role="bold">dependencies</emphasis> configuration (as seen in <xref linkend="sect-Reference_Guide-Foundations-The_Extension_Mechanism_and_Portal_Extensions" />). </para> <para> - Filter classes need to extend the <literal>org.exoplatform.container.web. AbstractFilter</literal>. + Filter classes need to extend the <literal>org.exoplatform.container.web.AbstractFilter</literal>. </para> <para> Both <literal>AbstractHttpServlet</literal>, and <literal>AbstractFilter</literal> have a <literal>getContainer()</literal> method, which returns the current <literal>PortalContainer</literal>. @@ -440,7 +437,7 @@ </para> </note> <para> - An application may also need to access to portal information within the <emphasis role="bold">HttpSessionListener</emphasis>. Ensure the provided abstract class; <emphasis role="bold">org.exoplatform.container.web. AbstractHttpSessionListener</emphasis> is extended. + An application may also need access to portal information within the <emphasis role="bold">HttpSessionListener</emphasis>. Ensure the abstract class <emphasis role="bold">org.exoplatform.container.web.AbstractHttpSessionListener</emphasis> is extended. </para> <para> In this instance, modify the method signatures as follows: @@ -496,7 +493,7 @@ <formalpara id="form-Reference_Guide-Running_Multiple_Portals-LoginModules"> <title>LoginModules</title> <para> - If some custom <literal>LoginModules</literal> require the current <literal>ExoContainer</literal> for initialization ensure they extend <emphasis role="bold">org.exoplatform.services.security.jaas.AbstractLoginModule</emphasis>. + If some custom <literal>LoginModules</literal> require the current <literal>eXoContainer</literal> for initialization ensure they extend <emphasis role="bold">org.exoplatform.services.security.jaas.AbstractLoginModule</emphasis>. </para> </formalpara> <para> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -3,6 +3,7 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "../../../Reference_Guide.ent"> %BOOK_ENTITIES; ]> + <section id="sect-Reference_Guide-JCR_configuration"> <title>JCR configuration</title> <para> @@ -12,269 +13,171 @@ <programlisting language="Java" role="Java"><xi:include parse="text" href="../../../extras/Advanced_Development_JCR_Configuration/NMTOKEN.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - To configure the JCR Service; + To modify the configuration of the JCR Service, you would need to modify the file found at <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> - <procedure> - <step> - <para> - Familiarize yourself with the DTD file above and the either the example configuration file below or the one in your &PRODUCT; deployment (found at; <filename>/<replaceable>JBOSS_AS</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>). - </para> - </step> - <step> - <para> - Replace the element values marked below with those of your deployment environment. - </para> - </step> - <step> - <para> - The repository configuration supports human-readable values. They are not case-sensitive. - </para> - <para> - Complete the appropriate element fields using the following value formats: - </para> - <variablelist> - <varlistentry> - <term>Number formats:</term> - <listitem> - <para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">K</emphasis> or <emphasis role="bold">KB</emphasis> for kiloBytes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">M</emphasis> or <emphasis role="bold">MB</emphasis> for megaBytes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">G</emphasis> or <emphasis role="bold">GB</emphasis> for gigaBytes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">T</emphasis> or <emphasis role="bold">TB</emphasis> for terraBytes. - </para> - </listitem> - <listitem> - <para> - Examples: 200k or 200 KBytes; 4m or 4 MBytes; 1.4G or 1.4 GBytes; 10T or 10 TBytes - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Time formats:</term> - <listitem> - <para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">ms</emphasis> for milliseconds. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">s</emphasis> for seconds. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">m</emphasis> for minutes. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">h</emphasis> for hours. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">d</emphasis> for days. - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">w</emphasis> for weeks. - </para> - </listitem> - <listitem> - <para> - The default time format is seconds if no other format is specified. - </para> - </listitem> - <listitem> - <para> - Examples: 500ms or 500 milliseconds; 20, 20s or 20 seconds; 30m or 30 minutes; 12h or 12 hours; 5d or 5 days; 4w or 4 weeks. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - </variablelist> - </step> - </procedure> + +<programlisting><![CDATA[ +<repository-service default-repository="repository"> + <repositories> + <repository name="repository" system-workspace="system" default-workspace="portal-system"> + <security-domain>gatein-domain</security-domain> + <access-control>optional</access-control> + <authentication-policy>org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator</authentication-policy> + + <!-- System --> + <workspaces> + [... Workspaces definitions ...] + </workspaces> + </repository> + </repositories> +</repository-service>]]> +</programlisting> + <para> + In JBoss Enterprise Portal Platform you will see several configured workspaces required for the portal. + </para> + <orderedlist numeration="arabic"> + <listitem> + <para> + <literal>system</literal> + </para> + </listitem> + <listitem> + <para> + <literal>portal-system</literal>: To store portal metadata such as page compositions. + </para> + </listitem> + <listitem> + <para> + <literal>portal-work</literal>: To store elements that are temporary such as tokens + </para> + </listitem> + <listitem> + <para> + <literal>wsrp-system</literal>: To store WSRP related data + </para> + </listitem> + <listitem> + <para> + <literal>wsrp-system</literal>: To store Portlet Container related data (such as portlet preferences + </para> + </listitem> + </orderedlist> + <para> + Configure the workspaces by locating the workspace you need to modify in <filename><filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename></filename>. + </para> + <para> + The repository configuration supports human-readable values. They are not case-sensitive. + </para> + <para> + Complete the appropriate element fields using the following value formats: + </para> + <variablelist> + <varlistentry> + <term>Number formats:</term> + <listitem> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">K</emphasis> or <emphasis role="bold">KB</emphasis> for kiloBytes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">M</emphasis> or <emphasis role="bold">MB</emphasis> for megaBytes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">G</emphasis> or <emphasis role="bold">GB</emphasis> for gigaBytes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">T</emphasis> or <emphasis role="bold">TB</emphasis> for terraBytes. + </para> + </listitem> + <listitem> + <para> + Examples: 200K or 200KB; 4M or 4MB; 1.4G or 1.4GB; 10T or 10TB. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Time formats:</term> + <listitem> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">ms</emphasis> for milliseconds. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">s</emphasis> for seconds. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">m</emphasis> for minutes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">h</emphasis> for hours. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">d</emphasis> for days. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">w</emphasis> for weeks. + </para> + </listitem> + <listitem> + <para> + The default time format is seconds if no other format is specified. + </para> + </listitem> + <listitem> + <para> + Examples: 500ms or 500 milliseconds; 20, 20s or 20 seconds; 30m or 30 minutes; 12h or 12 hours; 5d or 5 days; 4w or 4 weeks. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + <section id="sect-Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration"> - <title>Repository Service Configuration</title> + <title>Example of the portal-system workspace</title> <programlistingco> <areaspec> - <!--1--> - <area coords="1 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-default-repository"/> + <!--1--> + <area coords="2 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-workspace-name"/> <!--2--> - <area coords="2 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-repositories"/> + <area coords="3 90" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-container"/> <!--3--> - <area coords="3 80" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-name"/> + <area coords="23 90" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_initializer"/> <!--4--> - <area coords="3 85" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-system-workspace"/> + <area coords="29 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_cache"/> <!--5--> - <area coords="3 90" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-default-workspace"/> + <area coords="37 100" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_query-handler"/> <!--6--> - <area coords="4 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-security-domain"/> - <!--7--> - <area coords="5 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-access-control"/> - <!--8--> - <area coords="6 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-session-max-age"/> - <!--9--> - <area coords="7 100" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-authentication-policy"/> - <!--10--> - <area coords="8 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-workspaces"/> - <!--11--> - <area coords="9 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-workspace-name"/> - <!--12--> - <area coords="11 90" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-container"/> - <!--13--> - <area coords="30 90" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_initializer"/> - <!--14--> - <area coords="35 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_cache"/> - <!--15--> - <area coords="41 100" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_query-handler"/> - <!--16--> - <area coords="47 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_lock-manager-timeout"/> - <!--17--> - <area coords="48 100" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_lock-manager-persister"/> - <!--18--> - <area coords="50 90" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_lock-manager-path"/> - <!--19--> - <area coords="57 110" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-class"/> - <!--20--> - <area coords="58 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-properties"/> - <!--21--> - <area coords="65 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-value-storages"/> - <!--22--> - <area coords="66 90" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-value-storage"/> - <!--23--> - <area coords="66 95" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-value-class"/> - <!--24--> - <area coords="67 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-value-properties"/> - <!--25--> - <area coords="70 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-value-filters"/> - <!--26--> - <area coords="76 90" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_initializer_implementation_class"/> - <!--27--> - <area coords="77 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_initializer_implementation_properties"/> - <!--28--> - <area coords="81 90" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_cache_enabled"/> - <!--29--> - <area coords="81 95" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_cache_class"/> - <!--30--> - <area coords="82 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_cache_properties"/> - <!--31--> - <area coords="87 100" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_query-handler-class"/> - <!--32--> - <area coords="88 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_query-handler-properties"/> + <area coords="50 60" id="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_lock-manager-timeout"/> </areaspec> <programlisting language="XML" role="XML"><xi:include parse="text" href="../../../extras/Advanced_Development_JCR_Configuration/orig.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <calloutlist> - <title>Repository Service configuration:</title> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-default-repository"> - <para> - The name of a default repository (one returned by RepositoryService.getRepository()) - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-repositories"> - <para> - The list of repositories is configured within the &lt;repositories&gt; element. - </para> - </callout> - </calloutlist> - <calloutlist> - <title>Repository configuration:</title> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-name"> - <para> - The name of the repository being configured. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-default-workspace"> - <para> - The name of a workspace. This can be obtained using Session's <literal>login()</literal> or <literal>login(Credentials)</literal> methods for workspaces without an explicit name. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-system-workspace"> - <para> - The name of workspace where /jcr:system node is placed. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-security-domain"> - <para> - The name of a security domain for JAAS authentication - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-access-control"> - <para> - The name of an access control policy. There can be three types: - </para> - <variablelist> - <varlistentry> - <term>optional</term> - <listitem> - <para> - AN ACL is created on demand. This is the default policy. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>disable</term> - <listitem> - <para> - Disables access control. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>mandatory</term> - <listitem> - <para> - An ACL is created for each added node. This function is not supported in this release. - </para> - </listitem> - </varlistentry> - </variablelist> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-session-max-age"> - <para> - The amount of time before an idle session will be removed (called logout). If it is not set, the idle session will never be removed. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-authentication-policy"> - <para> - The name of an authentication policy class. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-workspaces"> - <para> - The list of workspaces. - </para> - </callout> - </calloutlist> - <calloutlist> - <title>Workspace configuration:</title> <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration-workspace-name"> <para> The name of the workspace. @@ -300,177 +203,16 @@ Query handler configuration. </para> </callout> - </calloutlist> - <calloutlist> - <title>Lock Manager configuration:</title> <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_lock-manager-timeout"> <para> The amount of time before the unused global lock is removed. </para> </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_lock-manager-persister"> - <para> - A class for storing lock information for future use. For example; remove lock after restarting JCR. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_lock-manager-path"> - <para> - Each workspace has its own lock folder. - </para> - </callout> - </calloutlist> - <calloutlist> - <title>Workspace data container configuration:</title> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-class"> - <para> - A workspace data container class name. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-properties"> - <para> - The list of properties (in name-value pairs) for the concrete Workspace data container. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-value-storages"> - <para> - The list of value storage plugins. - </para> - </callout> - </calloutlist> - <calloutlist> - <title>Value storage plugin configuration (optional feature):</title> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-value-storage"> - <para> - <emphasis role="bold">Optional</emphasis>: Value storage plugin definition. If this element is not included, the values will be stored as BLOBs inside the database. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-value-class"> - <para> - A value storage plugin class name (attribute). - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-value-properties"> - <para> - The list of properties (in name-value pairs) for a concrete value storage plugin. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_workspace-container-value-filters"> - <para> - The list of filters defining conditions when this plugin is applicable. - </para> - </callout> - </calloutlist> - <calloutlist> - <title>Initializer configuration (optional):</title> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_initializer_implementation_class"> - <para> - Initializer implementation class. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_initializer_implementation_properties"> - <para> - The list of properties (in name-value pairs). Properties are supported: - </para> - <variablelist> - <varlistentry> - <term>root-nodetype</term> - <listitem> - <para> - The node type for root node initialization. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>root-permissions</term> - <listitem> - <para> - Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities and the type of permission. - </para> - <para> - For example any read;:/admin read;:/admin add_node;:/admin set_property;:/admin remove means that users from group admin have all permissions and other users have only a 'read' permission. - </para> - <para> - Configurable initializer adds a capability to override workspace initial startup procedure. - </para> - </listitem> - </varlistentry> - </variablelist> - </callout> - </calloutlist> - <calloutlist> - <title>Cache configuration:</title> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_cache_enabled"> - <para> - Defines if the workspace cache is enabled. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_cache_class"> - <para> - Cache implementation class. This is optional from JCR version 1.9. - </para> - <para> - The default value is <literal>org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl</literal>. - </para> - <para> - The cache can be configured to use concrete implementations of the <literal>WorkspaceStorageCache</literal> interface. - </para> - <para> - The JCR core has two implementations to use: - </para> - <para> - <emphasis role="bold">LinkedWorkspaceStorageCacheImpl</emphasis> - </para> - <para> - The default implementation, with configurable read behavior and statistics. - </para> - <para> - <emphasis role="bold">WorkspaceStorageCacheImpl</emphasis> - </para> - <para> - This implementation is a legacy from pre 1.9 versions of the JCR. However, it can still be used. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_cache_properties"> - <para> - The list of properties (in name-value pairs) for the workspace cache: - </para> - <variablelist> - <varlistentry> - <term>max-size</term> - <listitem> - <para> - The maximum size of the cache. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>live-time</term> - <listitem> - <para> - Cached item live time. - </para> - </listitem> - </varlistentry> - </variablelist> - </callout> - </calloutlist> - <calloutlist> - <title>Query Handler configuration:</title> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_query-handler-class"> - <para> - A Query Handler class name. - </para> - </callout> - <callout arearefs="Reference_Guide-Portal_and_Standalone_configuration-Repository_service_query-handler-properties"> - <para> - The list of properties (name-value pairs) for a Query Handler (<literal>indexDir</literal>) properties and advanced features described in <xref linkend="sect-Reference_Guide-Search_Configuration"/>. - </para> - </callout> </calloutlist> </programlistingco> </section> - +<!-- <section id="sect-Reference_Guide-JCR_configuration-Related_documents"> <title>Related Sections</title> <itemizedlist> @@ -491,5 +233,5 @@ </listitem> </itemizedlist> </section> - +--> </section> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -3,6 +3,7 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> + <section id="sect-Reference_Guide-External_Value_Storages"> <title>External Value Storages</title> <section id="sect-Reference_Guide-External_Value_Storages-Introduction"> @@ -26,7 +27,7 @@ <section id="sect-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage"> <title>Tree File Value Storage</title> <para> - Tree File Value Storage holds values in tree-like FileSystem files. <property>Path</property> property points to the root directory to store the files. + Tree File Value Storage holds values in tree-like file system files. <property>Path</property> property points to the root directory to store the files. </para> <para> This is a recommended type of external storage because it can contain large amount of files limited only by disk/volume free space. @@ -41,14 +42,7 @@ </areaspec> <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_external-value-storages/default25.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="XML" role="XML"><![CDATA[<value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> -<properties> -<property name="path" value="data/values"/> -</properties> -<filters> -<filter property-type="Binary" min-value-size="1M"/> -</filters> -]]></programlisting> --> + <calloutlist> <callout arearefs="area-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-id"> <para> @@ -83,27 +77,9 @@ </para> <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_external-value-storages/default26.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="XML" role="XML"><![CDATA[<value-storages> -<value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> -<properties> -<property name="path" value="data/20Mvalues"/> -</properties> -<filters> -<filter property-type="Binary" min-value-size="20M"/> -</filters> -<value-storage> -<value-storage id="Storage #2" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"> -<properties> -<property name="path" value="data/values"/> -</properties> -<filters> -<filter property-type="Binary" min-value-size="1M"/> -</filters> -<value-storage> -<value-storages>]]></programlisting> --> + </section> - <!-- <section id="sect-Reference_Guide-External_Value_Storages-Simple_File_Value_Storage"> <title>Simple File Value Storage</title> <note> @@ -115,7 +91,7 @@ </para> </note> <para> -Holds Values in flat FileSystem files. <property>path</property> property points to root directory in order to store files +Holds Values in flat file system files. <property>path</property> property points to root directory in order to store files </para> <programlisting language="Java" role="Java"><xi:include parse="text" href="../../../extras/Advanced_Development_JCR_external-value-storages/default27.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <programlisting>&lt;value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.SimpleFileValueStorage"&gt; @@ -170,32 +146,7 @@ </para> <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_external-value-storages/default28.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="XML" role="XML"><![CDATA[<workspaces> -<workspace name="ws"> -<container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"> -<properties> -<property name="source-name" value="jdbcjcr"/> -<property name="dialect" value="oracle"/> -<property name="multi-db" value="false"/> -<property name="update-storage" value="false"/> -<property name="max-buffer-size" value="200k"/> -<property name="swap-directory" value="target/temp/swap/ws"/> -</properties> -<value-storages> -<!- here -> -<value-storage id="ws" class="org.exoplatform.services.jcr.impl.storage.value.fs.CASableTreeFileValueStorage"> -<properties> -<property name="path" value="target/temp/values/ws"/> -<property name="digest-algo" value="MD5"/> -<property name="vcas-type" value="org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImpl"/> -<property name="jdbc-source-name" value="jdbcjcr"/> -<property name="jdbc-dialect" value="oracle"/> -</properties> -<filters> -<filter property-type="Binary"/> -</filters> -</value-storage> -</value-storages>]]></programlisting> --> + <variablelist id="vari-Reference_Guide-Content_Addressable_Value_storage_CAS_support-CAS_Properties"> <title>CAS Properties</title> <varlistentry> @@ -210,8 +161,11 @@ <term>vcas-type</term> <listitem> <para> - Value CAS internal data type, JDBC backed is currently implemented <literal>org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImpl</literal>. + Value CAS internal data type, JDBC backed is currently implemented: </para> + <para> + <literal>org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImpl</literal> + </para> </listitem> </varlistentry> <varlistentry> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/intro.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/intro.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/intro.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -5,11 +5,20 @@ ]> <section id="sect-Reference_Guide-Introduction"> <title>Introduction</title> + <warning> + <title>eXo JCR usage</title> + <para> + The JBoss Enterprise Portal Platform is using a JCR API to store its information for internal usage. We do not support usage of the JCR to store application information. + </para> + <para> + The information below is intended to assist users to understand particular low level details on how the JBoss Enterprise Portal Platform works and how it can be fine-tuned. + </para> + </warning> <para> The term <emphasis role="bold">JCR</emphasis> refers to the Java Content Repository. The JCR is the data store of JBoss Enterprise Portal Platform. All content is stored and managed via the JCR. </para> <para> - The eXo JCR included with JBoss Enterprise Portal Platform 5.1 is a (<ulink type="http" url="http://www.jcp.org/en/jsr/detail?id=170">JSR-170</ulink>) compliant implementation of the JCR 1.0 specification. The JCR provides versioning, textual search, access control, content event monitoring, and can be used for storing text and binary data. The backend storage of the JCR is configurable and can be a filesystem or a database. + The eXo JCR included with JBoss Enterprise Portal Platform 5.1 is a (<ulink type="http" url="http://www.jcp.org/en/jsr/detail?id=170">JSR-170</ulink>) compliant implementation of the JCR 1.0 specification. The JCR provides versioning, textual search, access control, content event monitoring, and is used to storing text and binary data for the portal internal usage. The backend storage of the JCR is configurable and can be a file system or a database. </para> <section id="sect-Reference_Guide-Introduction-Concepts"> <title>Concepts</title> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -5,6 +5,54 @@ ]> <section id="sect-Reference_Guide-JBoss_Cache_configuration"> <title>JBoss Cache configuration</title> + <note> + <title>DOC REVIEW:</title> + <para> + The paragraphs below have been added based on QE feedback. Please review for technical accuracy. + </para> + </note> + <para> + JCR workspaces and their caches are configured in <filename>server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + </para> + <para> + Parameterized properties will be replaced with actual parameters defined in <filename>jboss-as/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/configuration.properties</filename> file. + </para> + <para> + Refer the examples below for an active illustration of this parameter handling: + </para> +<example> +<title><filename>repository-configuration.xml</filename></title> +<programlisting language="XML" role="XML"><![CDATA[<properties> + <property name="source-name" value="${gatein.jcr.datasource.name}${container.name.suffix}"/> + <property name="dialect" value="${gatein.jcr.datasource.dialect}"/> + <property name="multi-db" value="false"/> + <property name="update-storage" value="true"/> + <property name="max-buffer-size" value="204800"/> + <property name="swap-directory" value="${gatein.jcr.data.dir}/system${container.name.suffix}"/> +</properties>]]> +</programlisting> +</example> + +<example> +<title><filename>configuration.properties</filename></title> +<programlisting><![CDATA[# JCR +gatein.jcr.config.type=local +gatein.jcr.datasource.name=java:gatein-jcr +gatein.jcr.datasource.dialect=auto + +gatein.jcr.data.dir=${gatein.data.dir}/jcr +gatein.jcr.storage.data.dir=${gatein.jcr.data.dir}/values +gatein.jcr.index.data.dir=${gatein.jcr.data.dir}/lucene +gatein.jcr.index.changefilterclass=org.exoplatform.services.jcr.impl.core.query.DefaultChangesFilter +</properties>]]> +</programlisting> +</example> + <para> + The JBoss cache and jgroups configuration files are located inside the <filename>server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/lib/exo.portal.component.common-<replaceable>&lt;VERSION&gt;</replaceable>.jar</filename> file. + </para> + <para> + Within this jar the files are located at <filename>/conf/jcr/jbosscache/${gatein.jcr.config.type}</filename> (<literal>${gatein.jcr.config.type}</literal> is defined in <filename>configuration.properties</filename> and denotes either <filename>cluster</filename> or <filename>local</filename> directories). + </para> <section id="sect-Reference_Guide-JBoss_Cache_configuration-Indexer_Lock_Manager_and_Data_Container"> <title>Indexer, Lock Manager and Data Container</title> <para> @@ -16,7 +64,6 @@ <para> For example: </para> - <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_jbosscache-configuration-templates/default29.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> If there are many workspaces, however, configuring them in such a way can be hard to manage. Therefore the JCR offers a template-based configuration method for JBoss Cache instances. @@ -24,7 +71,8 @@ <para> Administrators can use one template for the lock manager, another for the indexer and a third for the data container and then use them in all the workspaces by defining the map of substitution parameters in the main configuration file. </para> - <para> + +<!-- <para> To do this, define <replaceable>${jbosscache-&#60;parameter name&#62;}</replaceable> inside an xml-template and list the correct value in the JCR configuration file (below the &#34;<parameter>jbosscache-configuration</parameter>&#34; entry) as shown below: </para> <para> @@ -36,8 +84,8 @@ The JCR configuration file: </para> -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_jbosscache-configuration-templates/default31.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_jbosscache-configuration-templates/default31.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>--> + </section> <section id="sect-Reference_Guide-JBoss_Cache_configuration-JGroups_configuration"> @@ -68,8 +116,9 @@ &#60;property name=&#34;jgroups-multiplexer-stack&#34; value=&#34;true&#34; /&#62;</programlisting> </section> - - <section id="sect-Reference_Guide-JBoss_Cache_configuration-Templates"> +<!--DOC NOTE: Commented Templates section out as per feedback from Marek Posolda that users should not need to edit these files. + +<section id="sect-Reference_Guide-JBoss_Cache_configuration-Templates"> <title>Templates</title> <para> The eXo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR components. They are located in the application package in the <filename>/conf/portal/</filename> directory. @@ -202,7 +251,7 @@ </callout> </calloutlist> </programlistingco> - </section> + </section> --> </section> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -87,7 +87,7 @@ The data container uses the JDBC driver to communicate with the actual database software. That is, any JDBC-enabled data storage can be used with eXo JCR implementation. </para> <para> - Currently the data container is tested with the following Rational Database Management Systems (RDBMS): + Currently the data container is tested with the following Relational Database Management Systems (RDBMS): </para> <table id="tabl-Reference_Guide-Introduction-Database_Support_"> <title>Database Support </title> @@ -231,7 +231,7 @@ <para> For example, in <application>mysql</application> it is necessary to add a parameter for the JDBC driver to the JDBC URL protocol. For instance: <code>jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8<... </para> - <para> + <para> While HSQL is not supported in production, there are pre-configured configuration files stored in the <filename>/conf/portal</filename> and <filename>/conf/standalone</filename> folders of the <filename>exo.jcr.component.core-XXX.XXX.jar</filename> jar-file or source-distribution of the eXo JCR implementation. <emphasis role="bold">These files are included primarily for development and/or familiarization purposes.</emphasis> </para> <para> @@ -240,12 +240,77 @@ <para> In &PRODUCT; the JCR is configured in portal web application <filename>portal/WEB-INF/conf/jcr/jcr-configuration.xml</filename> (containing JCR Repository Service and related services) and <filename>repository-configuration.xml</filename> (which contains the repositories configuration). </para> + + </section> + + <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Single_database_configuration"> + <title>Single-database configuration</title> <para> - Refer to <xref linkend="sect-Reference_Guide-JCR_configuration" /> for more information. + Only one naming resource must be set to configure a single database data container. </para> - </section> + <para> + The following example shows the settings for embedded mode for the <parameter>jdbcjcr</parameter> data container: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_jdbc-data-container-config/default40.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + To configure multiple repository workspaces with a single database the &#34;multi-db&#34; parameter must be switched off (set the value to &#34;false&#34;). + </para> + <para> + The following example shows configuration for two workspaces <parameter>ws</parameter> (jdbcjcr) and <parameter>ws1</parameter> (jdbcjcr) which will be persisted in one <application>PostgreSQL</application> database: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_jdbc-data-container-config/default41.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <section id="sect-Reference_Guide-Single_database_configuration-Configuration_without_DataSource"> + <title>Configuration without DataSource</title> + <para> + If you have a dedicated JDBC driver implementation with special features (such as XA transactions and statements/connections pooling) it is possible to configure a repository without using the <classname>javax.sql.DataSource</classname> bound in JNDI. + </para> + <procedure> + <step> + <para> + Remove the configuration in <classname>InitialContextInitializer</classname> for your database and configure a new one directly in the workspace container. + </para> + </step> + <step> + <para> + Remove the &#34;source-name&#34; parameter and include values for a <emphasis role="bold">JDBC driver</emphasis>, <emphasis role="bold">database url</emphasis> and <emphasis role="bold">username</emphasis> instead. + </para> + </step> + </procedure> - +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_jdbc-data-container-config/default42.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <note> + <para> + Ensure the JDBC driver provides connection pooling. Connection pooling is required for use with JCR to prevent a database overload. + </para> + </note> + </section> + + <!-- Section Commented out to discourage creation of new workspaces + <section id="sect-Reference_Guide-Single_database_configuration-Dynamic_Workspace_Creation"> + <title>Dynamic Workspace Creation</title> + <para> + Workspaces can be added dynamically during runtime. + </para> + <para> + Add new workspaces by: + </para> + <procedure> + <step> + <para> + Registering a new configuration in <literal>RepositoryContainer</literal> and create a WorkspaceContainer (<classname>ManageableRepository.configWorkspace(WorkspaceEntry wsConfig)</classname>). + </para> + </step> + <step> + <para> + Creating a new workspace (<classname>ManageableRepository.createWorkspace(String workspaceName)</classname>). + </para> + </step> + </procedure> + </section> --> + + </section> <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Multi_database_Configuration"> <title>Multi-database Configuration</title> <para> @@ -262,11 +327,7 @@ <para> It is the JNDI context initializer which registers (binds) naming resources (DataSources) for data containers. </para> - <!-- DOC NOTE: The below section has been commented as it refers to an example of repositories configured in standalone mode -<para> -The following example is in standalone mode with two data containers <parameter>jdbcjcr</parameter> (a local HSQLDB) and <parameter>jdbcjcr1</parameter> (a remote MySQL container): -</para> -<programlisting language="XML" role="XML"><xi:include parse="text" href="../../../extras/Advanced_Development_JCR_jdbc-data-container-config/default38.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> --> + </step> <step> <para> @@ -274,7 +335,7 @@ </para> <variablelist> <varlistentry> - <term>driverClassName</term> + <term><emphasis role="bold">driverClassName</emphasis></term> <listitem> <para> Some examples are &#34;<literal>org.hsqldb.jdbcDriver</literal>&#34;, &#34;<literal>com.mysql.jdbc.Driver</literal>&#34; and &#34;<literal>org.postgresql.Driver</literal>&#34; @@ -282,7 +343,7 @@ </listitem> </varlistentry> <varlistentry> - <term>URL</term> + <term><emphasis role="bold">URL</emphasis></term> <listitem> <para> For example: &#34;<literal>jdbc:hsqldb:file:target/temp/data/portal&#34;, &#34;jdbc:mysql://exoua.dnsalias.net/jcr</literal>&#34; @@ -290,7 +351,7 @@ </listitem> </varlistentry> <varlistentry> - <term>username</term> + <term><emphasis role="bold">username</emphasis></term> <listitem> <para> Examples are &#34;<literal>sa</literal>&#34;, &#34;<literal>exoadmin</literal>&#34; @@ -298,7 +359,7 @@ </listitem> </varlistentry> <varlistentry> - <term>password</term> + <term><emphasis role="bold">password</emphasis></term> <listitem> <para> Enter a password. @@ -313,7 +374,7 @@ </para> <variablelist> <varlistentry> - <term>maxActive</term> + <term><emphasis role="bold">maxActive</emphasis></term> <listitem> <para> Enter a maximum period of active time. For example; 50. @@ -321,7 +382,7 @@ </listitem> </varlistentry> <varlistentry> - <term>maxIdle</term> + <term><emphasis role="bold">maxIdle</emphasis></term> <listitem> <para> Enter a period of idle time. @@ -329,7 +390,7 @@ </listitem> </varlistentry> <varlistentry> - <term>initialSize</term> + <term><emphasis role="bold">initialSize</emphasis></term> <listitem> <para> Define an initial size. For example; 5. @@ -355,7 +416,7 @@ <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_jdbc-data-container-config/default39.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <variablelist> <varlistentry> - <term>source-name</term> + <term><emphasis role="bold">source-name</emphasis></term> <listitem> <para> A <literal>javax.sql.DataSource</literal> name configured in the <literal>InitialContextInitializer</literal> component. This was known as <parameter>sourceName</parameter> in JCR versions earlier than 1.9. @@ -363,7 +424,7 @@ </listitem> </varlistentry> <varlistentry> - <term>dialect</term> + <term><emphasis role="bold">dialect</emphasis></term> <listitem> <para> A database dialect. @@ -431,7 +492,7 @@ </listitem> </varlistentry> <varlistentry> - <term>multi-db</term> + <term><emphasis role="bold">multi-db</emphasis></term> <listitem> <para> This parameter enables multi-database containers when set to &#34;true&#34;. @@ -439,7 +500,7 @@ </listitem> </varlistentry> <varlistentry> - <term>max-buffer-size</term> + <term><emphasis role="bold">max-buffer-size</emphasis></term> <listitem> <para> A threshold (in bytes) after which a <literal>javax.jcr.Value</literal> content will be swapped to a file in a temporary storage. That is, swap for pending changes. @@ -447,7 +508,7 @@ </listitem> </varlistentry> <varlistentry> - <term>swap-directory</term> + <term><emphasis role="bold">swap-directory</emphasis></term> <listitem> <para> A path in the file system used to swap the pending changes. @@ -459,87 +520,15 @@ </procedure> <para> - The above configures two workspaces which will be persisted in two different databases (<literal>ws</literal> in <literal>HSQLDB</literal> and <literal>ws1</literal> in <literal>MySQL</literal>. + The above configures two workspaces which will be persisted in two different databases (<literal>ws</literal> in <literal>HSQLDB</literal> and <literal>ws1</literal> in <literal>MySQL</literal>). </para> <note> <para> - JCR version 1.9 supports human-readable parameter formats. See <xref linkend="sect-Reference_Guide-JCR_configuration" /> for more information). + JCR version 1.9 supports human-readable parameter formats. </para> </note> </section> - - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Single_database_configuration"> - <title>Single-database configuration</title> - <para> - Only one naming resource must be set to configure a single database data container. - </para> - <para> - The following example shows the settings for embedded mode for the <parameter>jdbcjcr</parameter> data container: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_jdbc-data-container-config/default40.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - To configure multiple repository workspaces with a single database the &#34;multi-db&#34; parameter must be switched off (set the value to &#34;false&#34;). - </para> - <para> - The following example shows configuration for two workspaces <parameter>ws</parameter> (jdbcjcr) and <parameter>ws1</parameter> (jdbcjcr) which will be persisted in one <application>PostgreSQL</application> database: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_jdbc-data-container-config/default41.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <section id="sect-Reference_Guide-Single_database_configuration-Configuration_without_DataSource"> - <title>Configuration without DataSource</title> - <para> - If you have a dedicated JDBC driver implementation with special features (such as XA transactions and statements/connections pooling) it is possible to configure a repository without using the <classname>javax.sql.DataSource</classname> bound in JNDI. - </para> - <procedure> - <step> - <para> - Remove the configuration in <classname>InitialContextInitializer</classname> for your database and configure a new one directly in the workspace container. - </para> - </step> - <step> - <para> - Remove the &#34;source-name&#34; parameter and include values for a <emphasis role="bold">JDBC driver</emphasis>, <emphasis role="bold">database url</emphasis> and <emphasis role="bold">username</emphasis> instead. - </para> - </step> - </procedure> - - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_jdbc-data-container-config/default42.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <note> - <para> - Ensure the JDBC driver provides connection pooling. Connection pooling is required for use with JCR to prevent a database overload. - </para> - </note> - </section> - - - <section id="sect-Reference_Guide-Single_database_configuration-Dynamic_Workspace_Creation"> - <title>Dynamic Workspace Creation</title> - <para> - Workspaces can be added dynamically during runtime. - </para> - <para> - Add new workspaces by: - </para> - <procedure> - <step> - <para> - Registering a new configuration in <literal>RepositoryContainer</literal> and create a WorkspaceContainer (<classname>ManageableRepository.configWorkspace(WorkspaceEntry wsConfig)</classname>). - </para> - </step> - <step> - <para> - Creating a new workspace (<classname>ManageableRepository.createWorkspace(String workspaceName)</classname>). - </para> - </step> - </procedure> - </section> - - </section> - - <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Simple_and_Complex_queries"> <title>Simple and Complex queries</title> <para> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/lock-manager-config.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/lock-manager-config.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/lock-manager-config.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -5,13 +5,18 @@ ]> <section id="sect-Reference_Guide-LockManager"> <title>LockManager</title> + <note> + <title>DOC REVIEW:</title> + <para> + Information regarding <emphasis role="bold">LockManagerImpl</emphasis> has been removed from this section based on QE feedback. Please review to ensure no impact on technical accuracy. + </para> + </note> <para> The LockManager stores lock objects. It can lock or release objects as required. It is also responsible for removing stale locks. </para> - <para> - The length of time LockManager allows a lock to remain in place can be configured with the &#34;<literal>time-out</literal>&#34; property. - </para> - <para> + + <!-- DOC NOTE: Below hidden as JCR standalone content (As per feedback from Marek Posolda + <para> JCR provides two base implementations of the LockManager: </para> <orderedlist> @@ -26,7 +31,7 @@ </para> </listitem> </orderedlist> - <para> + <para> <classname>LockManagerImpl</classname> is simple implementation of LockManager which is faster than <classname>CacheableLockManager</classname>. It stores lock objects in HashMap and can retain persistant locks if the <literal>LockPersister</literal> is configured. </para> <para> @@ -34,9 +39,12 @@ </para> <para> The second implementation (<classname>CacheableLockManagerImpl</classname>) will be the primary focus of this section. - </para> + </para> --> + <para> + The LockManager in &PRODUCT; is implemented with <classname>org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl</classname>. + </para> <para> - LockManager is enabled by adding <literal>lock-manager-configuration</literal> to <literal>workspace-configuration</literal>. + It is is enabled by adding <literal>lock-manager-configuration</literal> to <literal>workspace-configuration</literal>. </para> <para> For example: @@ -48,8 +56,11 @@ <para> <classname>CacheableLockManagerImpl</classname> stores lock objects in JBoss-cache (which implements JDBCCacheLoader to store locks in a database). This means its locks are replicable and can affect an entire cluster rather than just a single node. </para> + <para> + The length of time LockManager allows a lock to remain in place can be configured with the &#34;<literal>time-out</literal>&#34; property. + </para> <para> - Both implementations support the removal of expired locks. The LockRemover thread periodically polls LockManager for locks that have passed the time-out limit and must be removed. + The LockRemover thread periodically polls LockManager for locks that have passed the time-out limit and must be removed. </para> <para> The time-out for LockRemover is set as follows (the default value is 30m): @@ -102,7 +113,7 @@ Refer to <ulink url="http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader"... for more information about JBoss Cache and JDBCCacheLoader. </para> <section id="sect-Reference_Guide-CacheableLockManagerImpl-Simple_Jboss_Cache_Configuration"> - <title>Simple Jboss Cache Configuration</title> + <title>Simple JBoss Cache Configuration</title> <para> One method to configure the LockManager is to put a JBoss Cache configuration file path into <classname>CacheableLockManagerImpl</classname>. </para> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -7,6 +7,7 @@ <title>Multilanguage support in eXo JCR RDB backend</title> <para> Whenever a relational database is used to store multilingual text data in the eXo Java Content Repository the configuration must be adapted to support UTF-8 encoding. + Dialect is automatically detected for certified database. You can still enforce it in case fof failure, see below. </para> <para> The following sections describe enabling UTF-8 support with various databases. @@ -37,7 +38,7 @@ <orderedlist> <listitem> <para> - The configuration file to be modified for these changes is:<filename>/webapps/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename> + The configuration file to be modified for these changes is:<filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> </para> </listitem> <listitem> @@ -50,22 +51,9 @@ <section id="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-Oracle"> <title>Oracle</title> <para> - In order to run a multi-language instance of JCR on an Oracle backend, Unicode encoding should be applied to the database. Other Oracle globalization parameters will not be effective in this. The property to modify is <constant>NLS_CHARACTERSET</constant>. - </para> + In order to run a multi-language instance of JCR on an Oracle backend, Unicode encoding should be applied to the database. + </para> <para> - <constant>NLS_CHARACTERSET</constant> has tested with many European and Asian languages when set at <constant>AL32UTF8</constant>. - </para> - <para> - The below example of the multi-language database configuration has been used in pre-release JCR testing: - </para> - -<programlisting language="Java" role="Java"><xi:include href="../../../extras/Advanced_Development_JCR_multilanguage-support/default53.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <warning> - <para> - JCR 1.12.<replaceable>x</replaceable> versions do not use <parameter>NVARCHAR</parameter> columns, so the value of the <parameter>NLS_NCHAR_CHARACTERSET</parameter> parameter has no effect. - </para> - </warning> - <para> To create a database with Unicode encoding using Oracle dialect for the Workspace Container, implement the following settings: </para> @@ -84,11 +72,12 @@ <para> Below is an example of creating a UTF-8 database using the <parameter>db2</parameter> dialect for a workspace container with DB2 version 9 and higher: </para> - <!-- DOC TODO: Find out what programming language this is written in for syntax highlighting --> + <programlisting>DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US </programlisting> <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_multilanguage-support/default56.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <note> <para> For DB2 version 8.<replaceable>x</replaceable> support change the property &#34;dialect&#34; to db2v8. Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -12,20 +12,29 @@ Below is an example of the configuration file that governs search behaviors. Refer to <xref linkend="sect-Reference_Guide-Search_Configuration-Global_Search_Index" /> for how searching operates in JCR and discussions about customized searches. </para> <para> - The JCR index configuration file is located at <filename>/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + The JCR index configuration file is located at <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> <para> A code example is included below with a list of the configuration parameters shown below that. </para> <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_search-configuration/default61.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <table align="left" id="tabl-Reference_Guide-Search_Configuration-Configuration_parameters" pgwide="1"> + <para> + The table below outlines the Configuration Parameters available, their default setting, which version of eXo JCR they were implemented in and other useful information: + </para> + <note> + <title>DOC REVIEW:</title> + <para> + The table below has been updated based on QE feedback. Please review for technical accuracy. + </para> +</note> + <table id="tabl-Reference_Guide-Search_Configuration-Configuration_parameters" > <!--align="left" pgwide="1"--> <title>Configuration parameters</title> - <!-- Removing 'version' column <tgroup cols="4"> --> - <tgroup cols="3"> - <colspec colwidth="90pt"></colspec> - <colspec colwidth="135pt"></colspec> - <colspec colwidth="270pt"></colspec> + <tgroup cols="4"> + <colspec colname="1" colwidth="90pt"></colspec> + <colspec colname="2" colwidth="90pt"></colspec> + <colspec colname="3" colwidth="150pt"></colspec> + <colspec colname="4" colwidth="50pt"></colspec> <thead> <row> <entry> @@ -43,9 +52,9 @@ Description </para> </entry> - <!-- <entry> -Version -</entry> --> + <entry> + Implemented in Version + </entry> </row> </thead> <tbody> @@ -62,12 +71,12 @@ </entry> <entry> <para> - The location of the index directory. This parameter is mandatory. It is called &#34;<literal>indexDir</literal>&#34; in versions prior to version 1.9. + The location of the index directory. This parameter is mandatory. It is called "<literal>indexDir</literal>" in versions prior to eXo JCR version 1.9. </para> </entry> - <!-- <entry> -1.0 -</entry> --> + <entry> + 1.0 + </entry> </row> <row> <entry> @@ -85,10 +94,9 @@ Advises lucene to use compound files for the index files. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -106,10 +114,9 @@ The minimum number of nodes in an index until segments are merged. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -125,10 +132,9 @@ Idle time in seconds until the volatile index part is moved to a persistent index even though <literal>minMergeDocs</literal> is not reached. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -143,13 +149,12 @@ </entry> <entry> <para> - The maximum number of nodes in segments that will be merged. The default value changed to <literal>Integer.MAX_VALUE</literal> in JCR version 1.9. + The maximum number of nodes in segments that will be merged. The default value changed to <literal>Integer.MAX_VALUE</literal> in eXo JCR version 1.9. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -167,10 +172,9 @@ Determines how often segment indices are merged. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -188,10 +192,9 @@ The number of words that are fulltext indexed at most per property. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -209,10 +212,9 @@ Size of the document number cache. This cache maps uuids to lucene document numbers </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -230,10 +232,9 @@ Runs a consistency check on every startup. If false, a consistency check is only performed when the search index detects a prior forced shutdown. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -251,10 +252,9 @@ Errors detected by a consistency check are automatically repaired. If false, errors are only written to the log. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -271,10 +271,9 @@ This class must also extend from the class: <literal>org.exoplatform.services.jcr.impl.core. query.AbstractQueryImpl</literal>. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -289,13 +288,12 @@ </entry> <entry> <para> - If true and the query does not contain an &#39;order by&#39; clause, result nodes will be in document order. For better performance set to &#39;false&#39; when queries return many nodes. + If true and the query does not contain an 'order by' clause, result nodes will be in document order. For better performance set to 'false' when queries return many nodes. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -313,10 +311,9 @@ The number of results when a query is executed. Default value: <literal>Integer.MAX_VALUE</literal>. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -337,10 +334,9 @@ This should be used for the <literal>rep:excerpt()</literal> function in a query. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -358,10 +354,9 @@ If set to true additional information is stored in the index to support highlighting using the <literal>rep:excerpt()</literal> function. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -382,10 +377,9 @@ The default value is null. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -403,10 +397,9 @@ The path to the synonym provider configuration file. This path is interpreted relative to the path parameter. If there is a path element inside the <literal>SearchIndex</literal> element, then this path is interpreted relative to the root path of the path. Whether this parameter is mandatory depends on the synonym provider implementation. The default value is null. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -424,10 +417,9 @@ The path to the indexing configuration file. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -445,10 +437,9 @@ The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.IndexingConfiguration</literal>. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -466,10 +457,9 @@ If set to true a consistency check is performed depending on the parameter <literal>forceConsistencyCheck</literal>. If set to false no consistency check is performed on startup, even if a redo log had been applied. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -487,10 +477,9 @@ The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core. query.lucene.SpellChecker</literal>. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -500,18 +489,17 @@ </entry> <entry> <para> - 50(Kb) + 50(KB) </para> </entry> <entry> <para> - The default size of error log file in Kb. + The default size of error log file in KB. </para> </entry> - <!-- <entry> -1.9 -</entry> - --> + <entry> + 1.9 + </entry> </row> <row> <entry> @@ -532,8 +520,13 @@ For example: <command>-Dupgrade-index=true</command> </para> <para> - Indexes before JCR 1.12 will not run with JCR 1.12. Hence you have to run an automatic migration: Start JCR with -Dupgrade-index=true. + Indexes prior to eXo JCR 1.12 will not run with eXo JCR 1.12. You must run an automatic migration. </para> + <para> + Start eXo JCR with: + </para> +<programlisting><command> -Dupgrade-index=true</command> +</programlisting> <para> The old index format is then converted in the new index format. After the conversion the new format is used. </para> @@ -544,10 +537,9 @@ It is reccommended that a backup of the index be made before conversion. (Only for migrations from JCR 1.9 and later.) </para> </entry> - <!-- <entry> -1.12 -</entry> - --> + <entry> + 1.12 + </entry> </row> <row> <entry> @@ -565,10 +557,9 @@ Class name of a lucene analyzer to use for fulltext indexing of text. </para> </entry> - <!-- <entry> -1.12 -</entry> - --> + <entry> + 1.12 + </entry> </row> </tbody> </tgroup> @@ -586,18 +577,11 @@ </areaspec> <programlisting language="Java" role="Java"><xi:include href="../../../extras/Advanced_Development_JCR_search-configuration/default62.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="Java" role="JAVA"><![CDATA[public TokenStream tokenStream(String fieldName, Reader reader) { -StandardTokenizer tokenStream = new StandardTokenizer(reader, replaceInvalidAcronym); -tokenStream.setMaxTokenLength(maxTokenLength); -TokenStream result = new StandardFilter(tokenStream); -result = new LowerCaseFilter(result); -result = new StopFilter(result, stopSet); -return result; -}]]></programlisting> --> + <calloutlist> <callout arearefs="area-Reference_Guide-Search_Configuration-Global_Search_Index-StandardFilter"> <para> - The first filter (StandardFilter) removes possessive apostrophes (<emphasis role="bold">&#39;s</emphasis>) from the end of words and removes periods (<emphasis role="bold">.</emphasis>) from acronyms. + The first filter (StandardFilter) removes possessive apostrophes (<emphasis role="bold">'s</emphasis>) from the end of words and removes periods (<emphasis role="bold">.</emphasis>) from acronyms. </para> </callout> <callout arearefs="area-Reference_Guide-Search_Configuration-Global_Search_Index-LowerCaseFilter"> @@ -614,12 +598,12 @@ </programlistingco> <para> - The global search index is configured in the <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the &#34;query-handler&#34; tag. + The global search index is configured in the <filename><replaceable>JBOSS_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 "query-handler" tag. </para> - -<programlisting language="Java" role="Java"><xi:include href="../../../extras/Advanced_Development_JCR_search-configuration/default63.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting>&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; -</programlisting> --> + +<programlisting language="XML" role="XML"><![CDATA[<query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> +]]></programlisting> + <para> The same analyzer should always be used for indexing and for querying in lucene. Results may be unpredictable in other instances. eXo JCR does this automatically. The StandardAnalyzer (configured by default) can, however, be replaced with another. </para> @@ -633,7 +617,7 @@ </para> </formalpara> <para> - The <phrase>ISOLatin1AccentFilter</phrase> is not present in the current lucene version used by Exo. + The <phrase>ISOLatin1AccentFilter</phrase> is not present in the current lucene version used by eXo. </para> <para> In order to use a different filter, a new analyzer must be created, as well as new search index to use the analyzer. These are packaged into a jar file, which is then deployed with the application. @@ -682,23 +666,25 @@ <note> <para> - In JCR version 1.12 (and later) the analyzer can be directly set in the configuration. For users with this version the creation of a new SearchIndex for new analyzers is redundant. + In eXo JCR version 1.12 (and later) the analyzer can be directly set in the configuration. For users with this version the creation of a new SearchIndex for new analyzers is redundant. </para> </note> <para> To configure an application to use a new <literal>SearchIndex</literal>, replace the following code: </para> -<programlisting language="XML" role="XML">&#60;query-handler class=&#34;org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex&#34;&#62; +<programlisting language="XML" role="XML"><![CDATA[<query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> + ]]> </programlisting> <para> - ...in <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename> with the new class + in <filename><replaceable>JBOSS_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: </para> -<programlisting language="XML" role="XML">&#60;query-handler class=&#34;mypackage.indexation.MySearchIndex&#62; +<programlisting language="XML" role="XML"><![CDATA[<query-handler class="mypackage.indexation.MySearchIndex> + ]]> </programlisting> <para> - To configure an application to use a new analyzer, add the &#34;<parameter>analyzer</parameter>&#34; parameter to each query-handler configuration in <filename>portal/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>JBOSS_HOME</replaceable>/server/<replaceable>&lt;VERSION&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>: </para> <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_search-configuration/default69.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> @@ -720,7 +706,8 @@ To configure the indexing behavior add a parameter to the query-handler element in your configuration file. </para> -<programlisting language="XML" role="XML">&#60;param name=&#34;indexing-configuration-path&#34; value=&#34;/indexing_configuration.xml&#34;/&#62; +<programlisting language="XML" role="XML"><![CDATA[<param name="indexing-configuration-path" value="/indexing_configuration.xml"/> + ]]> </programlisting> <formalpara id="form-Reference_Guide-IndexingConfiguration-Node_Scope_Limit"> <title>Node Scope Limit</title> @@ -749,6 +736,7 @@ </para> <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_search-configuration/default73.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Conditional_Index_Rules"> <title>Conditional Index Rules</title> <para> @@ -758,7 +746,7 @@ <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_search-configuration/default74.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - In the above example the first rule only applies if the <parameter>nt:unstructured</parameter> node has a priority property with a value &#39;<parameter>high</parameter>&#39;. The condition syntax only supports the equals operator and a string literal. + In the above example the first rule only applies if the <parameter>nt:unstructured</parameter> node has a priority property with a value <parameter>high</parameter>. The condition syntax only supports the equals operator and a string literal. </para> <para> Properties may also be referenced on the condition that are not on the current node: @@ -770,6 +758,7 @@ </para> <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_search-configuration/default76.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Exclusion_from_the_Node_Scope_Index"> <title>Exclusion from the Node Scope Index</title> <para> @@ -777,13 +766,14 @@ </para> </formalpara> <para> - A node scope search normally finds all nodes of an index. That is to say; <literal>jcr:contains(., &#39;foo&#39;)</literal> returns all nodes that have a string property containing the word &#39;<replaceable>foo</replaceable>&#39;. + A node scope search normally finds all nodes of an index. That is to say; <literal>jcr:contains(., 'foo')</literal> returns all nodes that have a string property containing the word '<replaceable>foo</replaceable>'. </para> <para> Properties can be explicitly excluded from the node scope index with: </para> <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_search-configuration/default77.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Index_Aggregates"> <title>Index Aggregates</title> <para> @@ -813,6 +803,7 @@ </para> <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_search-configuration/default81.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <formalpara id="form-Reference_Guide-IndexingConfiguration-Property_Level_Analyzers"> <title>Property-Level Analyzers</title> <para> @@ -822,7 +813,7 @@ <programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_search-configuration/default82.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - The configuration above sets lucene <emphasis role="bold">KeywordAnalyzer</emphasis> to index and search the property &#34;<replaceable>mytext</replaceable>&#34; across the entire workspace while the &#34;<replaceable>mytext2</replaceable>&#34; property is searched with the <emphasis role="bold">WhitespaceAnalyzer</emphasis>. + The configuration above sets lucene <emphasis role="bold">KeywordAnalyzer</emphasis> to index and search the property "<replaceable>mytext</replaceable>" across the entire workspace while the "<replaceable>mytext2</replaceable>" property is searched with the <emphasis role="bold">WhitespaceAnalyzer</emphasis>. </para> <para> The <emphasis role="bold">WhitespaceAnalyzer</emphasis> tokenizes a property, the <emphasis role="bold">KeywordAnalyzer</emphasis> takes the property as a whole. @@ -837,13 +828,13 @@ </para> </formalpara> <para> - For example: the property &#34;<parameter>mytext</parameter>&#34; contains the text; &#34;<emphasis>testing my analyzers</emphasis>&#34; but no analyzers have been configured for this property (and the default analyzer in SearchIndex has not been changed). + For example: the property "<parameter>mytext</parameter>" contains the text; "<emphasis>testing my analyzers</emphasis>" but no analyzers have been configured for this property (and the default analyzer in SearchIndex has not been changed). </para> <para> If the query is: </para> -<programlisting language="Java" role="JAVA">xpath = &#34;//*[jcr:contains(mytext,&#39;analyzer&#39;)]&#34; +<programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(mytext,'analyzer')]" </programlisting> <para> The <literal>xpath</literal> does not return a result in the node with the property above and default analyzers. @@ -852,7 +843,7 @@ Also, if a search is done on the node scope as follows: </para> -<programlisting language="Java" role="JAVA">xpath = &#34;//*[jcr:contains(.,&#39;analyzer&#39;)]&#34; +<programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(.,'analyzer')]" </programlisting> <para> No result will be returned. @@ -861,24 +852,24 @@ Only specific analyzers can be set on a node property, and the node scope indexing and analyzing is always done with the globally defined analyzer in the SearchIndex element. </para> <para> - If the analyzer used to index the &#34;mytext&#34; property above is changed to: + If the analyzer used to index the "mytext" property above is changed to: </para> -<programlisting language="XML" role="XML">&#60;analyzer class=&#34;org.apache.lucene.analysis.Analyzer.GermanAnalyzer&#34;&#62; -&#60;property&#62;mytext&#60;/property&#62; -&#60;/analyzer&#62; -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[<analyzer class="org.apache.lucene.analysis.Analyzer.GermanAnalyzer"> +<property>mytext</property> +</analyzer> + ]]></programlisting> <para> The search below would return a result because of the word stemming (analyzers - analyzer). </para> -<programlisting language="Java" role="JAVA">xpath = &#34;//*[jcr:contains(mytext,&#39;analyzer&#39;)]&#34; +<programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(mytext,'analyzer')]" </programlisting> <para> The second search in the example: </para> -<programlisting language="Java" role="JAVA">xpath = &#34;//*[jcr:contains(.,&#39;analyzer&#39;)]&#34; +<programlisting language="Java" role="JAVA">xpath = "//*[jcr:contains(.,'analyzer')]" </programlisting> <para> Would still not give a result, since the node scope is indexed with the global analyzer, which in this case does not take into account any word stemming. Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/Advanced/JCR.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -28,4 +28,5 @@ --> <!-- <xi:include href="JCR/statistics.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + --> </chapter> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -37,7 +37,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>JBOSS_AS</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>JBOSS_HOME</replaceable>/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/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/BackendConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/BackendConfiguration.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/BackendConfiguration.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -31,7 +31,7 @@ <section id="sect-Reference_Guide-PicketLink_IDM_integration-Configuration_files"> <title>Configuration files</title> <para> - The main configuration file is <emphasis role="bold">idm-configuration.xml</emphasis>: + The main configuration file is <filename>02portal.war/WEB-INF/conf/organization/idm-configuration.xml</filename>: </para> <programlistingco> <areaspec> @@ -71,6 +71,9 @@ <varlistentry> <term>hibernate.annotations</term> <listitem> + <para> + <parameter>values-param</parameter> + </para> <para> A list of annotated classes that will be added to Hibernate configuration. </para> @@ -79,6 +82,9 @@ <varlistentry> <term>hibernate.mappings</term> <listitem> + <para> + <parameter>values-param</parameter> + </para> <para> A list of xml files that will be added to hibernate configuration as mapping files. </para> @@ -110,6 +116,9 @@ <term>apiCacheConfig</term> <term>storeCacheConfig</term> <listitem> + <para> + <parameter>value-param</parameter> + </para> <para> These options reference the JBoss cache configuration used for Picketlink. </para> @@ -169,7 +178,7 @@ <term>associationMembershipType</term> <listitem> <para> - If this option is used, then each Membership, created with MembrshipType that is equal to the value specified here, will be stored in PicketLink IDM as simple Group-User association. + If this option is used, then each Membership, created with MembershipType that is equal to the value specified here, will be stored in PicketLink IDM as simple Group-User association. </para> </listitem> </varlistentry> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -5,10 +5,11 @@ ]> <section id="sect-Reference_Guide-Predefined_User_Configuration"> <title>Predefined User Configuration</title> + <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 <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal>. This file uses the portal XML configuration schema. It lists several configuration plugins. + The initial Organization configuration should be specified by editing the content of <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</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 plugins. </para> </section> @@ -22,7 +23,7 @@ The <emphasis role="bold">checkDatabaseAlgorithm</emphasis> initialization parameter determines how the database update is performed. </para> <para> - If its value is set to <emphasis role="bold">entry</emphasis> it means that each user, group and membership listed in the configuration is checked each time &PRODUCT; is started. If the entry doesn&#39;t yet exist in the database, it is created. + If its value is set to <emphasis role="bold">entry</emphasis> it means that each user, group and membership listed in the configuration is checked each time &PRODUCT; is started. If the entry does not yet exist in the database, it is created. </para> <para> If <emphasis role="bold">checkDatabaseAlgorithm</emphasis> parameter value is set to <emphasis role="bold">empty</emphasis>, the configuration data will be updated to the database only if the database is empty. @@ -50,6 +51,11 @@ <para> The predefined groups are specified in the <emphasis role="bold">group</emphasis> field of the <emphasis role="bold">OrganizationConfig</emphasis> plugin parameter. </para> + <note> + <para> + See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. + </para> + </note> <programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default99.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> </section> @@ -57,18 +63,29 @@ <section id="sect-Reference_Guide-Predefined_User_Configuration-Users"> <title>Users</title> + <para> - The predefined users are specified in the <emphasis role="bold">membershipType</emphasis> field of the <emphasis role="bold">OrganizationConfig</emphasis> plugin parameter. + The predefined users are specified in the <emphasis role="bold">user</emphasis> field of the <emphasis role="bold">OrganizationConfig</emphasis> plugin parameter. </para> - + <note> + <para> + See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. + </para> + </note> <programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default100.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> </section> <section id="sect-Reference_Guide-Predefined_User_Configuration-Plugin_for_monitoring_user_creation"> - <title>Plugin for monitoring user creation</title> + <title>Plugin for managing user creation</title> + <note> + <title>DOC REVIEW:</title> + <para> + This section has been updated based on QE feedback. Please review for technical accuracy. + </para> +</note> <para> - The plugin type <literal>org.exoplatform.services.organization.impl.NewUserEventListener</literal> specifies which groups all the newly created users should become members of. + The plugin type <literal>org.exoplatform.services.organization.impl.NewUserEventListener</literal> specifies which groups all newly created users should become members of. </para> <para> It specifies the group memberships and the membership types to use (while a <emphasis>group</emphasis> is just a set of users, a membership <emphasis>type</emphasis> represents a user&#39;s role within a group). It also specifies a list of users that should not be processed (such as administrative users like &#39;<literal>root</literal>&#39;). Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/GadgetDevelopment/SetupGadgetServer.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/GadgetDevelopment/SetupGadgetServer.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/GadgetDevelopment/SetupGadgetServer.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -1,90 +1,66 @@ -<?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" [ +<?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-Advanced_Gadget_Administration"> - <title>Advanced Gadget Administration</title> - <section id="sect-Reference_Guide-Advanced_Gadget_Administration-Virtual_servers_for_gadget_rendering"> - <title>Virtual servers for gadget rendering</title> - <para> - &PRODUCT; recommends using two virtual hosts for security. If the gadget is running on a different domain than the container, it is unable to interfere with the portal by modifying code or cookies. - </para> - <para> - An example would hosting the portal from <emphasis role="bold">http://www.sample.com</emphasis> and the gadgets from <emphasis role="bold">http://www.samplemodules.com</emphasis>. - </para> - <para> - To do this, configure the <emphasis>gadgets.hostName</emphasis> parameter in the <filename>server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/portal/application-registry-configuration.xml</filename> file. The value is the <emphasis role="bold">path/to/gadgetServer</emphasis> in <literal>GadgetRegisteryService</literal>: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Gadget_Development_SetupGadgetServer/default139.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="XML" role="XML"><![CDATA[<component> -<key>org.exoplatform.application.gadget.GadgetRegistryService</key> -<type>org.exoplatform.application.gadget.impl.GadgetRegistryServiceImpl</type> -<init-params> -<value-param> -<name>gadgets.hostName</name> -<description>Gadget server url</description> -<value>http://localhost:8080/GateInGadgetServer/gadgets/</value> -</value-param> -</init-params> -</component>]]></programlisting> --> - <para> - It is also possible to have multiple rendering servers. This helps to balance the rendering load across multiple servers. - </para> - <para> - When deploying on the same server ensure the gadget initiates before anything that calls it (for example; the webapp <literal>GateInGadgets</literal> which uses <literal>org.exoplatform.application.gadget.GadgetRegister</literal>). - </para> - </section> - - - <section id="sect-Reference_Guide-Advanced_Gadget_Administration-Configuration"> - <title>Configuration</title> - <section id="sect-Reference_Guide-Configuration-Security_key"> - <title>Security key</title> - <para> - A file called <emphasis role="bold">key.txt</emphasis> has to be generated for every installation of &PRODUCT; to be secure. This file contains a secret key used to encrypt the security token used for authenticating the user. - </para> - <para> - In Linux systems this file can be generated with: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Gadget_Development_SetupGadgetServer/default140.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting><command>dd if=/dev/random bs=32 count=1 | openssl base64 &gt; /tmp/key.txt</command> -</programlisting> --> - </section> - - - <section id="sect-Reference_Guide-Configuration-Gadget_proxy_and_concat_configuration"> - <title>Gadget proxy and concat configuration</title> - <para> - These servers have to be on the same domain as the gadget server. You can configure the container in <filename>eXoGadgetServer:/WEB-INF/classes/containers/default/container.js</filename>. - </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/Gadget_Development_SetupGadgetServer/default141.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="Java" role="JAVA">"gadgets.content-rewrite" : { -"include-urls": ".*", -"exclude-urls": "", -"include-tags": ["link", "script", "embed", "img", "style"], -"expires": "86400", -"proxy-url": "http://localhost:8080/eXoGadgetServer/gadgets/proxy?url=", -"concat-url": "http://localhost:8080/eXoGadgetServer/gadgets/concat?" -}, -</programlisting> --> - </section> - - - <section id="sect-Reference_Guide-Configuration-Proxy"> - <title>Proxy</title> - <para> - To allow external gadgets when the server is behind a proxy, add the following code to the beginning of the JVM: - </para> - -<programlisting language="Java" role="Java">-Dhttp.proxyHost=proxyhostURL -Dhttp.proxyPort=proxyPortNumber -Dhttp.proxyUser=someUserName -Dhttp.proxyPassword=somePassword + <title>Advanced Gadget Administration</title> + <section id="sect-Reference_Guide-Advanced_Gadget_Administration-Virtual_servers_for_gadget_rendering"> + <title>Virtual servers for gadget rendering</title> + <para> + &PRODUCT; recommends using two virtual hosts for security. If the gadget is running on a different domain than the container, it is unable to interfere with the portal by modifying code or cookies. + </para> + <para> + An example would be hosting the portal from <emphasis role="bold">http://www.sample.com</emphasis> and the gadgets from <emphasis role="bold">http://www.samplemodules.com</emphasis>. + </para> + <para> + To do this, configure the <emphasis>gadgets.hostName</emphasis>parameter in the <filename>server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/portal/application-registry-configuration.xml</filename>file. The value is the <emphasis role="bold">path/to/gadgetServer</emphasis>in <literal>GadgetRegistryService.xml</literal>: + </para> +<programlisting language="XML" role="XML"><xi:include href="../../extras/Gadget_Development_SetupGadgetServer/default139.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting> - </section> - </section> - + <para> + It is also possible to have multiple rendering servers. This helps to balance the rendering load across multiple servers. + </para> + <para> + When deploying on the same server ensure the gadget initiates before anything that calls it (for example; the webapp <literal>eXoGadgets</literal>which uses <literal>org.exoplatform.application.gadget.GadgetRegister</literal>). + </para> + </section> + <section id="sect-Reference_Guide-Advanced_Gadget_Administration-Configuration"> + <title>Configuration</title> + <section id="sect-Reference_Guide-Configuration-Security_key"> + <title>Security key</title> + <para> + A specific file called <emphasis role="bold">key.txt</emphasis>has to be generated for each installation of &PRODUCT; to be secure. This file contains a secret key used to encrypt the security token used for authenticating the user. + </para> + <para> + In Linux systems this file can be generated with: + </para> +<programlisting language="XML" role="XML"><xi:include href="../../extras/Gadget_Development_SetupGadgetServer/default140.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</programlisting> + <important> + <title><emphasis role="bold">DOCS REVIEW: Technical verification required</emphasis></title> + <para> + This <filename>key.txt</filename>file should be placed in the <filename>/conf/gatein/gadgets</filename>folder of your profile. + </para> + </important> + </section> + <section id="sect-Reference_Guide-Configuration-Gadget_proxy_and_concat_configuration"> + <title>Gadget proxy and concat configuration</title> + <para> + These servers have to be on the same domain as the gadget server. You can configure the container in <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/eXoGadgetServer.war:/WEB-INF/classes/containers/default/container.js</filename>. + </para> +<programlisting language="Java" role="Java"><xi:include href="../../extras/Gadget_Development_SetupGadgetServer/default141.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</programlisting> + </section> + <section id="sect-Reference_Guide-Configuration-Proxy"> + <title>Proxy</title> + <para> + To allow external gadgets when the server is behind a proxy, add the following code to the beginning of the JVM: + </para> +<programlisting language="Java" role="Java">-Dhttp.proxyHost=proxyhostURL -Dhttp.proxyPort=proxyPortNumber -Dhttp.proxyUser=someUserName -Dhttp.proxyPassword=somePassword</programlisting> + </section> + </section> </section> - Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -11,7 +11,7 @@ &PRODUCT;&#39;s default home page URL is <literal>http://{hostname}:{port}/portal/</literal>. There may be multiple independent portals deployed in parallel at any given time, each of which has its root context (<literal>http://{hostname}:{port}/sample-portal/</literal>, for example). </para> <para> - Each portal is internally composed of one or more &#39;portals&#39;. This is because there needs to be at least one such portal available. The default portal is called &#39;<emphasis>Classic</emphasis>&#39;. When accessing &PRODUCT;&#39;s default URL, you are automatically directed to the &#39;<emphasis>Classic</emphasis>&#39; portal. + Each portal container is internally composed of one or more &#39;portals&#39;. This is because there needs to be at least one such portal available. The default portal is called &#39;<emphasis>Classic</emphasis>&#39;. When accessing &PRODUCT;&#39;s default URL, you are automatically directed to the &#39;<emphasis>Classic</emphasis>&#39; portal. </para> <para> The default portal performs another important task. When starting up &PRODUCT; for the first time, its JCR database (where portal runtime-configurable settings are stored) will be empty . The default portal detects this and triggers automatic data initialization. @@ -26,26 +26,7 @@ </para> <programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_DefaultPortalConfiguration/default143.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="XML" role="XML"><![CDATA[<component> -<key>org.exoplatform.portal.config.UserPortalConfigService</key> -<type>org.exoplatform.portal.config.UserPortalConfigService</type> -<component-plugins> -<component-plugin> -<name>new.portal.config.user.listener</name> -<set-method>initListener</set-method> -<type>org.exoplatform.portal.config.NewPortalConfigListener</type> -<description>this listener init the portal configuration</description> -<init-params> -<value-param> -<name>default.portal</name> -<description>The default portal for checking db is empty or not</description> -<value>classic</value> -</value-param> -... -</init-params> -</component-plugin> -</component-plugins> -</component>]]></programlisting> --> + <para> In this example the <emphasis>Classic</emphasis> portal has been set as the default. </para> @@ -53,8 +34,9 @@ Notice that the <literal>NewPortalConfigListener</literal> <parameter>component-plugin</parameter> is used to add configuration to <literal>UserPortalConfigService</literal>, which is designed in this way to allow other components to add configuration to it. </para> <para> - <emphasis>Components</emphasis>, <emphasis>component-plugins</emphasis>, and <emphasis>init-params</emphasis> are explained in a later chapter of this document. + <emphasis>Components</emphasis>, <emphasis>component-plugins</emphasis>, and <emphasis>init-params</emphasis> are explained in a later chapter of this document (<xref linkend="chap-Reference_Guide-Foundations"/>). </para> +<!-- DOC NOTE: Rather than linking 11 chapters forward here (which contravenes the RH Style Guide, can this information be relocated to here?--> </section> </chapter> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -62,7 +62,8 @@ It is also possible to apply a nested container that can also contain portlets. Row, column or tab containers are then responsible for the layout of their child portlets. </para> <para> - Each application references a portlet using its application name (usually the name of the WAR file) and a portlet reference (The name of the portlet as defined in portlet.xml) + Each application references a portlet using its application name (usually the name of the WAR file) +and a portlet reference (the name of the portlet as defined in portlet.xml). </para> <para> Use the <literal>page-body</literal> tag to define where &PRODUCT; should render the current page. @@ -81,7 +82,7 @@ <para> When the <literal>#{...}</literal> syntax is used in a <literal>&#60;label&#62;</literal> element, the enclosed property name serves as a key that is automatically passed to internationalization mechanism which replaces the literal property name with a localized value taken from the associated properties file matching the current locale. </para> - <!-- Replaced code navigation.xml with code from GateIn commit r3831 (as per instruction from theute) --> + <!-- DOC NOTE: Replaced code navigation.xml with code from GateIn commit r3831 (as per instruction from theute) --> <programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/navigation.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> This navigation tree can have multiple views inside portlets (such as the breadcrumbs portlet) that render the current view node, the site map or the menu portlets. @@ -97,10 +98,10 @@ </listitem> </varlistentry> <varlistentry> - <term>Subpages</term> + <term>Subnodes</term> <listitem> <para> - Subpages can also be created using the following XML structure + Subnodes can also be created using the following XML structure </para> <programlistingco> <areaspec> @@ -111,7 +112,7 @@ <calloutlist> <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation-subpage"> <para> - This element defines the parent/child relationship between a page and a subpage. + This element defines the parent/child relationship between a page and a subnode. </para> </callout> </calloutlist> @@ -121,102 +122,22 @@ <varlistentry> <term>pages.xml</term> <listitem> + <note> + <title>DOC REVIEW:</title> + <para> + The paragraph below has been updated based on QE feedback. Please review for technical accuracy + </para> + </note> <para> - This configuration file structure is very similar to <filename>portal.xml</filename> and it can also contain container tags. Each application can decide whether to render the portlet border, the window state, the icons or portlet&#39;s mode. + 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&#39;s 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 href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/pages.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- Replaced code pages.xml with code from GateIn commit r3831 (as per instruction from theute) -<?xml version="1.0" encoding="ISO-8859-1"?> -<page-set -xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" -xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0" -xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0"> -<page> -<name>homepage</name> -<title>Home Page</title> -<access-permissions>Everyone</access-permissions> -<edit-permission>*:/platform/administrators</edit-permission> -<portlet-application> -<portlet> -<application-ref>web</application-ref> -<portlet-ref>HomePagePortlet</portlet-ref> -<preferences> -<preference> -<name>template</name> -<value>system:/templates/groovy/webui/component/UIHomePagePortlet.gtmpl</value> -<read-only>false</read-only> -</preference> -</preferences> -</portlet> -<title>Home Page portlet</title> -<access-permissions>Everyone</access-permissions> -<show-info-bar>false</show-info-bar> -<show-application-state>false</show-application-state> -<show-application-mode>false</show-application-mode> -</portlet-application> -</page> -<page> -<name>groupnavigation</name> -<title>Group Navigation</title> -<access-permissions>*:/platform/users</access-permissions> -<edit-permission>*:/platform/administrators</edit-permission> -<portlet-application> -<portlet> -<application-ref>exoadmin</application-ref> -<portlet-ref>GroupNavigationPortlet</portlet-ref> -</portlet> -<title>Group Navigation</title> -<access-permissions>Everyone</access-permissions> -<show-info-bar>false</show-info-bar> -</portlet-application> -</page> -<page> -<name>portalnavigation</name> -<title>Portal Navigation</title> -<access-permissions>*:/platform/users</access-permissions> -<edit-permission>*:/platform/administrators</edit-permission> -<portlet-application> -<portlet> -<application-ref>exoadmin</application-ref> -<portlet-ref>PortalNavigationPortlet</portlet-ref> -</portlet> -<title>Portal Navigation</title> -<access-permissions>Everyone</access-permissions> -<show-info-bar>false</show-info-bar> -</portlet-application> -</page> -<page> -<name>register</name> -<title>Register</title> -<access-permissions>*:/platform/guests</access-permissions> -<edit-permission>*:/platform/administrators</edit-permission> -<portlet-application> -<portlet> -<application-ref>exoadmin</application-ref> -<portlet-ref>RegisterPortlet</portlet-ref> -</portlet> -<title>Register Account</title> -<access-permissions>*:/platform/guests</access-permissions> -<show-info-bar>false</show-info-bar> -</portlet-application> -</page> -<page> -<name>sitemap</name> -<title>Site Map</title> -<access-permissions>Everyone</access-permissions> -<edit-permission>*:/platform/administrators</edit-permission> -<portlet-application> -<portlet> -<application-ref>web</application-ref> -<portlet-ref>SiteMapPortlet</portlet-ref> -</portlet> -<title>SiteMap</title> -<access-permissions>Everyone</access-permissions> -<show-info-bar>false</show-info-bar> -</portlet-application> -</page> -</page-set> --> + </listitem> </varlistentry> </variablelist> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -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>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>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename> file. </para> <para> It defines eight permissions types: @@ -81,37 +81,7 @@ </variablelist> <programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_DefaultPortalPermissionConfiguration/default145.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="XML" role="XML"><![CDATA[<component> -<key>org.exoplatform.portal.config.UserACL</key> -<type>org.exoplatform.portal.config.UserACL</type> -<init-params> -<value-param> -<name>super.user</name> -<description>administrator</description> -<value>root</value> -</value-param> -<value-param> -<name>portal.creator.groups</name> -<description>groups with membership type have permission to manage portal</description> -<value>*:/platform/administrators,*:/organization/management/executive-board</value> -</value-param> -<value-param> -<name>navigation.creator.membership.type</name> -<description>specific membership type have full permission with group navigation</description> -<value>manager</value> -</value-param> -<value-param> -<name>guests.group</name> -<description>guests group</description> -<value>/platform/guests</value> -</value-param> -<value-param> -<name>access.control.workspace</name> -<description>groups with memberships that have the right to access the User Control Workspace</description> -<value>*:/platform/administrators,*:/organization/management/executive-board</value> -</value-param> -</init-params> -</component>]]></programlisting> --> + </section> @@ -122,27 +92,7 @@ </para> <programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_DefaultPortalPermissionConfiguration/default146.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="XML" role="XML"><![CDATA[<external-component-plugins> -<target-component>org.exoplatform.portal.config.UserACL</target-component> -<component-plugin> -<name>addPortalACLPlugin</name> -<set-method>addPortalACLPlugin</set-method> -<type>org.exoplatform.portal.config.PortalACLPlugin</type> -<description>setting some permission for portal</description> -<init-params> -<values-param> -<name>access.control.workspace.roles</name> -<value>*:/platform/administrators</value> -<value>*:/organization/management/executive-board</value> -</values-param> -<values-param> -<name>portal.creation.roles</name> -<value>*:/platform/administrators</value> -<value>*:/organization/management/executive-board</value> -</values-param> -</init-params> -</component-plugin> -</external-component-plugins>]]></programlisting> --> + </section> </chapter> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -31,7 +31,7 @@ <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> - Inside those file are typical <literal>key=value</literal> Java EE properties. For example; in the <literal>French</literal> file: + 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> @@ -47,7 +47,7 @@ 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 te be ASCII encoded, while the XML file can define its encoding. As a result it&#39;s easier for a human being to read a translation in XML instead of having to decode and encode the property file. + Property files have to be ISO 8859-1 encoded, while the XML file can define its encoding. As a result it&#39;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" /> @@ -95,7 +95,7 @@ </callout> <callout arearefs="area-Reference_Guide-i18n.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>. + <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-i18n.locales.configuration.description"> @@ -204,14 +204,14 @@ <section id="sect-Reference_Guide-Portlets-Standard_Portlet_Resource_Keys"> <title>Standard Portlet Resource Keys</title> <para> - The portlet specifications 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. + 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 enterpise ready: https://jira.jboss.org/browse/GTNPORTAL-1482 + <!-- 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 - PLEASE REVIEW</title> Added: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml (rev 0) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -0,0 +1,297 @@ +<?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; +]> +<chapter id="chap-Reference_Guide-Localization_Configuration"> + <title>Localization Configuration</title> + <section id="sect-Reference_Guide-Portal_Development-Pluggable_Locale_Policy"> + <title>Pluggable Locale Policy</title> + <para> + Every request processed by every portlet is invoked within a context of the current <literal>Locale</literal>. + </para> + <para> + The current <literal>Locale</literal> can be retrieved by calling the <literal>getLocale()</literal> method of <literal>javax.portlet.PortletRequest</literal> interface. + </para> + <para> + The exact algorithm for determining the current <literal>Locale</literal> is not specified by Portlet Specification. Portlet containers implement this the way they deem most appropriate. + </para> + <para> + In &PRODUCT;, each portal instance has a default language which can be used to present content for new users. Another option is to use each user’s browser language preference, provided it matches one of the available localizations that &PRODUCT; supports, and only fallback to the portal's default language if no match is found. + </para> + <para> + Every user, while visiting a portal, has an option to change the language of the user interface by using a Language chooser. The choice can be remembered for the duration of the session, or it can be remembered for a longer period using a browser cookie, or, for registered and logged-in users, it can be saved into the user’s profile. + </para> + <para> + As there is more than one way to determine the <literal>Locale</literal> to be used for displaying a portal page, the mechanism for determining the current <literal>Locale</literal> of the request is pluggable in &PRODUCT;, and the exact algorithm can be customized. + </para> + + <section> + <title>LocalePolicy API</title> + + <para> + Customization is achieved by using LocalePolicy API, which is a simple API consisting of one interface, and one class: + </para> + <itemizedlist> + <listitem> + <para><literal>org.exoplatform.services.resources.LocalePolicy</literal> interface</para> + </listitem> + <listitem> + <para><literal>org.exoplatform.services.resources.LocaleContextInfo</literal> class</para> + </listitem> + </itemizedlist> + + <para> + The <literal>LocalePolicy</literal> interface defines a single method that is invoked on the installed <literal>LocalePolicy</literal> service implementation: + </para> + +<programlisting language="Java" role="Java"><![CDATA[public interface LocalePolicy + { + public Locale determineLocale(LocaleContextInfo localeContext); + }]]> +</programlisting> + <para> + The <literal>Locale</literal> returned by determineLocale() method is the <literal>Locale</literal> that will be returned to portlets when they call <literal>javax.portlet.PortletRequest.getLocale()</literal> method. + </para> + <para> + 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>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</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. + </para> + <para> + All these different sources of <literal>Locale</literal> configuration or preference are used as input to <literal>LocalePolicy</literal> implementation that decides which <literal>Locale</literal> should be used. + </para> + </section> + + <section id="sect-Reference_Guide-Portal_Development-Default_LocalePolicy"> + <title>Default <literal>LocalePolicy</literal></title> + <para> + By default, <literal>org.exoplatform.portal.application.localization.DefaultLocalePolicyService</literal>, an implementation + of <literal>LocalePolicy</literal>, is installed to provide the default behaviour. + This, however, can easily be extended and overriden. A completely new implementation can also be written from scratch. + </para> + <para> + <literal>DefaultLocalePolicyService</literal> treats logged-in users slightly differently than anonymous users. + Logged-in users have a profile that can contain language preference, while anonymous users do not. + </para> + <para> + Here is an algorithm used for anonymous users. + </para> + <procedure id="proc-Reference_Guide-Portal_Development-Default_LocalePolicy-anonymous_users"> + <title>An algorithm for anonymous users</title> + <step> + <para> + Iterate over <literal>LocaleContextInfo</literal> properties in the following order: + </para> + <itemizedlist> + <listitem> + <para><literal>cookieLocales</literal></para> + </listitem> + <listitem> + <para><literal>sessionLocale</literal></para> + </listitem> + <listitem> + <para><literal>browserLocales</literal></para> + </listitem> + <listitem> + <para><literal>portalLocale</literal></para> + </listitem> + </itemizedlist> + </step> + <step> + <para> + Get each property's value. If it's a collection, get the first value. + </para> + </step> + <step> + <para> + If value is one of the supported locales return it as a result. + </para> + </step> + <step> + <para> + If the value is not in the supported locales set, try to remove country information and check if a language matching locale is in the list of supported locales. If so, return it as a result. + </para> + </step> + <step> + <para> + Otherwise, continue with the next property. + </para> + </step> + </procedure> + <para> + If no supported locale is found the return locale eventually defaults to <literal>portalLocale</literal>. + </para> + <para> + The algorithm for logged-in users is virtually the same except that the first <literal>Locale</literal> + source checked is user's profile.</para> + <procedure id="proc-Reference_Guide-Portal_Development-Default_LocalePolicy-logged-in_users"> + <title>An algorithm for logged-in users</title> + <step> + <para> + Iterate over <literal>LocaleContextInfo</literal> properties in the following order: + </para> + <itemizedlist> + <listitem> + <para><literal>userProfile</literal></para> + </listitem> + <listitem> + <para><literal>cookieLocales</literal></para> + </listitem> + <listitem> + <para><literal>sessionLocale</literal></para> + </listitem> + <listitem> + <para><literal>browserLocales</literal></para> + </listitem> + <listitem> + <para><literal>portalLocale</literal></para> + </listitem> + </itemizedlist> + </step> + <step> + <para> + Perform the rest of the steps in <xref linkend="proc-Reference_Guide-Portal_Development-Default_LocalePolicy-anonymous_users"/>. + </para> + </step> + </procedure> + </section> + + <section id="sect-Reference_Guide-Portal_Development-Custom_LocalePolicy"> + <title>Custom <literal>LocalePolicy</literal></title> + <para> + The easiest way to customize the <literal>LocalePolicy</literal> is to extend <literal>DefaultLocalePolicyService</literal>. A study of the source code is required. JavaDocs provide thorough information on this. + </para> + <para> + Most customizations will involve simply overriding one or more of its protected methods. + </para> + <para> + An example of a customization is an already provided <literal>NoBrowserLocalePolicyService</literal>. By overriding just one method, it skips any use of browser language preference. + </para> +<programlisting language="Java" role="Java"><![CDATA[public class NoBrowserLocalePolicyService extends DefaultLocalePolicyService + { + /** + * Override super method with no-op. + * + * @param context locale context info available to implementations in order to determine appropriate Locale + * @return null + */ + @Override + protected Locale getLocaleConfigFromBrowser(LocaleContextInfo context) + { + return null; + } + }]]> +</programlisting> + </section> + + <section id="sect-Reference_Guide-Portal_Development-LocalePolicy_Configuration"> + <title>LocalePolicy Configuration</title> + + <para> + The <literal>LocalePolicy</literal> framework is enabled for portlets by configuring <literal>LocalizationLifecycle</literal> class in portal's webui configuration file: <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/webui-configuration.xml</filename>: + </para> + +<programlisting language="XML" role="XML"><![CDATA[<application-lifecycle-listeners> + ... + <listener>org.exoplatform.portal.application.localization.LocalizationLifecycle</listener> +</application-lifecycle-listeners>]]> +</programlisting> + + <para> + The default <literal>LocalePolicy</literal> implementation is installed as GateIn Kernel portal service via <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/lib/exo.portal.webui.portal-VERSION.jar/conf/portal/configuration.xml</filename>. + </para> + <para> + The following excerpt is responsible for installing the service: + </para> +<programlisting language="XML" role="XML"><![CDATA[<component> + <key>org.exoplatform.services.resources.LocalePolicy</key> + <type>org.exoplatform.portal.application.localization.DefaultLocalePolicyService</type> +</component>]]> +</programlisting> + <para> + Besides implementing <literal>LocalePolicy</literal>, the service class also needs to implement <literal>org.picocontainer.Startable</literal> interface in order to get installed. + </para> + <para> + This configuration file should not be changed. The configuration in it can be overridden by placing it into portal's .war file: + <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/configuration.xml</filename> (usually as another file included into this one). + </para> + </section> + + <section id="sect-Reference_Guide-Portal_Development-non-bridged_sync"> + <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 'bridged'. Any resources that are accessed directly, bypassing portal filters and servlets, + are referred to as 'non-bridged'. + </para> + <para> + Non-bridged servlets, and .jsps have no access to <literal>PortalRequest</literal>. They don'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'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. + </para> + <para> + This problem is addressed by <literal>LocalizationFilter</literal>. This is a filter that changes the behavior + of <literal>ServletRequest.getLocale()</literal> method so that it behaves the same way as <literal>PortletRequest.getLocale()</literal>. + </para> + <para> + 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's web.xml file: <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. + </para> +<programlisting language="XML" role="XML"><![CDATA[<filter> + <filter-name>LocalizationFilter</filter-name> + <filter-class>org.exoplatform.portal.application.localization.LocalizationFilter</filter-class> +</filter> + +... + +<filter-mapping> + <filter-name>LocalizationFilter</filter-name> + <url-pattern>/*</url-pattern> + <dispatcher>INCLUDE</dispatcher> + <dispatcher>FORWARD</dispatcher> + <dispatcher>REQUEST</dispatcher> + <dispatcher>ERROR</dispatcher> +</filter-mapping>]]> +</programlisting> + <para> + There is a minor limitation with this mechanism in that it is unable to determine the current portal,and consequently, its default language. As a result the portalLocale defaults to <literal>English</literal>, but can be configured to something else by using the filter's <literal>PortalLocale</literal> init param. For example: + </para> +<programlisting language="XML" role="XML"><![CDATA[<filter> + <filter-name>LocalizationFilter</filter-name> + <filter-class>org.exoplatform.portal.application.localization.LocalizationFilter</filter-class> + <init-param> + <param-name>PortalLocale</param-name> + <param-value>fr_FR</param-value> + </init-param> +</filter> ]]> +</programlisting> + <para> + By default, <literal>LocalizationFilter</literal> is applied very broadly to cover all the resources automatically. + </para> + <para> + &PRODUCT; uses some non-bridged .jsps that require <literal>LocalizationFilter</literal>, so narrowing the mapping to *.jsp is enough for &PRODUCT; to function correctly. + </para> + <para> + Additionally deployed portlets, and portal applications, however, may require broader mapping to cover their non-bridged resources. + </para> + <para> + Narrowing the mapping might improve performance. This is something to consider, when optimizing for speed. + </para> + </section> + </section> +</chapter> \ No newline at end of file Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -5,32 +5,32 @@ ]> <chapter id="chap-Reference_Guide-Right_To_Left_RTL_Framework"> <title>Right To Left (RTL) Framework</title> + <note> + <title>DOC REVIEW:</title> + <para> + Some information has been removed from this section based on QE feedback. Please review to ensure there is no impact to technical accuracy. + </para> +</note> <para> The text orientation depends on the current locale setting. The orientation is a Java 5 enum that provides a set of functionalities: </para> <programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_RTLFramework/default172.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting language="Java" role="JAVA"><![CDATA[ LT, // Western Europe -RT, // Middle East (Arabic, Hebrew) -TL, // Japanese, Chinese, Korean -TR; // Mongolian -public boolean isLT() { ... } -public boolean isRT() { ... } -public boolean isTL() { ... } -public boolean isTR() { ... }]]></programlisting> --> - <para> + + <!-- DOC NOTE: Commented based on feedback from Marek Posolda that section seemed to have been included without previous explanatory context. + <para> The object defining the orientation for the current request is the <literal>UIPortalApplication</literal>. However it should be accessed at runtime using the <literal>RequestContext</literal> that delegates to the <literal>UIPortalApplication</literal>. </para> <para> In the case of a <literal>PortalRequestContext</literal> it is a direct delegate as the <literal>PortalRequestContext</literal> has a reference to the current <literal>UIPortalApplication</literal>. </para> <para> - In the case of a different context such as the <literal>PortletRequestContext</literal>, it delegates to the parent context given the fact that the root <literal>RequestContext</literal> is always a <literal>PortalRequestContext</literal>. - </para> + In the case of a different context, it delegates to the parent context given the fact that the root <literal>RequestContext</literal> is always a <literal>PortalRequestContext</literal>. + </para>--> <section id="sect-Reference_Guide-Right_To_Left_RTL_Framework-Groovy_templates"> <title>Groovy templates</title> <para> - Orientation is defined by implicit variables in the groovy binding context: + Orientation is defined by implicit variables passed into the groovy binding context: </para> <variablelist> <varlistentry> @@ -72,85 +72,56 @@ <section id="sect-Reference_Guide-Right_To_Left_RTL_Framework-Stylesheet"> <title>Stylesheet</title> <para> - The skin service handles stylesheet rewriting to accommodate the orientation. It works by appending -lt or -rt to the stylesheet name. + The skin service handles stylesheet rewriting to accommodate the orientation. + </para> + <para> + It works by appending -lt or -rt to the stylesheet name. </para> <para> - For instance: <filename>/web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet-rt.css</filename> will return the same stylesheet as <filename>/web/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>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet-rt.css</filename> will return the same stylesheet as <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</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. </para> - <formalpara id="form-Reference_Guide-Stylesheet-Example_1"> - <title>Example 1</title> - <para> - In the example we need to use the orientation to modify the float attribute that will make the horizontal tabs either float on left or on right: - </para> - </formalpara> - + <para> + In the example below we need to use the orientation to modify the float attribute that will make the horizontal tabs either float on left or on right: + </para> + <example> + <title>Example 1</title> <programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_RTLFramework/default173.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting> -float: left; /* orientation=lt */ -float: right; /* orientation=rt */ -font-weight: bold; -text-align: center; -white-space: nowrap; -</programlisting> --> + </example> <para> The LT produced output will be: </para> <programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_RTLFramework/default174.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting> -float: left; /* orientation=lt */ -font-weight: bold; -text-align: center; -white-space: nowrap; -</programlisting> --> + <para> The RT produced output will be: </para> <programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_RTLFramework/default175.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting> -float: right; /* orientation=rt */ -font-weight: bold; -text-align: center; -white-space: nowrap; -</programlisting> --> - <formalpara id="form-Reference_Guide-Stylesheet-Example_2"> - <title>Example 2</title> - <para> - In this example we need to modify the padding according to the orientation: - </para> - </formalpara> - + + <para> + In this example we need to modify the padding according to the orientation: + </para> + <example> + <title>Example 2</title> <programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_RTLFramework/default176.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting> -color: white; -line-height: 24px; -padding: 0px 5px 0px 0px; /* orientation=lt */ -padding: 0px 0px 0px 5px; /* &gt;orientation=rt */ -</programlisting> --> + </example> + <para> The LT produced output will be: </para> <programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_RTLFramework/default177.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting> -color: white; -line-height: 24px; -padding: 0px 5px 0px 0px; /* orientation=lt */ -</programlisting> --> + <para> The RT produced output will be: </para> <programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_RTLFramework/default178.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting> -color: white; -line-height: 24px; -padding: 0px 0px 0px 5px; /* orientation=rt */ -</programlisting> --> + </section> @@ -163,7 +134,8 @@ 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>/GateInResources/skin/DefaultSkin/webui/component/UITabSystem/UITabs/background/NormalTabStyle-rt.gif</filename> returns a mirror of the image <filename>/GateInResources/skin/DefaultSkin/webui/component/UITabSystem/UITabs/background/NormalTabStyle.gif</filename>. + For instance: requesting the image <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</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>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/01eXoResources.war/skin/DefaultSkin/webui/component/UITabSystem/UITabs/background/NormalTabStyle.gif</filename>. </para> <note> <para> @@ -175,13 +147,7 @@ </para> <programlisting language="Java" role="Java"><xi:include href="../../extras/PortalDevelopment_RTLFramework/default179.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- <programlisting> -line-height: 24px; -background: url('background/NavigationTab.gif') no-repeat right top; /* orientation=lt */ -background: url('background/NavigationTab-rt.gif') no-repeat left top; /* orientation=rt */ -padding-right: 2px; /* orientation=lt */ -padding-left: 2px; /* orientation=rt */ -</programlisting> --> + </section> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortalDevelopment.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -11,8 +11,11 @@ <xi:include href="PortalDevelopment/DefaultPortalPermissionConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="PortalDevelopment/DefaultPortalNavigationConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="PortalDevelopment/InternationalizationConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="PortalDevelopment/LocalizationConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!--DOC NOTE: LocalizationConfiguration.xml added to satisfy JBEPP-685/GTNPORTAL-1694 --> <xi:include href="PortalDevelopment/RTLFramework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="PortalDevelopment/XMLResourceBundles.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="PortalDevelopment/JavascriptInterApplicationCommunication.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- <xi:include href="PortalDevelopment/JavascriptConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> File has not been edited. Noted for later release --> + <!--<xi:include href="PortalDevelopment/JavascriptConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--> + <!-- DOC NOTE: JavaScript Configuration section removed as per instruction from Thomas Heute--> </part> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -87,9 +87,7 @@ </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> - <!-- <programlisting language="XML" role="XML"><![CDATA[ -<security:portal-identity authenticate-method="#{authenticator.authenticate}"/> -]]></programlisting> --> + </section> @@ -100,12 +98,7 @@ </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> - <!-- <programlisting language="XML" role="XML"><![CDATA[ -<context-param> -<param-name>org.jboss.portletbridge.WRAP_SCRIPTS</param-name> -<param-value>true</param-value> -</context-param> -]]></programlisting> --> + </section> </section> @@ -117,7 +110,7 @@ The embedded version in the &PRODUCT; 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-5.0/portletbridge</filename> </para> <para> - You can run a provided archetype (See <xref linkend="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes" />) and deploy the generated <literal>war</literal> in a few easy steps. + You can run a provided archetype (See <xref linkend="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes" />) and deploy the generated <literal>war</literal> or <literal>ear</literal> in a few easy steps. </para> </section> @@ -125,7 +118,8 @@ <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. + 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"> @@ -151,14 +145,7 @@ <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> - <!-- <programlisting>mvn archetype:generate --DarchetypeGroupId=org.jboss.portletbridge.archetypes --DarchetypeArtifactId=1.2-basic --DarchetypeVersion=2.0.0.FINAL --DgroupId=org.whatever.project --DartifactId=myprojectname --DarchetypeRepository=https://repository.jboss.org/nexus/content/groups/public/ -</programlisting> --> + </entry> </row> <row class="table-even" style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;"> @@ -168,14 +155,7 @@ <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> - <!-- <programlisting>mvn archetype:generate --DarchetypeGroupId=org.jboss.portletbridge.archetypes --DarchetypeArtifactId=richfaces-basic --DarchetypeVersion=2.0.0.FINAL --DgroupId=org.whatever.project --DartifactId=myprojectname --DarchetypeRepository=https://repository.jboss.org/nexus/content/groups/public/ -</programlisting> --> + </entry> </row> <row class="table-odd" style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;"> @@ -185,20 +165,12 @@ <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> - <!-- <programlisting>mvn archetype:generate --DarchetypeGroupId=org.jboss.portletbridge.archetypes --DarchetypeArtifactId=seam-basic --DarchetypeVersion=2.0.0.FINAL --DgroupId=org.whatever.project --DartifactId=seamproject --DarchetypeRepository=https://repository.jboss.org/nexus/content/groups/public/ -</programlisting> --> + </entry> </row> </tbody> </tgroup> </table> - </para> </section> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -18,16 +18,6 @@ </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> - <!-- <programlisting language="XML" role="XML"><![CDATA[ -<application> -<application-extension> -<bridge:excluded-attributes> -<bridge:excluded-attribute>foo.bar</bridge:excluded-attribute> -<bridge:excluded-attribute>foo.baz.*</bridge:excluded-attribute> -</bridge:excluded-attributes> -</application-extension> -</application> -]]></programlisting> --> </section> @@ -44,15 +34,6 @@ </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> - <!-- <programlisting language="XML" role="XML"><![CDATA[ -<navigation-rule> -<from-view-id>/register.jspx</from-view-id> -<navigation-case> -<from-outcome>edit</from-outcome> -<to-view-id>/edit.jspx?javax.portlet.faces.PortletMode=edit</to-view-id> -</navigation-case> -</navigation-rule> -]]></programlisting> --> </section> @@ -72,15 +53,7 @@ </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> - <!-- <programlisting language="XML" role="XML"><![CDATA[ -<navigation-rule> -<from-view-id>/edit.jspx*</from-view-id> -<navigation-case> -<from-outcome>view</from-outcome> -<to-view-id>#{sessionScope['javax.portlet.faces.viewIdHistory.view']}</to-view-id> -</navigation-case> -</navigation-rule> -]]></programlisting> --> + <section id="sect-Reference_Guide-Navigating_to_a_modes_last_viewId-Note_to_Portlet_Developers"> <title>Note to Portlet Developers</title> <para> @@ -123,12 +96,7 @@ </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> - <!-- <programlisting language="XML" role="XML"><![CDATA[ -<init-param> -<name>javax.portlet.faces.extension.resetModeViewId</name> -<value>true</value> -</init-param> -]]></programlisting> --> + </section> @@ -150,16 +118,7 @@ </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> - <!-- <programlisting language="XML" role="XML"><![CDATA[ -<error-page> -<exception-type>javax.servlet.ServletException</exception-type> -<location>/faces/error.xhtml</location> -</error-page> -<error-page> -<exception-type>javax.faces.application.ViewExpiredException</exception-type> -<location>/faces/error.xhtml</location> -</error-page> -]]></programlisting> --> + </section> @@ -170,31 +129,13 @@ </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> - <!-- <programlisting language="XML" role="XML"><![CDATA[ -<script type="text/javascript"> -A4J.AJAX.onError = function(req,status,message){ -window.alert("Custom onError handler "+message); -} -A4J.AJAX.onExpired = function(loc,expiredMsg){ -if(window.confirm("Custom onExpired handler "+expiredMsg+" for a location: "+loc)){ -return loc; -} else { -return false; -} -} -</script> -]]></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> - <!-- <programlisting language="XML" role="XML"><![CDATA[ -<context-param> -<param-name>org.ajax4jsf.handleViewExpiredOnClient</param-name> -<param-value>true</param-value> -</context-param> -]]></programlisting> --> + <para> Read more about these settings here <ulink url="http://docs.jboss.org/richfaces/3.3.3.BETA1/en/devguide/html/Ar... Errors and Session Expiration Handling</ulink> </para> @@ -230,13 +171,11 @@ <programlisting language="Java" role=&quot;JAVA&quot;&gt;(a)PortletScope(PortletScope.ScopeType.APPLICATION_SCOPE) </programlisting> <para> - Then you would pull the statefull object from the session: + 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> - <!-- <programlisting language="Java" role="JAVA"><![CDATA[ -YourSessionClass yourSessionClass = (YourSessionClass)getRenderRequest().getAttribute("javax.portlet.p./default/seamproject/seamprojectPortletWindow?textHolder"); -]]></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> @@ -250,16 +189,7 @@ </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> - <!-- <programlisting language="Java" role="JAVA"><![CDATA[ -Object objSession = FacesContext.getCurrentInstance().getExternalContext().getSession(false); -try -{ -if (objSession instanceof PortletSession) -{ -PortletSession portalSession = (PortletSession)objSession; -portalSession.setAttribute("your parameter name","parameter value",PortletSession.APPLICATION_SCOPE); -... -]]></programlisting> --> + <para> Then, in your JSP or Facelets page, you can use: </para> @@ -280,35 +210,25 @@ </section> - <section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Linking_to_PortletJSF_Pages_Using_houtputink"> - <title>Linking to Portlet/JSF Pages Using h:outputink</title> + <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> - <!-- <programlisting language="Java" role="JAVA"><![CDATA[ -<h:outputLink value="#{facesContext.externalContext.requestContextPath}/home.xhtml"> -<f:param name="javax.portlet.faces.ViewLink" value="true"/> -navigate to the test page -</h:outputLink> -]]></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 (that is, jboss.org) you can use the following parameter. + 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> - <!-- <programlisting language="Java" role="JAVA"><![CDATA[ -<h:commandLink actionListener="#{yourBean.yourListenr}"> -<f:param name="javax.portlet.faces.DirectLink" value="true"/> -navigate to the test page -</h:commandLink> -]]></programlisting> --> + <para> Then in your backing bean, you must call a <parameter>redirect()</parameter>. </para> @@ -325,33 +245,15 @@ </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> - <!-- <programlisting language="XML" role="XML"><![CDATA[ <h:form> -<h:inputText id="pref" required="true" value="#{mutablePortletPreferencesValues['userName'].value}" /> -<h:commandButton actionListener="#{myBean.savePref}" value="Save Preferences" /> -</h:form> -]]></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> - <!-- <programlisting language="Java" role="JAVA"><![CDATA[ Object request = FacesContext.getCurrentInstance().getExternalContext().getRequest(); -PortletRequest portletRequest = (PortletRequest)request; -if (request instanceof PortletRequest) { -try { -PortletPreferences portletPreferences = portletRequest.getPreferences(); -portletPreferences.store(); -]]></programlisting> --> + </section> - - <!-- DO NOT UNCOMMENT!! EL variables --><!-- using sendRedirect --><!-- FacesContext.getCurrentInstance().getExternalContext().redirect("http://www.google.com"); --><!-- and adding the <f:param name="javax.portlet.faces.DirectLink" value="true"/> to the commandButton, all seems fine. --><!-- <section> -<title>Integrations with JBoss Tools IDE</title> -<para> -</para> -<programlisting role="XML"><![CDATA[ -]]></programlisting> -</section> --> </section> Modified: epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/WSRP.xml 2010-12-02 05:13:47 UTC (rev 5436) +++ epp/docs/branches/EPP_5_0_Branch/Reference_Guide/en-US/modules/WSRP.xml 2010-12-02 06:17:20 UTC (rev 5437) @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP"> - <title>Web Services for Remote Portlets (WSRP)</title> + <title>Web Services for Remote Portlets (WSRP) - Please Review</title> <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Introduction"> <title>Introduction</title> <para> @@ -14,7 +14,8 @@ 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 the proposals made to the committee. </para> <para> - Scenarios that motivate WSRP functionality include: + Scenarios that motivate WSRP functionality include: + </para> <itemizedlist> <listitem> <para> @@ -27,27 +28,23 @@ </para> </listitem> </itemizedlist> - </para> + <para> More information on WSRP can be found on the official <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp...;. We suggest reading the <ulink url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr... for a good, albeit technical, overview of WSRP. </para> - <!-- Doesn't seem to offer any more than the para above -<para> -The <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... is suggested reading for a comprehensive overview of WSRP. -</para> --> </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Level_of_support_in_PRODUCT"> - <title>Level of support in &PRODUCT;</title> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Level_of_Support"> + <title>Level of Support</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. Terms defined in that document will be used in this section. </para> <para> - &PRODUCT_NAME; provides a <emphasis>Simple</emphasis> level of support for the WSRP Producer, with the exception of out-of-band registration. In-band registration and persistent local state (which are defined at the <emphasis>Complex</emphasis> level) are supported. + &PRODUCT; provides a <emphasis>Simple</emphasis> level of support for the WSRP Producer, with the exception of out-of-band registration. In-band registration and persistent local state (which are defined at the <emphasis>Complex</emphasis> level) are supported. </para> <para> - &PRODUCT_NAME; provides a <emphasis>Medium</emphasis> level of support for the Consumer, excepting HTML markup (as &PRODUCT_NAME; itself doesn&#39;t handle other markup types). Explicit portlet cloning and the <literal>PortletManagement</literal> interface are supported. + &PRODUCT; provides a <emphasis>Medium</emphasis> level of support for the Consumer, excepting HTML markup (as &PRODUCT; itself does not handle other markup types). Explicit portlet cloning and the <literal>PortletManagement</literal> interface are supported. </para> <para> The WSRP component has Level 1 Producer and Consumer caching. Cookie handling is supported properly on the Consumer. The Producer requires cookie initialization (as this improves interoperabilty with some consumers). @@ -55,41 +52,57 @@ <para> &PRODUCT; does not support custom window states or modes, therefore neither does the WSRP component. It does, however, support CSS on both the Producer (although this is more a function of the portlets than an inherent Producer capability) and Consumer. </para> - <para> - While &PRODUCT; provides a complete implementation of WSRP 1.0, more interoperability testing (based on the <ulink url="http://www.oasis-open.org/committees/download.php/6018">... statements</ulink>) is planned for future releases. - </para> </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Deploying_PRODUCT_NAMEs_WSRP_services"> - <title>Deploying &PRODUCT_NAME;&#39;s WSRP services</title> - <para> - &PRODUCT_NAME; provides a complete support of WSRP 1.0 standard interfaces and offers both Consumer and Producer services. - </para> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Deploying_WSRP"> + <title>Deploying WSRP</title> <note> - <title>Assumptions</title> + <title>Notational Devices</title> <para> - The following list of support files assumes: + The following list of support files uses the following notational devices: </para> - <orderedlist> - <listitem> - <para> - That the directory &PRODUCT_NAME; has been installed into will be referred to as <replaceable>PORTAL_HOME</replaceable>. - </para> - </listitem> - <listitem> - <para> - That <replaceable>WSRP_VERSION</replaceable> is the version of the WSRP component in use (at the time of the writing, it was &WSRP_VERSION;). - </para> - </listitem> - <listitem> - <para> - That <replaceable>PORTAL_VERSION</replaceable> is the current &PRODUCT_NAME; version (at the time of the writing, it was &PORTAL_VERSION;). - </para> - </listitem> - </orderedlist> + <variablelist> + <title></title> + <varlistentry> + <term><replaceable>EPP_HOME</replaceable></term> + <listitem> + <para> + <replaceable>EPP_HOME</replaceable> refers to the directory that your instance of &PRODUCT; has been extracted/installed to. For example: <filename>/home/<replaceable>USERNAME</replaceable>/jboss-epp-<replaceable>&lt;VERSION&gt;</replaceable>/</filename> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>WSRP_PATH</replaceable></term> + <listitem> + <para> + The WSRP files referred to in this section are found in the <filename><replaceable>EPP_HOME</replaceable>/jboss-as/server/$CONFIG/deploy/gatein.ear</filename> directory. + </para> + <para> + For ease of reference this path will be represented by: <replaceable>WSRP_PATH</replaceable>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>WSRP_VERSION</replaceable></term> + <listitem> + <para> + <replaceable>WSRP_VERSION</replaceable> represents the version of the WSRP component in use. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>PORTAL_VERSION</replaceable></term> + <listitem> + <para> + <replaceable>PORTAL_VERSION</replaceable> represents the version of &PRODUCT; in use. + </para> + </listitem> + </varlistentry> + </variablelist> </note> - <variablelist id="vari-Reference_Guide-Deploying_PRODUCT_NAMEs_WSRP_services-WSRP_support_files"> + + <variablelist id="vari-Reference_Guide-Deploying_WSRP-WSRP_support_files"> <title>WSRP support files</title> <varlistentry> <term><replaceable>PORTAL_HOME</replaceable>/wsrp-admin-gui.war</term> @@ -131,6 +144,14 @@ </para> </listitem> </varlistentry> + <varlistentry> + <term><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-producer-lib-$WSRP_VERSION.jar</term> + <listitem> + <para> + This file contains the classes needed by the WSRP producer. + </para> + </listitem> + </varlistentry> <varlistentry> <term><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-wsrp1-ws-<replaceable>WSRP_VERSION</replaceable>.jar</term> <listitem> @@ -139,69 +160,68 @@ </para> </listitem> </varlistentry> - <!-- DOC TODO: Uncomment this entry for version 5.1.0. Check to see if WSRP1 entry is still relevant -<varlistentry> -<term><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-wsrp2-ws-<replaceable>WSRP_VERSION</replaceable>.jar</term> -<listitem> -<para> -This file contains the JAX-WS classes for WSRP version 2. -</para> -</listitem> -</varlistentry> --> + <varlistentry> + <term><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-wsrp2-ws-<replaceable>WSRP_VERSION</replaceable>.jar</term> + <listitem> + <para> + This file contains the JAX-WS classes for WSRP version 2. + </para> + </listitem> + </varlistentry> <varlistentry> <term><replaceable>PORTAL_HOME</replaceable>/lib/gatein.portal.component.wsrp-<replaceable>PORTAL_VERSION</replaceable>.jar</term> <listitem> <para> - This file contains the code to integrate the WSRP service into &PRODUCT_NAME;. + This file contains the code to integrate the WSRP service into &PRODUCT;. </para> </listitem> </varlistentry> </variablelist> <para> - If WSRP is not going to be used in &PRODUCT_NAME;, the <filename><replaceable>PORTAL_HOME</replaceable>/lib/gatein.portal.component.wsrp-<replaceable>PORTAL_VERSION</replaceable>.jar</filename> can be removed from &PRODUCT_NAME; distribution to deactivate WSRP support. + If WSRP is not going to be used in your &PRODUCT; instance, the <filename><replaceable>PORTAL_HOME</replaceable>/lib/gatein.portal.component.wsrp-<replaceable>PORTAL_VERSION</replaceable>.jar</filename> can be removed to deactivate WSRP support. </para> - <section id="sect-Reference_Guide-Deploying_PRODUCT_NAMEs_WSRP_services-Considerations_for_use_with_non_default_port_or_hostname"> - <title>Considerations for use with non-default port or hostname</title> + + <section id="sect-Reference_Guide-Deploying_WSRP-Non_default_Ports_or_Hostnames"> + <title>Non-default Ports or Hostnames</title> <para> - JBoss WS (the web service stack that &PRODUCT_NAME; uses) should update the port and host name used in WSDL. Refer to the JBoss WS <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... guide</ulink> for more information. + JBoss WS (the web service stack that &PRODUCT; uses) should update the port and host name used in WSDL. Refer to the JBoss WS <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... guide</ulink> for more information. </para> <para> - If the host name and port on which the server runs have been modified, the configuration for the Consumer used to consume &PRODUCT_NAME;&#39;s &#39;self&#39; Producer will need to be updated. Refer to <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME" /> to learn how to do this. + If the host name and port on which the server runs have been modified, the configuration for the Consumer used to consume &PRODUCT;'s "self" Producer will need to be updated. Refer to <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets" /> for directions on how to do this. </para> </section> - <section id="sect-Reference_Guide-Deploying_PRODUCT_NAMEs_WSRP_services-Considerations_to_use_WSRP_with_SSL"> - <title>Considerations to use WSRP with SSL</title> + <section id="sect-Reference_Guide-Deploying_WSRP-Using_WSRP_with_SSL"> + <title>Using WSRP with SSL</title> <para> It is possible to use WSRP over SSL for secure exchange of data. Refer to these <ulink url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu... for how to do this. </para> </section> - </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Making_a_portlet_remotable"> - <title>Making a portlet remotable</title> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Making_a_Portlet_Remotable"> + <title>Making a Portlet Remotable</title> <note> <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> </note> <para> - &PRODUCT_NAME; does <emphasis role="bold">NOT</emphasis>, by default, expose local portlets for consumption by remote WSRP consumers. + &PRODUCT; does <emphasis role="bold">not</emphasis>, by default, expose local portlets for consumption by remote WSRP consumers. </para> <para> - In order to make a portlet remotely available, it must be made &#34;remotable&#34; by marking it as such in the associated <filename>portlet.xml</filename>. + In order to make a portlet remotely available, it must be made "remotable" by marking it as such in the associated <filename>portlet.xml</filename>. </para> <para> - A specific <code>org.gatein.pc.remotable container-runtime-option</code> is used to accomplished this. Setting its value to <code>true</code> makes the portlet available for remote consumption, while setting its value to <code>false</code> will not publish it remotely. + A specific <code>org.gatein.pc.remotable container-runtime-option</code> is used to accomplish this. Setting its value to <code>true</code> makes the portlet available for remote consumption, while setting its value to <code>false</code> will not publish it remotely. </para> <para> As specifying the remotable status for a portlet is optional, nothing need be done if portlets do not need to be remotely available. </para> <para> - In the following example, the &#34;BasicPortlet&#34; portlet is specified as being remotable. + In the following example, the "BasicPortlet" portlet is specified as being remotable. </para> <programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default255.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> @@ -217,13 +237,13 @@ <programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default256.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - This example defines two portlets. As the <code>org.gatein.pc.remotable container-runtime-option</code> is set to <code>true</code> at the <code>portlet-app</code> level, all portlets defined in this particular portlet application are exposed remotely by &PRODUCT_NAME;&#39;s WSRP Producer. + This example defines two portlets. As the <code>org.gatein.pc.remotable container-runtime-option</code> is set to <code>true</code> at the <code>portlet-app</code> level, all portlets defined in this particular portlet application are exposed remotely by &PRODUCT;'s WSRP Producer. </para> <para> It is possible to override this 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. </para> <para> - In the example above, 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>. + In the example above, 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>. </para> <para> The <varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely exposed. @@ -236,29 +256,32 @@ </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_PRODUCT_NAMEs_WSRP_portlets_from_a_remote_Consumer"> - <title>Consuming &PRODUCT_NAME;&#39;s WSRP portlets from a remote Consumer</title> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_WSRP_portlets_from_a_remote_Consumer"> + <title>Consuming WSRP portlets from a remote Consumer</title> <para> - Configuration is extremely variable between different WSRP Consumers. Most, however, require a specification of the URL for the Producer&#39;s WSDL definition. If the &PRODUCT_NAME; Consumer is not being used, refer to the documentation for the Consumer that is in use for specific instructions. + Configuration is extremely variable between different WSRP Consumers. Most, however, require a specification of the URL for the Producer's WSDL definition. If the &PRODUCT; Consumer is not being used, refer to the documentation for the Consumer that is in use for specific instructions. </para> <para> - For instructions on how to specify this URL in &PRODUCT_NAME;, refer to <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME" />. + For instructions on how to specify this URL in &PRODUCT;, refer to <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets" />. </para> <para> - &PRODUCT_NAME;&#39;s Producer is automatically set up when a portal instance is deployed with the WSRP service. + &PRODUCT;'s Producer is automatically set up when a portal instance is deployed with the WSRP service. </para> <para> - The WSDL file can be accessed at <filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/MarkupService?wsdl</filename>. The default hostname is <literal>localhost</literal> and the default port is <literal>8080</literal>. + The WSDL file can be accessed at <filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/v1/MarkupService?wsdl</filename>. </para> + <para> + The default hostname is <literal>localhost</literal> and the default port is <literal>8080</literal>. + </para> </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME"> - <title>Consuming remote WSRP portlets in &PRODUCT_NAME;</title> - <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Overview"> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets"> + <title>Consuming Remote WSRP Portlets</title> + <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-Overview"> <title>Overview</title> <para> - To be able to consume WSRP portlets exposed by a remote producer, &PRODUCT_NAME;&#39;s WSRP consumer must be configured to access that remote producer. + To be able to consume WSRP portlets exposed by a remote producer, &PRODUCT;'s WSRP consumer must be configured to access that remote producer. </para> <para> Access to a remote producer can be configured using WSRP Producer descriptors. Alternatively, a portlet is provided to configure remote producers. @@ -267,22 +290,26 @@ 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> <para> - A default consumer named <literal>self</literal>, that consumes the portlets exposed by &PRODUCT_NAME;&#39;s producer, has been configured as a way to test the WSRP producer service and to check that portlets are correctly published via WSRP. + A default consumer named <literal>self</literal>, that consumes the portlets exposed by &PRODUCT;'s producer, has been configured as a way to test the WSRP producer service and to check that portlets are correctly published via WSRP. </para> </section> - <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Configuring_a_remote_producer"> - <title>Configuring a remote producer</title> + <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-Configuring_a_Remote_Producer"> + <title>Configuring a Remote Producer</title> <para> - Access to a remote producer needs to be defined so that portlets can be consumed within &PRODUCT_NAME;. This section will show how to configure access to <emphasis role="bold">Oracle</emphasis>&#39;s public WSRP producer. Firstly using the configuration portlet. Then how the same result can be accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet. + Access to a remote producer needs to be defined so that portlets can be consumed within &PRODUCT;. This section will show how to configure access to <emphasis role="bold">Oracle</emphasis>'s public WSRP producer. Firstly using the configuration portlet. Then how the same result can be accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet. </para> - <!-- Warning added as per notification from Chris Laprun --> <important> <title>Chunked Encoding</title> <para> - Some WSRP producers, such as Oracle, do not support chunked encoding. Using an Oracle WSRP producer will therefore produce an error. + Some WSRP producers, such as Oracle, do not support chunked encoding. If your producer does not support chunked encoding, it will not be able to properly connect to the producer. </para> + <para> + This will manifest itself with the following error: + </para> +<screen>Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] - Service Unavailable. +</screen> <para> A workaround for this issue involves editing the <parameter>chunksize</parameter> setting in the <filename>standard-jaxws-client-config.xml</filename> file. </para> @@ -290,148 +317,158 @@ Refer to <ulink type="http" url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis... for more information. </para> </important> - <section id="sect-Reference_Guide-Configuring_a_remote_producer-Using_the_configuration_portlet"> - <title>Using the configuration portlet</title> + <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-The_Configuration_Portlet"> + <title>The Configuration Portlet</title> <para> - &PRODUCT_NAME; provides a portlet to configure access (among other functions) to remote WSRP Producers grahically. This portlet isn&#39;t installed by default, so it must be installed using the Application Registry. - </para> - <procedure> - <step> - <para> - Log into the portal as an administrator and go to the Application Registry (Click <ulink url="http://localhost:8080/portal/private/classic/administration/registry">http://localhost:8080/portal/private/classic/administration/registry</ulink> if using the default installation). - </para> - </step> - <step> - <para> - Add the WSRP Configuration portlet to the Administration category. If the Import Applications functionality is used, the WSRP Configuration portlet will be automatically added to the Administration category. - </para> - </step> - </procedure> - - <para> - Once the portlet is added to a category, it can be added to a page and used. It is recommended that it be added to the same page as the Application Registry (as other operations relating to WSRP and adding portlets to categories are somewhat related). Add the WSRP Configuration portlet to the page using the standard procedure. - </para> - <para> - <emphasis role="bold">The WSRP Configuration portlet</emphasis>: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_init.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_init.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - <para> - This screen presents all the configured consumers associated with their status and possible actions on them. - </para> - <para> - A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. - </para> - <para> - Note also that a Consumer can be marked as requiring <emphasis>refresh</emphasis>, which means that the information held about it might not be up to date. Refreshing it from the remote Producer will update this information. - </para> - <para> - This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information. - </para> - <procedure> - <step> - <para> - Type &#34;<literal> oracle</literal>&#34; into the &#34;<emphasis role="bold">Create a consumer named:</emphasis>&#34; field. - </para> - </step> - <step> - <para> - Click on &#34;<emphasis role="bold">Create consumer</emphasis>&#34; to create a new Consumer called <literal>oracle</literal>. - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_create.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_create.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - </step> - <step> - <para> - In the next form, set the cache expiration value to <parameter>300</parameter> seconds. - </para> - </step> - <step> - <para> - Leave the default timeout value for web services (WS) operations. - </para> - </step> - <step> - <para> - Enter the WSDL URL for the producer in the text field. - </para> - </step> - <step> - <para> - Press the &#34;Refresh &amp; Save&#34; button: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_wsdl.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_wsdl.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - </step> - </procedure> - - <para> - This will retrieve the service description associated with the Producer which WSRP interface is described by the WSDL file found at the URL entered. - </para> - <para> - In this case, querying the service description will suggest that the Producer requires registration but did not request any registration property: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_refresh.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_refresh.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - <para> - The Consumer for the <literal>oracle</literal> Producer should now be available as a portlet provider and be ready to be used. - </para> - <para> - Assuming that the producer required a value for an <literal>email</literal> registration property, &PRODUCT_NAME;&#39;s WSRP consumer will report that some information was missing: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_missing.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_missing.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - <note> - <title>Values</title> - <para> - As at this release there is no automated way to learn about which possible values (if any) are expected by the remote Producer. Possible values may be indicated in the registration property description but this is not always the case... Please refer to the specific Producer&#39;s documentation. - </para> - </note> - <para> - Entered an address for the registration property (&amp;#34;&lt;literal&gt;example(a)example.com&lt;/literal&gt;&amp;#34;) and press &#34;<emphasis role="bold">Save &amp; Refresh</emphasis>&#34; once more: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_end.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> + &PRODUCT; provides a graphical portlet to assist with configuring access to, and other facets of, remote WSRP Producers. + </para> + <para> + This portlet is not installed by default in &PRODUCT;. It must be installed using the Application Registry. + </para> + <procedure> + <title><emphasis role="bold">Installing the configuration portlet:</emphasis></title> + <step> + <para> + Log into the portal as an administrator and go to the Application Registry (Click <ulink url="http://localhost:8080/portal/private/classic/administration/registry">http://localhost:8080/portal/private/classic/administration/registry</ulink> if using the default installation). + </para> + </step> + <step> + <para> + Add the WSRP Configuration portlet to the Administration category. If the Import Applications functionality is used, the WSRP Configuration portlet will be automatically added to the Administration category. + </para> + </step> + <step> + <para> + Once the portlet is added to a category, it can be added to a page and used. It is recommended that it be added to the same page as the Application Registry (as other operations relating to WSRP and adding portlets to categories are somewhat related). Add the WSRP Configuration portlet to the page using the standard procedure. + </para> + </step> + </procedure> + + <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-The_Configuration_Portlet-Using_the_Configuration_Portlet"> + <title><emphasis role="bold">Using the Configuration portlet</emphasis></title> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_init.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" 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. + </para> + <para> + A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. + </para> + <para> + Note also that a Consumer can be marked as requiring <emphasis>refresh</emphasis>, which means that the information held about it might not be up to date. Refreshing it from the remote Producer will update this information. + </para> + <para> + This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information. + </para> + <para> + To create a new Consumer: + </para> + <procedure> + <title><emphasis role="bold">Creating a Consumer</emphasis></title> + <step> + <para> + Type "<literal> oracle</literal>" into the "<emphasis role="bold">Create a consumer named:</emphasis>" field. + </para> + </step> + <step> + <para> + Click on "<emphasis role="bold">Create consumer</emphasis>" to create a new Consumer called <literal>oracle</literal>. + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_create.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_create.png" format="PNG" /> + </imageobject> + </mediaobject> + </step> + <step> + <para> + In the next form, set the cache expiration value to <parameter>300</parameter> seconds. + </para> + </step> + <step> + <para> + Leave the default timeout value for web services (WS) operations. + </para> + </step> + <step> + <para> + Enter the WSDL URL for the producer in the text field. + </para> + </step> + <step> + <para> + Press the "Refresh &amp; Save" button: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_wsdl.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_wsdl.png" format="PNG" /> + </imageobject> + </mediaobject> + </step> + </procedure> + + <para> + This will retrieve the service description associated with the Producer which WSRP interface is described by the WSDL file found at the URL entered. + </para> + <para> + In this case, querying the service description will show that the Producer requires registration but did not request any registration property: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_refresh.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_refresh.png" format="PNG" /> + </imageobject> + </mediaobject> + <para> + The Consumer for the <literal>oracle</literal> Producer should now be available as a portlet provider and be ready to be used. + </para> + <para> + Assuming that the producer required a value for an <literal>email</literal> registration property, &PRODUCT;'s WSRP consumer will report that some information was missing: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_missing.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_missing.png" format="PNG" /> + </imageobject> + </mediaobject> + <note> + <title>Values</title> + <para> + As at this release there is no automated way to learn about which possible values (if any) are expected by the remote Producer. Possible values may be indicated in the registration property description but this is not always the case. Refer to the specific Producer's documentation. + </para> + </note> + <para> + Enter an address for the registration property (&quot;&lt;literal&gt;example(a)example.com&lt;/literal&gt;&quot;) and press "<emphasis role="bold">Save &amp; Refresh</emphasis>" once more: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_end.png" format="PNG" /> + </imageobject> + </mediaobject> + </section> </section> - <section id="sect-Reference_Guide-Configuring_a_remote_producer-Using_XML"> + <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-Using_XML"> <title>Using XML</title> <para> Although using the WSRP Configuration portlet to configure Consumers is recommended, the WSRP component provides an alternative way to configure consumers. @@ -442,7 +479,7 @@ <programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default257.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - The file as shown above specifies access to two producers: <literal>self</literal>, which consumes &PRODUCT_NAME;&#39;s own WSRP producer (albeit in a version that assumes that the producer requires a value for an <literal>email</literal> registration property), and <literal>oracle</literal>, which consumes Oracle&#39;s public producer, both in configurations as shown in the procedure above. + The file as shown above specifies access to two producers: <literal>self</literal>, which consumes &PRODUCT;'s own WSRP producer (albeit in a version that assumes that the producer requires a value for an <literal>email</literal> registration property), and <literal>oracle</literal>, which consumes Oracle's public producer, both in configurations as shown in the procedure above. </para> <note> <para> @@ -451,18 +488,17 @@ </note> </section> - - <section id="sect-Reference_Guide-Configuring_a_remote_producer-Configuring_access_to_a_remote_portlet"> - <title>Configuring access to a remote portlet</title> + <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-Adding_remote_portlets_to_categories"> + <title>Adding remote portlets to categories</title> <para> Clicking on the Portlet link in the Application Registry will now show the remote potlets in the <emphasis role="bold">REMOTE</emphasis> tab in the left column: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/remote_portlets.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/remote_portlets.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" /> </imageobject> </mediaobject> <para> @@ -480,15 +516,11 @@ </section> - - <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Configuring_access_to_remote_Producers_via_XML"> - <title>Configuring access to remote Producers via XML</title> + <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-Configuring_Access_to_Remote_Producers_via_XML"> + <title>Configuring Access to Remote Producers via XML</title> <para> - Although using the WSRP Configuration portlet to configure Consumers is recommended, the WSRP component provides an alternative way to configure consumers. + Again, configuring consumers via XML is done by editing <filename><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar/conf/wsrp-consumers-config.xml</filename>. </para> - <para> - This is done by editing the XML file located at <filename><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar/conf/wsrp-consumers-config.xml</filename>. - </para> <note> <title>XML Elements</title> <para> @@ -501,20 +533,20 @@ It is important to understand 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 the JCR (Java Content Repository). </para> <para> - Subsequent launches of the WSRP service will use the JCR-stored information for all producers that are already known to &PRODUCT_NAME;. More specifically, the <filename>wsrp-consumers-config.xml</filename> file is scanned for producer identifiers. Any identifier that is already known will be bypassed and the JCR information associated with this remote producer will be used. + Subsequent launches of the WSRP service will use the JCR-stored information for all producers that are already known to &PRODUCT;. More specifically, the <filename>wsrp-consumers-config.xml</filename> file is scanned for producer identifiers. Any identifier that is already known will be bypassed and the JCR information associated with this remote producer will be used. </para> <para> The information defined at the XML level is only processed for producer definition for which no information is already present in the JCR. </para> <para> - Therefore, to delete a Producer configuration, the associated information in the database must be deleted (this can be accomplished using the configuration portlet as shown in <xref linkend="sect-Reference_Guide-Configuring_a_remote_producer-Using_the_configuration_portlet" />). + Therefore, to delete a Producer configuration, the associated information in the database must be deleted (this can be accomplished using the configuration portlet as shown in <xref linkend="sect-Reference_Guide-Configuring_a_Remote_Producer-The_Configuration_Portlet" />). </para> <para> The associated information in <filename>wsrp-consumers-config.xml</filename> (if such information exists) must also be removed, otherwise the producer will be re-created the next time the WSRP is launched. </para> </note> - <section id="sect-Reference_Guide-Configuring_access_to_remote_Producers_via_XML-Required_configuration_information"> - <title>Required configuration information</title> + <section id="sect-Reference_Guide-Configuring_Access_to_Remote_Producers_via_XML-Required_Configuration_Information"> + <title>Required Configuration Information</title> <para> The following information needs to be provided to configure access to a remote Producer: </para> @@ -526,7 +558,7 @@ </listitem> <listitem> <para> - &PRODUCT_NAME; also needs to know about the remote Producer&#39;s endpoints to be able to connect to the remote web services and perform WSRP invocations. Use the <literal>&#60;endpoint-wsdl-url&#62;</literal> element to specify the URL for the WSDL description of the remote WSRP service. + &PRODUCT; also needs to know about the remote Producer's endpoints to be able to connect to the remote web services and perform WSRP invocations. Use the <literal>&#60;endpoint-wsdl-url&#62;</literal> element to specify the URL for the WSDL description of the remote WSRP service. </para> </listitem> </orderedlist> @@ -536,12 +568,12 @@ </section> - <section id="sect-Reference_Guide-Configuring_access_to_remote_Producers_via_XML-Optional_configuration"> - <title>Optional configuration</title> + <section id="sect-Reference_Guide-Configuring_Access_to_Remote_Producers_via_XML-Optional_Configuration"> + <title>Optional Configuration</title> <para> It is also possible to provide additional configuration, which, in some cases, might be important to establish a proper connection to the remote producer. </para> - <variablelist id="vari-Reference_Guide-Optional_configuration-Optional_Configurations"> + <variablelist id="vari-Reference_Guide-Optional_Configuration-Optional_Configurations"> <title>Optional Configurations</title> <varlistentry> <term>Caching</term> @@ -553,19 +585,24 @@ The rate at which the information is refreshed is defined by the <literal>expiration-cache</literal> attribute of the <literal>&#60;wsrp-producer&#62;</literal> element (in seconds). </para> <para> - For example; providing a value of 120 for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been accessed. If no value is provided, &PRODUCT_NAME; will always access the remote producer regardless of whether the remote information has changed or not. + For example; providing a value of <literal>120</literal> for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been accessed. If no value is provided, &PRODUCT; will always access the remote producer regardless of whether the remote information has changed or not. </para> <para> Since, in most instances, the information provided by the producer does not change often, use of this caching facility to minimize bandwidth usage is recommended. </para> - <para> - It is also possible to define a timeout after which WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, as it waits on a service that does not answer. - </para> - <para> - Use the <literal>ws-timeout</literal> attribute of the <literal>&#60;wsrp-producer&#62;</literal> element to specify how many milliseconds the WSRP service will wait for a response from the remote producer before timing out. - </para> </listitem> </varlistentry> + <varlistentry> + <term>WS Timeout</term> + <listitem> + <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, as it waits on a service that does not answer. + </para> + <para> + Use the <literal>ws-timeout</literal> attribute of the <literal>&#60;wsrp-producer&#62;</literal> element to specify how many milliseconds the WSRP service will wait for a response from the remote producer before timing out. + </para> + </listitem> + </varlistentry> <varlistentry> <term>Pre-registration information</term> <listitem> @@ -574,20 +611,20 @@ </para> <note> <para> - As at this release only simple String properties are supported and it is not possible to configure complex registration data. However, this should be sufficient for most cases. + Only simple String properties are supported. It is not possible to configure complex registration data. However, this should be sufficient for most cases. </para> </note> <para> This pre-registration configuration is done via the <literal>&#60;registration-data&#62;</literal> element. </para> <para> - If the remote producer does not require any registration properties, only an empty <literal>&#60;registration-data&#62;</literal> element need be provided, as &PRODUCT_NAME; can generate the mandatory information. + If the remote producer does not require any registration properties, only an empty <literal>&#60;registration-data&#62;</literal> element need be provided, as &PRODUCT; can generate the mandatory information. </para> <para> Values for the registration properties required by the remote producer can be provided via <literal>&#60;property&#62;</literal> elements. Refer to the example below for more details. </para> <para> - Additionally, the default consumer name automatically provided by &PRODUCT_NAME; can be overridden via the <literal>&#60;consumer-name&#62;</literal> element. When providing a consumer name, please remember that it should uniquely identify your consumer. + Additionally, the default consumer name automatically provided by &PRODUCT; can be overridden via the <literal>&#60;consumer-name&#62;</literal> element. When providing a consumer name, please remember that it should uniquely identify your consumer. </para> </listitem> </varlistentry> @@ -597,7 +634,7 @@ </section> - <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Examples"> + <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-Examples"> <title>Examples</title> <para> This is the configuration of the <literal>self</literal> producer as found in <filename>default-wsrp.xml</filename> with a cache expiring every five minutes and with a 30 second timeout for web service operations: @@ -614,23 +651,23 @@ </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consumers_maintenance"> - <title>Consumers maintenance</title> - <section id="sect-Reference_Guide-Consumers_maintenance-Modifying_a_currently_held_registration"> - <title>Modifying a currently held registration</title> - <section id="sect-Reference_Guide-Modifying_a_currently_held_registration-Registration_modification_for_service_upgrade"> - <title>Registration modification for service upgrade</title> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consumers_Maintenance"> + <title>Consumers Maintenance</title> + <section id="sect-Reference_Guide-Consumers_Maintenance-Modifying_a_Currently_Held_Registration"> + <title>Modifying a Currently Held Registration</title> + <section id="sect-Reference_Guide-Modifying_a_Currently_Held_Registration-Registration_Modification_for_Service_Upgrade"> + <title>Registration Modification for Service Upgrade</title> <para> - Producers often offer several levels of service depending on consumers&#39; 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. + Producers often offer several levels of service depending on consumers' subscription levels (for example). This is implemented at the WSRP level with the registration concept: producers can assert which level of service to provide to consumers based on the values of given registration properties. </para> <para> - There may also be cases where the registration information has changed and must be updated. 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. + There may also be cases where the registration information has changed and must be updated. For example, the producer required you to provide a valid email and the previous email address is not valid anymore and needs to be updated. </para> <para> Therefore at times it may be necessary to modify the registration that sets the service agreement between a consumer and a producer. </para> <para> - For example; the producer requiring an email that was configured in <xref linkend="sect-Reference_Guide-Configuring_a_remote_producer-Using_the_configuration_portlet" />. In that case the producer was requiring registration and required a value to be provided for the <literal>email</literal> property. + For example; the producer requiring an email that was configured in <xref linkend="sect-Reference_Guide-Configuring_a_Remote_Producer-The_Configuration_Portlet" />. In that case the producer was requiring registration and required a value to be provided for the <literal>email</literal> property. </para> <para> To update the email address that was provided, the remote producer must be informed that some registration data has been modified. @@ -645,36 +682,36 @@ </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_start.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/modify_reg_start.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png" format="PNG" /> </imageobject> </mediaobject> </step> <step> <para> - Click on &#34;<emphasis role="bold">Update properties</emphasis>&#34; to save the change. A &#34;<emphasis role="bold">Modify registration</emphasis>&#34; button should now appear to let you send this new data to the remote producer: + Click on "<emphasis role="bold">Update properties</emphasis>" to save the change. A "<emphasis role="bold">Modify registration</emphasis>" button should now appear to let you send this new data to the remote producer: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_modify.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/modify_reg_modify.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png" format="PNG" /> </imageobject> </mediaobject> </step> <step> <para> - Click on this new button and, if the updated registration details have been been accepted by the remote producer the following should appear: + Click on <emphasis role="bold">Modify registration</emphasis> and, if the updated registration details have been been accepted by the remote producer the following should appear: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_end.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/modify_reg_end.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png" format="PNG" /> </imageobject> </mediaobject> </step> @@ -682,10 +719,10 @@ </section> - <section id="sect-Reference_Guide-Modifying_a_currently_held_registration-Registration_modification_on_Producer_error"> - <title>Registration modification on Producer error</title> + <section id="sect-Reference_Guide-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error"> + <title>Registration Modification on Producer Error</title> <para> - Invoking operations on the producer may fail with an <exceptionname>OperationFailedFault</exceptionname> if the producer administrator has changed its requirement for registered consumers. &PRODUCT_NAME; will attempt to assist in these cases. + If a Producer administrator changes the requirements for registered consumers, invoking operations on the producer may fail with an <exceptionname>OperationFailedFault</exceptionname>. &PRODUCT; will attempt to assist in these cases. </para> <para> This section will discuss an example using the <literal>self</literal> producer. @@ -695,43 +732,44 @@ </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_self.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/config_self.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_self.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_self.png" format="PNG" /> </imageobject> </mediaobject> <para> If the administrator of the producer now requires an additional value to be provided for a <literal>name</literal> registration property operations with this producer will fail. </para> <para> - If a registration modification is required, go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing &#34;<emphasis role="bold">Refresh &amp; Save</emphasis>&#34;: + If a registration modification is required, go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing "<emphasis role="bold">Refresh &amp; Save</emphasis>": </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_self.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/modify_reg_self.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self.png" format="PNG" /> </imageobject> </mediaobject> <para> The configuration screen now shows the currently held registration information and the expected information from the producer. </para> <para> - Enter a value for the <literal>name</literal> property and then click on &#34;<emphasis role="bold">Modify registration</emphasis>&#34;. If the producer accepts the new registration data, the following screen will appear: + Enter a value for the <literal>name</literal> property and then click on "<emphasis role="bold">Modify registration</emphasis>". If the producer accepts the new registration data, the following screen will appear: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" /> </imageobject> </mediaobject> <note> + <title><emphasis role="bold">Exceptions</emphasis></title> <para> - As of WSRP 1, it can be difficult to ascertain what caused an <exceptionname>OperationFailedFault</exceptionname> as it is a generic exception returned by producers during a failed method invocation. + In WSRP 1, it can be difficult to ascertain what caused an <exceptionname>OperationFailedFault</exceptionname> as it is a generic exception returned by producers during a failed method invocation. </para> <para> An <exceptionname>OperationFailedFault</exceptionname> failure can be caused by several different reasons, one of them being a request to modify the registration data. @@ -739,26 +777,23 @@ <para> In these instances examining the log files may assist in gathering more information about the problem. </para> - <para> - WSRP 2 introduces an exception that is specific to a request to modify registrations which reduces the ambiguity that currently exists. - </para> </note> </section> </section> - <section id="sect-Reference_Guide-Consumers_maintenance-Consumer_operations"> - <title>Consumer operations</title> + <section id="sect-Reference_Guide-Consumers_Maintenance-Consumer_Operations"> + <title>Consumer Operations</title> <para> Several operations are available from the consumer list view of the WSRP configuration portlet: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/consumer_operations.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/consumer_operations.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/consumer_operations.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/consumer_operations.png" format="PNG" /> </imageobject> </mediaobject> <para> @@ -807,10 +842,9 @@ </varlistentry> </variablelist> </section> - - <section id="sect-Reference_Guide-Consumers_maintenance-Erasing_local_registration_data"> - <title>Erasing local registration data</title> + <section id="sect-Reference_Guide-Consumers_Maintenance-Erasing_Local_Registration_Data"> + <title>Erasing Local Registration Data</title> <para> In rare cases, it may be necessary to erase the local data without being able to de-register first. </para> @@ -818,17 +852,17 @@ This can occur when a consumer is registered with a producer that has been modified by its administrator to not require registration any longer. </para> <para> - In this unlikely scenario, local registration information can be erased from the consumer to allow it to resume interacting with the remote producer. + In this scenario, local registration information can be erased from the consumer to allow it to resume interacting with the remote producer. </para> <para> - To do this click on the &#34;<emphasis role="bold">Erase local registration</emphasis>&#34; button next to the registration context information on the consumer configuration screen: + To do this click on the "<emphasis role="bold">Erase local registration</emphasis>" button next to the registration context information on the consumer configuration screen: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/erase_registration.png" format="PNG" scale="80" width="444" /> + <imagedata align="center" fileref="images/WSRP/erase_registration.png" format="PNG" scale="80" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration.png" format="PNG" /> </imageobject> </mediaobject> <warning> @@ -837,10 +871,10 @@ </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/erase_registration_warning.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/erase_registration_warning.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration_warning.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration_warning.png" format="PNG" /> </imageobject> </mediaobject> </warning> @@ -849,23 +883,22 @@ </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Configuring_PRODUCT_NAMEs_WSRP_Producer"> - <title>Configuring &PRODUCT_NAME;&#39;s WSRP Producer</title> - <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Overview"> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Configuring_the_WSRP_Producer"> + <title>Configuring the WSRP Producer</title> + <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-Overview"> <title>Overview</title> <para> - The behavior of the Portal&#39;s WSRP Producer can be configured using the WSRP administration interface, (this is the recommended method), or by editing the <filename><replaceable>PORTAL_HOME</replaceable>/wsrp-producer.war/WEB-INF/conf/producer/config.xml</filename> file. + The behavior of the Portal's WSRP Producer can be configured using the WSRP administration interface, (this is the recommended method), or by editing the <filename><replaceable>PORTAL_HOME</replaceable>/wsrp-producer.war/WEB-INF/conf/producer/config.xml</filename> file. </para> <para> - Several aspects can be modified with respects to whether registration is required for consumers to access the Producer&#39;s services. An XML Schema for the configuration format is available at <filename> <replaceable>PORTAL_HOME</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename>. + Several aspects can be modified with respect to whether registration is required for consumers to access the Producer's services. An XML Schema for the configuration format is available at <filename> <replaceable>PORTAL_HOME</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename>. </para> </section> - - <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Default_configuration"> - <title>Default configuration</title> + <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-Default_Configuration"> + <title>Default Configuration</title> <para> - The default producer configuration requires that consumers register with it before providing access its services. However it does not require any specific registration properties (excepting those mandated by the WSRP standard). + The default producer configuration requires that consumers register with it before providing access to its services. However it does not require any specific registration properties (excepting those mandated by the WSRP standard). </para> <para> It does, however, require consumers to be registered before sending them a full service description. This means that the WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. @@ -874,114 +907,111 @@ The producer also uses the default <classname>RegistrationPolicy</classname> paired with the default <classname>RegistrationPropertyValidator</classname>. </para> <para> - This allows users to customize how Portal&#39;s WSRP Producer decides whether a given registration property is valid or not (however property validators are discussed in greater detail in <xref linkend="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Registration_configuration" />). + This allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not (however property validators are discussed in greater detail in <xref linkend="sect-Reference_Guide-Configuring_the_WSRP_Producer-Registration_Configuration" />). </para> <para> - &PRODUCT_NAME; provides a web interface to configure the producer&#39;s behavior. It can be accessed by clicking on the &#34;<emphasis role="bold">Producer Configuration</emphasis>&#34; tab of the &#34;<emphasis role="bold">WSRP</emphasis>&#34; page of the &#34;<emphasis role="bold">admin</emphasis>&#34; portal. + &PRODUCT; provides a web interface to configure the producer's behavior. It can be accessed by clicking on the "<emphasis role="bold">Producer Configuration</emphasis>" tab of the "<emphasis role="bold">WSRP</emphasis>" page of the "<emphasis role="bold">admin</emphasis>" portal. </para> <para> The default configuration should show: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_default.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/producer_default.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_default.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_default.png" format="PNG" /> </imageobject> </mediaobject> <para> - Administrators can specify whether or not a producer which requires registration will send the full service description to unregistered consumers. + You can specify whether or not the producer will send the full service description to unregistered consumers, and, if it requires registration, which <literal>RegistrationPolicy</literal> to use (and, if needed, which <literal>RegistrationPropertyValidator</literal>), along with required registration property description for which consumers must provide acceptable values to successfully register. </para> - <para> - The full service description includes which <classname>RegistrationPolicy</classname> (and <classname>RegistrationPropertyValidator</classname> if needed) to use, as well as required registration property descriptions for which consumers must provide acceptable values to successfully register. - </para> </section> - <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Registration_configuration"> - <title>Registration configuration</title> + <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-Registration_Configuration"> + <title>Registration Configuration</title> <para> - In order to have consumers register with Portal&#39;s producer the Portal&#39;s behavior with respect to registration must be configured. + In order to have consumers register with Portal's producer the Portal's behavior with respect to registration must be configured. </para> <para> Registration is optional, as are registration properties. The producer can require registration without requiring consumers to pass any registration properties as is the case in the default configuration. </para> <para> - The following section discusses configuring a producer&#39;s registration behavior from a blank state: + The following section discusses configuring a producer's registration behavior from a blank state: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_blank.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/producer_blank.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_blank.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_blank.png" format="PNG" /> </imageobject> </mediaobject> <procedure> <step> <para> - To allow unregistered consumers to see the list of offered portlets, leave the first checkbox (&#34;<emphasis role="bold">Access to full service description requires consumers to be registered.</emphasis>&#34;) unchecked. + To allow unregistered consumers to see the list of offered portlets, leave the first checkbox ("<emphasis role="bold">Access to full service description requires consumers to be registered.</emphasis>") unchecked. </para> </step> <step> <para> - To specify, however, that consumers will need to be registered to be able to interact with the producer, check the second box (&#34;<emphasis role="bold">Requires registration. Modifying this information will trigger invalidation of consumer registrations.&#34;</emphasis>). + To specify, however, that consumers will need to be registered to be able to interact with the producer, check the second box ("<emphasis role="bold">Requires registration. Modifying this information will trigger invalidation of consumer registrations."</emphasis>). </para> <para> The screen will refresh and display: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_registration.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/producer_registration.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_registration.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_registration.png" format="PNG" /> </imageobject> </mediaobject> </step> <step> <para> - The fully-qualified name for the <classname>RegistrationPolicy</classname> and <classname>RegistrationPropertyValidator</classname> can be specified here. The default values are acceptable. Refer to <xref linkend="sect-Reference_Guide-Registration_configuration-Customization_of_Registration_handling_behavior" /> for more information. + The fully-qualified name for the <classname>RegistrationPolicy</classname> and <classname>RegistrationPropertyValidator</classname> can be specified here. The default values are acceptable. Refer to <xref linkend="sect-Reference_Guide-Registration_Configuration-Customization_of_Registration_Handling_Behavior" /> for more information. </para> </step> <step> <para> - To add a registration property called <literal>email</literal> click &#34;A<emphasis role="bold">dd property</emphasis>&#34; and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to determine its purpose: + To add a registration property called <literal>email</literal> click "<emphasis role="bold">Add property</emphasis>" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to determine its purpose: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_email.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/producer_email.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_email.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_email.png" format="PNG" /> </imageobject> </mediaobject> </step> <step> <para> - Press &#34;Save&#34; to record the modifications. + Press "Save" to record the modifications. </para> </step> </procedure> <note> <para> - At this time, only String (xsd:string) properties are supported. <!-- If your application requires more complex properties, please let us know. --> + At this time, only String (<literal>xsd:string</literal>) properties are supported. </para> </note> <note> <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. The consumer side of that process is documented in <xref linkend="sect-Reference_Guide-Modifying_a_currently_held_registration-Registration_modification_on_Producer_error" />. + 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. The consumer side of that process is documented in <xref linkend="sect-Reference_Guide-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error" />. </para> </note> - <section id="sect-Reference_Guide-Registration_configuration-Customization_of_Registration_handling_behavior"> - <title>Customization of Registration handling behavior</title> + <section id="sect-Reference_Guide-Registration_Configuration-Customization_of_Registration_Handling_Behavior"> + <title>Customization of Registration Handling Behavior</title> <para> Registration handling behavior can be customized by users to suit their Producer needs. This is done with an implementation of the <classname>RegistrationPolicy</classname> interface. </para> <para> - This interface defines methods that are called by Portal&#39;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. + This interface defines methods that are called by Portal's Registration service so that decisions can be made appropriately. A default registration policy that provides basic behavior is provided and should be enough for most user needs. </para> <para> While the default registration policy provides default behavior for most registration-related aspects, one aspect requires specific configuration: whether a given value for a registration property is acceptable by the WSRP Producer. @@ -990,14 +1020,23 @@ This is done by plugging a <classname>RegistrationPropertyValidator</classname> into the default registration policy. This allows users to define their own validation mechanism. </para> <para> - Refer to the <trademark class="trade">Javadoc</trademark> for <classname>org.jboss.portal.registration.RegistrationPolicy</classname> and <classname>org.jboss.portal.Registration.policies.RegistrationPropertyValidator</classname> for more details on what is expected of each method. + Refer to the <trademark class="trade">Javadoc</trademark> for <classname>org.gatein.registration.RegistrationPolicy</classname> and <classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname> for more details on what is expected of each method. </para> <para> - A defined registration policy is required for the producer to be correctly configured. Do this by specifying the qualified class name of the registration policy. As it is anticipated that most users will use the default registration policy, it is possible to provide the class name of a custom property validator instead to customize the default registration policy behavior. Note that property validators are only used by the default policy. + A defined registration policy is required for the producer to be correctly configured. Do this by specifying the qualified class name of the registration policy. + </para> + <para> + As it is anticipated that most users will use the default registration policy, it is possible to provide the class name of a custom property validator instead to customize the default registration policy behavior. Note that property validators are only used by the default policy. </para> <note> <para> - Since the policy or the validator are defined via their class name and dynamically loaded, it is important to ensure that the identified class is available to the application server. One way to accomplish that is to deploy the policy implementation as JAR file in the AS instance deploy directory. Note also that, since both policies and validators are dynamically instantiated, they must provide a default, no-argument constructor. + Since the policy or the validator are defined via their class name and dynamically loaded, it is important to ensure that the identified class is available to the application server. + </para> + <para> + One way to accomplish that is to deploy the policy implementation as a JAR file in the AS instance deploy directory. + </para> + <para> + Note also that, since both policies and validators are dynamically instantiated, they must provide a default, no-argument constructor. </para> </note> </section> @@ -1005,13 +1044,19 @@ </section> - <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-WSRP_validation_mode"> - <title>WSRP validation mode</title> + <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-WSRP_Validation_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. Experience from these issues has produced a way to relax the validation that the WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. Note that the our validation algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes. + The lack of conformance kit and the wording of the WSRP specification leaves room for differing interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when using consumers from different vendors. + </para> + <para> + Experience of these issues has produced a way to relax the validation that the WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. + </para> + <para> + Note that the our validation algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes. </para> <para> - By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you might want to try to relax the validation mode. This is accomplished by unchecking the &#34;Use strict WSRP compliance&#34; checkbox on the Producer configuration screen. + By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you may attempt to relax the validation mode. Unchecking the "Use strict WSRP compliance" checkbox on the Producer configuration screen to do this. </para> </section>