Author: smumford Date: 2010-05-20 04:48:41 -0400 (Thu, 20 May 2010) New Revision: 3140 Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_end.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_init.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_missing.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_refresh.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_self.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_wsdl.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/consumer_operations.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/modify_reg_end.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/modify_reg_self.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/modify_reg_self_end.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/producer_blank.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/producer_default.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/producer_email.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/producer_registration.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/remote_portlets.png portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/architecture.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/cluster-config.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration-persister.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/intro.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/query-handler-config.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/statistics.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/transaction-manager-lookup.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml Log: JBEPP-276: Final edits and QE action. See JIRA comment for more details Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_end.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_init.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_missing.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_refresh.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_self.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/config_wsdl.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/consumer_operations.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/modify_reg_end.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/modify_reg_self.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/modify_reg_self_end.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/producer_blank.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/producer_default.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/producer_email.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/producer_registration.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/images/WSRP/remote_portlets.png =================================================================== (Binary files differ) Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -5,8 +5,8 @@ ]> <chapter id="chap-Reference_Guide-Foundations"> <title>Foundations</title> - <section id="sect-Reference_Guide-Foundations-The_GateIn_Kernel"> - <title>The GateIn 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> @@ -14,7 +14,7 @@ Service components exist in two scopes. The first scope is represented by the <literal>RootContainer</literal>. It contains services that exist independently of any portal, and can be accessed by all portals. </para> <para> - The second scope, the <literal>PortalContainer</literal>, is portal-private. Each portal exists in an instance of PortalContainer. This scope contains services that are common for a set of portals, and services which should not be shared by all portals. + The second scope, the <literal>PortalContainer</literal>, is portal-specific. Each portal exists in an instance of the <literal>PortalContainer</literal>. This scope contains services that are common for a set of portals, and services which should not be shared by all portals. </para> <para> <mediaobject> @@ -27,17 +27,17 @@ </mediaobject> </para> <para> - Whenever a specific service is looked up through <literal>PortalContainer</literal>, and the service is not available, the lookup is delegated further up to <literal>RootContainer</literal>. + Whenever a specific service is looked up through the <literal>PortalContainer</literal>, and the service is not available, the lookup is delegated further up to the <literal>RootContainer</literal>. </para> <para> - &PRODUCT; can have default instance of a certain component in <literal>RootContainer</literal>, and portal specific instances in some or all <literal>PortalContainers</literal>, that override the default instance. + &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 GateIn services, these services can be looked up through <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> <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 GateIn, 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> @@ -45,33 +45,32 @@ <section id="sect-Reference_Guide-Foundations-Configuring_services"> <title>Configuring services</title> <para> - GateIn 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. + 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 <emphasis>conf/configuration.xml</emphasis> in the classpath (any directory, or any jar in the classpath) will have their services configured at RootContainer scope. All <filename>configuration.xml</filename> files located at <emphasis role="bold">conf/portal/configuration.xml</emphasis> in the classpath will have their services configured at PortalContainer scope. + 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 at PortalContainer scope. + 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. </para> <note> <para> - Portal extensions are described later in this document. + <emphasis role="bold">Portal extensions</emphasis> are described later in this document. </para> </note> </section> - <section id="sect-Reference_Guide-Foundations-Configuration_syntax"> <title>Configuration syntax</title> <section id="sect-Reference_Guide-Configuration_syntax-Components"> <title>Components</title> <para> - A service component is defined in <filename>configuration.xml</filename> by using <emphasis role="bold">&lt;component&gt;</emphasis> element. + A service component is defined in <filename>configuration.xml</filename> by using a <emphasis role="bold">&lt;component&gt;</emphasis> element. </para> <para> Only one piece of information is required when defining a service; the service implementation class. This is specified using <literal>&lt;type&gt;</literal> </para> <para> - Every component has a <literal>&lt;key&gt;</literal> that identifies it. If not explicitly set, a key defaults to the value of <literal>&lt;type&gt;</literal>. If key can be loaded as a class, a Class object is used as a key, otherwise a String is used. + Every component has a <literal>&lt;key&gt;</literal> that identifies it. If not explicitly set, a key defaults to the value of <literal>&lt;type&gt;</literal>. If a key can be loaded as a class, a class object is used as a key, otherwise a string is used. </para> <para> The usual approach is to specify an interface as a key. @@ -97,13 +96,13 @@ <section id="sect-Reference_Guide-Configuration_syntax-External_Plugins"> <title>External Plugins</title> <para> - The GateIn Kernel supports non-component objects that can be configured, instantiated, and injected into registered components, using method calls. This '<emphasis>plugins</emphasis>' 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 '<emphasis>plugin</emphasis>' method allows portal extensions to add additional configurations to core services. </para> <para> - An external plugin is defined by using the <literal>&lt;external-component-plugins&gt;</literal> wrapper element which contains one or more <literal>&lt;component-plugin&gt;</literal> definitions. + An external plugin is defined by using the <literal>&lt;external-component-plugin&gt;</literal> wrapper element which contains one or more <literal>&lt;component-plugin&gt;</literal> definitions. </para> <para> - The <literal>&lt;external-component-plugins&gt;</literal> element uses <literal>&lt;target-component&gt;</literal> to specify a target service component that will receive injected objects. + The <literal>&lt;external-component-plugin&gt;</literal> element uses <literal>&lt;target-component&gt;</literal> to specify a target service component that will receive injected objects. </para> <para> Every <literal>&lt;component-plugin&gt;</literal> defines an implementation type, and a method on target component to use for injection (<literal>&lt;set-method&gt;</literal>). @@ -112,7 +111,7 @@ A plugin implementation class has to implement the <emphasis role="bold">org.exoplatform.container.component. ComponentPlugin</emphasis> interface. </para> <para> - In the following example <literal>PortalContainerDefinitionPlugin</literal> implements <literal>ComponentPlugin</literal>: + In the following example the <literal>PortalContainerDefinitionPlugin</literal> implements the <literal>ComponentPlugin</literal>: </para> <programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> @@ -146,10 +145,10 @@ <section id="sect-Reference_Guide-Configuration_syntax-Includes_and_special_URLs"> <title>Includes, and special URLs</title> <para> - It is possible to the break the <filename>configuration.xml</filename> file into many smaller files, which are then included into a 'master' configuration file. + It is possible to divide the <filename>configuration.xml</filename> file into many smaller files, which are then included into the main configuration file. </para> <para> - The included files must be complete <filename>configuration.xml</filename> documents in their own right. That is, they can not be fragments of text. + The included files must be valid xml files; they cannot be fragments of text. </para> <para> Below is an example <filename>configuration.xml</filename> that 'outsources' its content into several files: @@ -172,7 +171,7 @@ <callout arearefs="area-Reference_Guide-Configuration_syntax-Includes_and_special_URLs-url_schema"> <para> - This line is being used to reference another configuration file. The <code>war:</code> URL schema indicates that the path that follows is to be resolved relative to the current PortalContainer's servlet context resource path, starting with <emphasis role="bold">WEB-INF</emphasis> as a root. + This line is being used to reference another configuration file. The <code>war:</code> URL schema indicates that the following path is to be resolved relative to the current <literal>PortalContainer</literal>'s servlet context resource path, starting with <emphasis role="bold">WEB-INF</emphasis> as a root. </para> </callout> </calloutlist> @@ -196,7 +195,7 @@ Configuration files may contain a <emphasis role="bold">special variable</emphasis> reference <emphasis>${container.name.suffix}</emphasis>. This variable resolves to the name of the current portal container, prefixed by underscore (_). </para> <para> - This facilitates reuse of configuration files in situations where portal specific unique names need to be assigned to some resources; JNDI names, Database/DataSource names and JCR repository names, for example. + This facilitates reuse of configuration files in situations where portal-specific unique names need to be assigned to some resources; JNDI names, Database/DataSource names and JCR repository names, for example. </para> <para> This variable is only defined when there is a current <literal>PortalContainer</literal> available and is only available for <literal>PortalContainer</literal> scoped services. @@ -241,18 +240,18 @@ </section> <section id="sect-Reference_Guide-Foundations-InitParams_configuration_object"> - <title>InitParams configuration object</title> + <title>InitParams configuration element</title> <para> - <parameter>InitParams</parameter> is a configuration object that is essentially a map of key-value pairs, where <emphasis role="bold">key</emphasis> is always a <literal>String</literal>, and <emphasis role="bold">value</emphasis> can be any type that can be described using the kernel XML configuration. + <parameter>InitParams</parameter> is a configuration element that is essentially a map of key-value pairs, where <emphasis role="bold">key</emphasis> is always a <literal>String</literal>, and <emphasis role="bold">value</emphasis> can be any type that can be described using the kernel XML configuration. </para> <para> - Service components that form the &PRODUCT; insfrastructure use <parameter>InitParams</parameter> objects to configure themselves. A component can have one instance of <parameter>InitParams</parameter> injected at most. + Service components that form the &PRODUCT; infrastructure use <parameter>InitParams</parameter> elements to configure themselves. A component can have one instance of <parameter>InitParams</parameter> injected at most. </para> <para> If the service component'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> object <emphasis role="bold">must</emphasis> include an <parameter>&lt;init-params&gt;</parameter> element, however this element may be empty. + The XML configuration for a service component that expects an <parameter>InitParams</parameter> element must have an <parameter>&lt;init-params&gt;</parameter> element present, however this element can be left empt </para> <para> Below is an example of how the kernel XML configuration syntax looks when creating <parameter>InitParams</parameter> instances: @@ -273,7 +272,7 @@ ]]></programlisting> <para> - An <parameter>InitParams</parameter> object description begins with <parameter>&lt;init-params&gt;</parameter> element. + An <parameter>InitParams</parameter> element description begins with an <parameter>&lt;init-params&gt;</parameter> element. </para> <para> It can have zero or more children elements, each of which is one of the following: @@ -309,7 +308,7 @@ Each of these child elements takes a <parameter>&lt;name&gt;</parameter> that serves as a map entry key, and an optional <parameter>&lt;description&gt;</parameter>. It also takes a type-specific <emphasis role="bold">value</emphasis> specification. </para> <para> - The value specification for the <parameter>&lt;properties-param&gt;</parameter> defines one or more <parameter>&lt;property&gt;</parameter> elements, each of which specifies two strings; a property name and a property value. This is evident in the two examples above. + The value specification for the <parameter>&lt;properties-param&gt;</parameter> defines one or more <parameter>&lt;property&gt;</parameter> element, each of which specifies two strings; a property name and a property value. This is evident in the two previous examples. </para> <para> Each <parameter>&lt;properties-params&gt;</parameter> defines one <literal>java.util.Properties</literal> instance. @@ -362,7 +361,7 @@ ]]></programlisting> <para> - The value specification for <parameter>&lt;values-param&gt;</parameter> requires one or more <parameter>&lt;value&gt;</parameter> elements. Each <parameter>&lt;value&gt;</parameter> represents one <literal>String</literal> instance. All <literal>String</literal> values are then collected into a <literal>java.util.List</literal> instance. + The value specification for <parameter>&lt;values-param&gt;</parameter> requires one or more <parameter>&lt;value&gt;</parameter> element. Each <parameter>&lt;value&gt;</parameter> represents one <literal>String</literal> instance. All <literal>String</literal> values are then collected into a <literal>java.util.List</literal> instance. </para> <programlisting language="XML" role="XML"><![CDATA[<component> @@ -396,13 +395,13 @@ ]]></programlisting> <para> - For <parameter>&lt;object-param&gt;</parameter> entries, the value specification consists of a <parameter>&lt;object&gt;</parameter> element which is used for plain java style object specification (specifying an implementation <emphasis>class - <parameter>&lt;type&gt;</parameter></emphasis>, and <emphasis>property values - <parameter>&lt;field&gt;</parameter></emphasis>). + For <parameter>&lt;object-param&gt;</parameter> entries, the value specification consists of an <parameter>&lt;object&gt;</parameter> element which is used for plain java style object specification (specifying an implementation <emphasis>class - <parameter>&lt;type&gt;</parameter></emphasis>, and <emphasis>property values - <parameter>&lt;field&gt;</parameter></emphasis>). </para> <para> The following section has an example of specifying a field of with a <literal>Collection</literal> type. </para> <para> - The <parameter>InitParams</parameter> structure (the names and types of entries) is specific for each service, as it is the code inside a service components's class that defines which entry names to look up and what types it expects to find. + The <parameter>InitParams</parameter> structure (the names and types of entries) is specific for each service, as it is the code inside a service components' class that defines which entry names to look up and what types it expects to find. </para> </section> @@ -530,7 +529,7 @@ Dependencies are part of the <emphasis role="bold">extension mechanism</emphasis> which is discussed later in this document. </para> <para> - Every <literal>portal container</literal> is represented by a <literal>PortalContainer instance</literal>, which contains: + Every <literal>PortalContainer</literal> is represented by a <literal>PortalContainer instance</literal>, which contains: </para> <variablelist> <varlistentry> @@ -545,7 +544,7 @@ <term>Unified Servlet Context</term> <listitem> <para> - Which deals with web-archive-relative resource loading. + This deals with web-archive-relative resource loading. </para> </listitem> </varlistentry> @@ -570,20 +569,20 @@ 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 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 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>. </para> <para> - Resources from other web applications are queried in the order specified by Dependencies. The later entries in the list override the previous ones. + 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> </section> - <section id="sect-Reference_Guide-Foundations-GateIn_Extension_Mechanism_and_Portal_Extensions"> + <section id="sect-Reference_Guide-Foundations-Exo_Extension_Mechanism_and_Portal_Extensions"> <title>The Extension Mechanism and Portal Extensions</title> <para> 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'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'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>. @@ -614,7 +613,7 @@ </step> <step> <para> - Add the application's servlet context name to the <literal>PortalContainerDefinition</literal>'s list of Dependencies. This must be done for each portal container that you want to have access to the new application. + Add the application's servlet context name to the <literal>PortalContainerDefinition</literal>'s list of dependencies. This must be done for each portal container that you want to have access to the new application. </para> <para> The application's position in these lists will dictate its priority when the portal loads resources. The later your application appears in the list, the higher its resource priority will be. @@ -630,7 +629,7 @@ <note> <title>Example</title> <para> - Refer to the code extract in <xref linkend="sect-Reference_Guide-Foundations-Configuring_a_portal_container"/> for an example of a <literal>PortalContainerDefinition</literal> that has <emphasis role="bold">sample-ext</emphasis> in its list of Dependencies. + Refer to the code extract in <xref linkend="sect-Reference_Guide-Foundations-Configuring_a_portal_container"/> for an example of a <literal>PortalContainerDefinition</literal> that has <emphasis role="bold">sample-ext</emphasis> in its list of dependencies. </para> </note> </section> @@ -660,10 +659,10 @@ 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 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's context classloader to one that looks for resources in associated web applications in the order specified by <emphasis role="bold">Dependencies</emphasis> configuration (as seen in <xref linkend="sect-Reference_Guide-Foundations-GateIn_Extension_Mechanism_and_Portal_Extensions"/>). + This will also set the current thread'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-Exo_Extension_Mechanism_and_Portal_Extensions"/>). </para> <para> Filter classes need to extend the <literal>org.exoplatform.container.web. AbstractFilter</literal>. @@ -689,7 +688,7 @@ </para> </note> <para> - An application may also need to access 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 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. </para> <para> In this instance, modify the method signatures as follows: @@ -720,7 +719,7 @@ </programlisting> <para> - If this method returns <emphasis>true</emphasis> the current thread's context classloader is set up according to the <emphasis role="bold">Dependencies</emphasis> configuration and availability of the associated web applications. + If this method returns <emphasis>true</emphasis> the current thread's context classloader is set up according to the <emphasis role="bold">dependencies</emphasis> configuration and availability of the associated web applications. </para> <para> If it returns <emphasis>false</emphasis> the standard application separation rules are used for resource loading (effectively turning off the extension mechanism). @@ -730,13 +729,13 @@ </para> <formalpara> - <title>ServletContextListener-based initialization needing to access PortalContainer</title> + <title>ServletContextListener-based initialization access to PortalContainer</title> <para> &PRODUCT; has no direct control over the deployment of application archives (<code>.war</code> and <code>.ear</code> files); it is the application server that performs the deployment. </para> </formalpara> <para> - However, the applications in the <emphasis role="bold">Dependencies</emphasis> configuration must be deployed <emphasis>before</emphasis> the portal that depends on them is initialized in order for the <emphasis role="bold">extension mechanism</emphasis> to work properly. + However, applications in the <emphasis role="bold">dependencies</emphasis> configuration must be deployed <emphasis>before</emphasis> the portal that depends on them is initialized in order for the <emphasis role="bold">extension mechanism</emphasis> to work properly. </para> <para> Conversely, some applications may require an already initialized <literal>PortalContainer</literal> to properly initialize themselves. This gives rise to a recursive dependency problem. @@ -751,7 +750,7 @@ To ensure this, a web application should package its initialization logic into an <code>init</code> task of an appropriate type and only use <literal>ServletContextListener</literal> to insert the <code>init</code> task instance into the proper <code>init</code> tasks queue. </para> <para> - An example of this is the Gadgets application which registers Google gadgets with the current <literal>PortalContainer</literal>. This example uses <emphasis role="bold">PortalContainerPostInitTask</emphasis> which gets executed after the portal container has been initialized. + An example of this is the Gadgets application which registers Google gadgets with the current <literal>PortalContainer</literal>. This example uses <emphasis role="bold">PortalContainerPostInitTask</emphasis> which is executed after the portal container has been initialized. </para> <programlisting language="Java" role="JAVA"> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/architecture.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/architecture.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/architecture.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -7,11 +7,11 @@ <sectioninfo> <keywordset> <keyword>JCR</keyword> - <keyword>eXoJCR</keyword> + <keyword>eXo JCR</keyword> <keyword>etc</keyword> </keywordset> </sectioninfo> - <title>Basic concepts of eXoJCR</title> + <title>Basic concepts of eXo JCR</title> <para> DOC TODO: Needs text. </para> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/cluster-config.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/cluster-config.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/cluster-config.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -41,7 +41,7 @@ </step> <step> <para> - Ensure that you use JBossTS and JBossCache. See <xref linkend="chap-Reference_Guide-eXoJCR"/> and <xref linkend="sect-Reference_Guide-JBossTransactionsService"/> for more information. + Ensure that you use JBossTS and JBoss Cache. See <xref linkend="chap-Reference_Guide-eXoJCR"/> and <xref linkend="sect-Reference_Guide-JBossTransactionsService"/> for more information. </para> <para> The <filename>exo-configuration.xml</filename> must contain the following parts: @@ -70,7 +70,7 @@ </step> <step> <para> - Navigate a web browser to <ulink url="http://localhost:8080/browser">http://localhost:8080/browser</ulink>. This should access to repository browser. + Navigate a web browser to <ulink url="http://localhost:8080/browser">http://localhost:8080/browser</ulink>. This should access the repository browser. </para> <para> The default user login and password combination is root/exo. @@ -81,14 +81,14 @@ <formalpara> <title>Configuring JCR to use an external configuration</title> <para> - To manually configure a repository, create a new configuration file (<filename>exo-jcr-configuration.xml</filename>). + To manually configure a repository, create a new configuration file (<filename>exo-jcr-configuration.xml</filename>). </para> </formalpara> <para> - For more information refer to <ulink url="http://wiki.exoplatform.org/xwiki/bin/view/JCR/#HConfiguration&... Configuration</ulink>. + Refer to <ulink url="http://wiki.exoplatform.org/xwiki/bin/view/JCR/#HConfiguration&... Configuration</ulink> for more information. </para> <para> - The configuration must look like: + The configuration should look like this: </para> <programlistingco> @@ -171,7 +171,7 @@ </programlistingco> <para> - To update <parameter>RepositoryServiceConfiguration</parameter>, configurate the settings in <filename>exo-configuration.xml</filename> to use the new file: + Configure the settings in <filename>exo-configuration.xml</filename> to update <parameter>RepositoryServiceConfiguration</parameter>. To use the new file: </para> <programlisting language="XML" role="XML"><![CDATA[<component> @@ -240,7 +240,8 @@ <area coords="5" id="Reference_Guide-Requirements-Environment_requirements-cluster_name"/> </areaspec> -<programlisting language="XML" role="XML"><![CDATA[<cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache"> +<programlisting language="XML" role="XML"><![CDATA[<cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache. +JBossCacheWorkspaceStorageCache"> <properties> <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-data.xml" /> <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration-persister.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration-persister.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration-persister.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -26,7 +26,7 @@ In the example above the Repository Service will read the configuration from the file <filename>/conf/standalone/exo-jcr-config.xml</filename>. </para> <para> - To make changes while the JCR is active, to be sure the changes will be used, and to avoid modifying the orginal file, the configuration persister feature allows new configurations to stored in different locations. + The configuration persister feature allows new configurations to be stored in different locations. This allows changes to be made while the JCR is active, ensures the changes will be used, and avoids modifying the original file. </para> <section id="sect-Reference_Guide-The_JCR_Configuration_persister-Usage"> @@ -70,7 +70,7 @@ <calloutlist> <callout arearefs="Reference_Guide-The_The_JCR_Configuration_persister-source-name"> <para> - The <parameter>source-name</parameter> parameter is the JNDI source name configured in <classname>InitialContextInitializer</classname> component (also known as <parameter>sourceName</parameter> in versions prior to 1.9.). refer to <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/> for more information. + The <parameter>source-name</parameter> parameter is the JNDI source name configured in <classname>InitialContextInitializer</classname> component (also known as <parameter>sourceName</parameter> in versions prior to 1.9.). Refer to <xref linkend="sect-Reference_Guide-eXo_JCR_configuration"/> for more information. </para> </callout> <callout arearefs="Reference_Guide-The_The_JCR_Configuration_persister-dialect"> @@ -80,7 +80,7 @@ </callout> <callout arearefs="Reference_Guide-The_The_JCR_Configuration_persister-persister-class-name"> <para> - The <parameter>persister-class-name</parameter> parameter is the class name of the <classname>ConfigurationPersister</classname> interface implementation. (known as <parameter>persisterClassName</parameter> in version earlier than 1.9.) + The <parameter>persister-class-name</parameter> parameter is the class name of the <classname>ConfigurationPersister</classname> interface implementation (known as <parameter>persisterClassName</parameter> in versions earlier than 1.9.) </para> </callout> </calloutlist> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -9,10 +9,10 @@ The JCR configuration is defined in an XML file (as per the DTD below). </para> <para> - The JCR Service can use multiple Repositories and each repository can have multiple Workspaces. + The JCR Service can use multiple repositories and each repository can have multiple workspaces. </para> <para> - The Repositories configuration parameters support human-readable formats of values. They are not case-sensitive. + The repository configuration parameters support human-readable formats of values. They are not case-sensitive. </para> <para> The parameters are: @@ -25,27 +25,27 @@ <itemizedlist> <listitem> <para> - <emphasis role="bold">K</emphasis> or <emphasis role="bold">KB</emphasis> for kilobytes. + <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. + <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. + <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. + <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 + Examples: 200k or 200 KBytes; 4m or 4 MBytes; 1.4G or 1.4 GBytes; 10T or 10 TBytes </para> </listitem> </itemizedlist> @@ -106,16 +106,16 @@ <section id="sect-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration"> <title>Portal and Standalone configuration</title> <para> - Like other eXo services eXo JCR can be configured and used in Portal (or Embedded) mode (as a service embedded in eXo Portal) and in Standalone mode. + Like other eXo services, eXo JCR can be configured and used in portal (or embedded) mode (as a service embedded in EPP5) and in standalone mode. </para> <para> - In Embedded mode, JCR services are registered in the Portal container. In Standalone mode JCR uses a Standalone container. + In embedded mode, JCR services are registered in the portal container. In standalone mode JCR uses a standalone container. </para> <para> - The main difference between these container types is that the first is intended to be used in a Portal (Web) environment while the second can be used standalone. <!--(DOC TODO see the comprehensive page Service Configuration for Beginners for more details) --> + The main difference between these container types is that the first is intended to be used in a portal (Web) environment while the second can be used as a standalone. <!--(DOC TODO see the comprehensive page Service Configuration for Beginners for more details) --> </para> <para> - The following setup procedure is used to obtain a Standalone configuration: <!--(DOC TODO find more in Container configuration)--> + The following setup procedure is used to obtain a standalone configuration: <!--(DOC TODO find more in Container configuration)--> </para> <!-- DOC TODO: The following list of points are unclear. Are the edited versions correct? --> @@ -136,7 +136,7 @@ Configuration settings are read from <filename><replaceable>$base:directory</replaceable>/exo-configuration.xml</filename> or <filename><replaceable>$base:directory</replaceable>/conf/exo-configuration.xml</filename>. </para> <para> - Replace <replaceable>$base:directory</replaceable> in the above locations with, either the Application Server's home directory (in J2EE environments) or the current directory for standalone applications. + Replace <filename><replaceable>$base:directory</replaceable></filename> in the above locations with, either the application server's home directory (in J2EE environments) or the current directory for standalone applications. </para> </listitem> <listitem> @@ -152,7 +152,7 @@ Configuration from $service_jar_file/conf/portal/configuration.xml. WARNING: do not rely on some concrete jar's configuration if you have more than one jar containing conf/portal/configuration.xml file. In this case choosing a configuration is unpredictable. </para> --> <!-- Revised --><para> - Further configuration setting are read from <filename><replaceable>$service_jar_file</replaceable>/conf/portal/configuration.xml</filename> + Further configuration settings are read from <filename><replaceable>$service_jar_file</replaceable>/conf/portal/configuration.xml</filename> </para> <important> <para> @@ -195,7 +195,8 @@ <calloutlist> <callout arearefs="area-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration-JCR_Service_Configuration-conf-path"> <para> - <literal>&lt;conf-path&gt;</literal> is a path to a <literal>RepositoryService</literal> JCR Configuration. + <literal>&lt;conf-path&gt;</literal> is a path to a <literal>RepositoryService</literal> JCR Configuration. The .xml file in the example is not in the released jar file. +<!-- Added last sentence as per advice from Villiam Rockai that file does not exist in jar file --> </para> </callout> <callout arearefs="area-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration-JCR_Service_Configuration-working-conf"> @@ -208,7 +209,7 @@ </section> <section id="sect-Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration"> - <title>Repository service configuration</title> + <title>Repository Service Configuration</title> <para> The default configuration of the Repository Service is defined in <filename><replaceable>jar:</replaceable>/conf/portal/exo-jcr-config.xml</filename>. It is available in both portal and standalone modes. </para> @@ -393,7 +394,7 @@ <term>system-workspace</term> <listitem> <para> - The name of workspace where /jcr:system node is placed. + The name of workspace where <literal>/jcr:system</literal> node is placed. </para> </listitem> </varlistentry> @@ -409,13 +410,13 @@ <term>access-control</term> <listitem> <para> - The name of an access control policy. There can be 3 types: + The name of an access control policy. There can be three types: </para> <para> <emphasis role="bold">optional</emphasis> </para> <para> - AN ACL is created on-demand. This is the default policy. + AN ACL is created on demand. This is the default policy. </para> <para> <emphasis role="bold">disable</emphasis> @@ -427,7 +428,7 @@ <emphasis role="bold">mandatory</emphasis> </para> <para> - An ACL is created for each added node. This function not supported in this release. + An ACL is created for each added node. This function is not supported in this release. </para> </listitem> </varlistentry> @@ -451,7 +452,7 @@ <term>session-max-age</term> <listitem> <para> - The amount of time before an idle session will be removed (called logout). If not set, the idle session will never be removed. + 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> </listitem> </varlistentry> @@ -538,12 +539,12 @@ </variablelist> <variablelist> - <title>Value Storage plugin configuration (optional feature):</title> + <title>Value storage plugin configuration (optional feature):</title> <varlistentry> <term>value-storage</term> <listitem> <para> - Optional value Storage plugin definition. + Optional value storage plugin definition. </para> </listitem> </varlistentry> @@ -559,7 +560,7 @@ <term>properties</term> <listitem> <para> - The list of properties (in name-value pairs) for a concrete Value Storage plugin. + The list of properties (in name-value pairs) for a concrete value storage plugin. </para> </listitem> </varlistentry> @@ -636,22 +637,22 @@ The default value is <literal>org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl</literal>. </para> <para> - The cache can be configured to use concrete implementation of <literal>WorkspaceStorageCache</literal> interface. + The cache can be configured to use concrete implementations of the <literal>WorkspaceStorageCache</literal> interface. </para> <para> - The JCR core has two implementation to use: + 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 statistic. + The default implementation, with configurable read behavior and statistics. </para> <para> <emphasis role="bold">WorkspaceStorageCacheImpl</emphasis> </para> <para> - This implememtation if a legacy from pre 1.9 version of the JCR, however, it may still be used. + This implementation is a legacy from pre 1.9 versions of the JCR. However, it can still be used. </para> </listitem> </varlistentry> @@ -659,14 +660,14 @@ <term>properties</term> <listitem> <para> - The list of properties (in name-value pairs) for the Workspace cache: + 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. + The maximum size of the cache. </para> </listitem> </varlistentry> @@ -720,7 +721,7 @@ <term>persister</term> <listitem> <para> - A class for storing lock information for future use. For example; remove lock after jcr restart. + A class for storing lock information for future use. For example; remove lock after restarting JCR. </para> </listitem> </varlistentry> @@ -728,7 +729,7 @@ <term>path</term> <listitem> <para> - A lock folder, each workspace has its own. + Each workspace has its own lock folder. </para> </listitem> </varlistentry> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/external-value-storages.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -8,10 +8,10 @@ <section id="sect-Reference_Guide-External_Value_Storages-Introduction"> <title>Introduction</title> <para> - JCR Values are stored in the Workspace Data container by default. eXo JCR offers an additional option of storing JCR Values separately from Workspace Data container which can help keep Binary Large Objects (BLOBs). + JCR values are stored in the Workspace Data container by default. eXo JCR offers an additional option of storing JCR values separately from the Workspace Data container which can help keep Binary Large Objects (BLOBs) separate. </para> <para> - Value storage configuration is a part of the Repository configuration.Refer to <xref linkend="sect-Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration"/> for more details. + Value storage configuration is a part of the repository configuration. Refer to <xref linkend="sect-Reference_Guide-Portal_and_Standalone_configuration-Repository_service_configuration"/> for more details. </para> <para> Tree-based storage is recommended in most cases. @@ -25,13 +25,13 @@ <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 FileSystem files. <property>Path</property> property points to the root directory to store the files. </para> <para> - This is a recommended type of external storage, it can contain large amount of files limited only by disk/volume free space. + This is a recommended type of external storage because it can contain large amount of files limited only by disk/volume free space. </para> <para> - However using Tree File Value Storage can result in a higher time on Value deletion, due to the removal of unused tree-nodes. + However, using Tree File Value Storage can result in a higher time on value deletion, due to the removal of unused tree-nodes. </para> <programlistingco> @@ -51,7 +51,7 @@ <calloutlist> <callout arearefs="Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-id"> <para> - The <emphasis role="bold">id</emphasis> is the value storage unique identifier, used for linking with properties stored in workspace container + The <emphasis role="bold">id</emphasis> is the value storage unique identifier, used for linking with properties stored in a workspace container </para> </callout> <callout arearefs="Reference_Guide-External_Value_Storages-Tree_File_Value_Storage-path"> @@ -63,10 +63,10 @@ </programlistingco> <para> - Each file value storage can have the <function>filter(s)</function> for incoming values. A filter can match values by <property>property-type</property>, <property>property-name</property>, <property>ancestor-path</property> and/or the size of values stored (<property>min-value-size</property>, in bytes). + Each file value storage can have the <function>filters</function> for incoming values. A filter can match values by <property>property-type</property>, <property>property-name</property>, <property>ancestor-path</property>. It can also match the size of values stored (<property>min-value-size</property>) in bytes. </para> <para> - In the example above a filter with <property>property-type</property> and <property>min-value-size</property> has been used. This results in storage for binary values with size greater of 1MB. + In the previous example a filter with <property>property-type</property> and <property>min-value-size</property> has been used. This results in storage for binary values with size greater of 1MB. </para> <para> It is recommended that properties with large values are stored in file value storage only. @@ -78,7 +78,7 @@ A value storage uses ORed logic in the process of filter selection. This means the first filter in the list will be called first and if it is not matched the next will be called, and so on. </para> <para> - In this example a value matches the 20MB filter <property>min-value-size</property> and will be stored in the path "<literal>data/20Mvalues</literal>", all other filters will be stored in "<literal>data/values</literal>". + In this example a value matches the 20MB filter <property>min-value-size</property> and will be stored in the path "<literal>data/20Mvalues</literal>". All other filters will be stored in "<literal>data/values</literal>". </para> <programlisting language="XML" role="XML"><![CDATA[<value-storages> @@ -137,22 +137,22 @@ It is typically used for high-speed storage and retrieval of fixed content, such as documents stored for compliance with government regulations. </para> <para> - Content Addressable Value storage stores unique content once. Different properties (values) with same content will be stored as one data file shared between those values. We can tell the Value content will be shared across some Values in storage and will be stored on one physical file. + Content-addressable value storage stores unique content once. Different properties (values) with same content will be stored as one data file shared between those values. We can tell the value content will be shared across some values in storage and will be stored in one physical file. </para> <para> - Storage size will be decreased for application which governs potentially same data in the content. + Storage size will be decreased for applications which govern potentially same data in the content. </para> <para> - As an example; if 100 different properties contain the same data (e.g. mail attachment) the storage stores only one single file. The file will be shared with all referencing properties. + As an example; if 100 different properties contain the same data (mail attachments for example) the storage stores only one single file. The file will be shared with all referencing properties. </para> <para> - If a property Value changes it is stored in an additional file. Alternatively the file is shared with other values, pointing to the same content. + If a property value changes it is stored in an additional file. Alternatively the file is shared with other values, pointing to the same content. </para> <para> - The storage calculates Value content address each time the property was changed. CAS write operations are more expensive compared to the non-CAS storages. + The storage calculates value content address each time the property was changed. CAS write operations are more expensive compared to the non-CAS storages. </para> <para> - Content address calculation based on java.security.MessageDigest hash computation and tested with MD5 and SHA1 algorithms. + Content address calculation is based on <literal>java.security.MessageDigest</literal> hash computation and has been tested with MD5 and SHA1 algorithms. </para> <note> <para> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/intro.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/intro.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/intro.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -6,7 +6,7 @@ <section id="sect-Reference_Guide-Introduction"> <title>Introduction</title> <para> - The Java Content Repository (JCR) API was created within the Java Community Process <ulink type="http" url="http://jcp.org/">http://jcp.org/</ulink>) as a collaboration between an expert group and the Java community. + The Java Content Repository (JCR) API was created within the Java Community Process (JCP)<ulink type="http" url="http://jcp.org/">http://jcp.org/</ulink>) as a collaboration between an expert group and the Java community. </para> <para> Within the JCP, JCR is known as Java Specification Request-170 (JSR-170) <ulink type="http" url="http://www.jcp.org/en/jsr/detail?id=170">http://www.jcp...;. @@ -15,10 +15,10 @@ <section id="sect-Reference_Guide-JCR_JSR_170_API_main_concepts-The_Data_model"> <title>The data model</title> <para> - The main purpose of a content repository (CR) is to maintain data. Therefore the core of any CR is the data model: + The main purpose of a content repository (CR) is to maintain data. Therefore the core of any CR is the data model. </para> <para> - Some points about the eXoJCR are: + Some points about the eXo JCR are: </para> <itemizedlist> <listitem> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jbosscache-configuration-templates.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -8,10 +8,10 @@ <section id="sect-Reference_Guide-JBoss_Cache_configuration-JBoss_cache_configuration_for_indexer_lock_manager_and_data_container"> <title>Indexer, Lock Manager and Data Container</title> <para> - Each of these components use instances of the JBoss Cache product for caching in a clustered environment so every element has its own transport and has to be configured correctly. + Each of these components uses instances of the JBoss Cache product for caching in a clustered environment so every element has its own transport and has to be configured correctly. </para> <para> - As usual, workspaces has similar configuration but with different cluster-names (and possibly some other parameters). The best way to configure them is to define specific configuration files for each component in each workspace: + As usual, workspaces have similar configurations but with different cluster-names (and possibly some other parameters). The best way to configure them is to define specific configuration files for each component in each workspace. </para> <para> For example: @@ -23,7 +23,7 @@ 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. </para> <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 main configuration file. + 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> To do this, define <replaceable>${jbosscache-&lt;parameter name&gt;}</replaceable> inside an xml-template and list the correct value in the JCR configuration file (below the "<parameter>jbosscache-configuration</parameter>" entry) as shown below: @@ -49,7 +49,7 @@ <section id="sect-Reference_Guide-JBoss_Cache_configuration-JGroups_configuration"> <title>JGroups configuration</title> <para> - JGroups is used by JBoss Cache for network communications and transport in clustered environment. If the property "<parameter>jgroups-configuration</parameter>" is defined in the component configuration, it will be injected into the JBoss Cache instance on startup. + JGroups is used by JBoss Cache for network communications and transport in a clustered environment. If the property "<parameter>jgroups-configuration</parameter>" is defined in the component configuration, it will be injected into the JBoss Cache instance on startup. </para> <programlisting language="XML" role="XML"><![CDATA[<property name="jgroups-configuration" value="your/path/to/modified-udp.xml" />]]> @@ -58,7 +58,7 @@ As mentioned previously, each component (lock manager, data container and query handler) for each workspace requires its own clustered environment. </para> <para> - Each cluster should perform multi-casts on separate port by default. This configuration leads to unnecessary overhead on the cluster. JGroups offers a multiplexer feature providing the ability to use a single channel for a set of clusters. This feature reduces network overheads and increases the performance and stability of an application. + Each cluster should perform multi-casts on separate ports by default. This configuration leads to unnecessary overhead on the cluster. JGroups offers a multiplexer feature providing the ability to use a single channel for a set of clusters. This feature reduces network overheads and increases the performance and stability of an application. </para> <para> To enable the multiplexer stack feature, the appropriate configuration file must be defined and the "<parameter>jgroups-multiplexer-stack</parameter>" should be set to "<replaceable>true</replaceable>". @@ -67,7 +67,7 @@ A configuration file named <filename>upd-mux.xml</filename> is pre-shipped with the product. </para> <para> - Example: + For example: </para> <programlisting language="XML" role="XML"><![CDATA[<property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> @@ -77,7 +77,7 @@ <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 <filename>/conf/portal/</filename> directory. + 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. </para> <formalpara> <title>Data container template</title> @@ -86,7 +86,7 @@ </para> </formalpara> <para> - Example: + For example: </para> <programlistingco> <areaspec> @@ -128,7 +128,7 @@ <formalpara> <title>Lock manager template</title> <para> - The Lock Manager uses a template called "<filename>jbosscache-lock.xml</filename>" + The lock manager uses a template called "<filename>jbosscache-lock.xml</filename>" </para> </formalpara> <para> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/jdbc-data-container-config.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -23,7 +23,7 @@ <term>Single-database</term> <listitem> <para> - All the workspaces are persisted in one database. This mode is used in embedded eXo JCR service mode, e.g. in eXo portal. + All the workspaces are persisted in one database. This mode is used in embedded eXo JCR service mode, for example in EPP5. </para> </listitem> </varlistentry> @@ -126,7 +126,7 @@ 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>&lt;component&gt; +<programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/key&gt; &lt;type&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/type&gt; &lt;component-plugins&gt; @@ -294,7 +294,7 @@ &lt;/container&gt; &lt;cache enabled="true"&gt; &lt;properties&gt; - &lt;property name="max-size" value="10K"/&gt;&lt;!-- 10Kbytes --&gt; + &lt;property name="max-size" value="10K"/&gt;&lt;!-- 10KBytes --&gt; &lt;property name="live-time" value="30m"/&gt;&lt;!-- 30 min --&gt; &lt;/properties&gt; &lt;/cache&gt; @@ -350,7 +350,7 @@ <term>source-name</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 version earlier than 1.9. + 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. </para> </listitem> </varlistentry> @@ -418,7 +418,7 @@ </listitem> </itemizedlist> <para> - The dialect and also be set to "auto" to allow dialect autodetection. + The dialect can also be set to "auto" to allow dialect autodetection. </para> </listitem> </varlistentry> @@ -664,11 +664,11 @@ &lt;/worksapces&gt; </programlisting> <para> - Simple queries are implemented in such a way so as to support as many database dialects as possible. They do not use sub queries, left or right joins. + Simple queries are implemented in such a way so as to support as many database dialects as possible. They do not use sub queries, or left or right joins. </para> <para> - Complex queries will be used if you chose <classname>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</classname>: + Complex queries will be used if you choose <classname>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</classname>: </para> <programlisting>&lt;workspaces&gt; &lt;workspace name="ws" auto-init-root-nodetype="nt:unstructured"&gt; @@ -685,10 +685,10 @@ <section id="sect-Reference_Guide-JDBC_Data_Container_Config-Forse_Query_Hints"> <title>Force Query Hints</title> <para> - Some databases (such as <application>Oracle</application> and <application>MySQL</application>)support hints to increase query performanc. + Some databases (such as <application>Oracle</application> and <application>MySQL</application>)support hints to increase query performance. </para> <para> - eXo JCR has a separate Complex Query implementation for the <application>Oracle</application> dialect which uses query hints to increase performance for important queries. + eXo JCR has a separate complex query implementation for the <application>Oracle</application> dialect which uses query hints to increase performance for important queries. </para> <para> To enable this option complete the configuration property as shown below: @@ -705,10 +705,10 @@ <note> <para> Query hints are enabled by default. + </para> + <para> +Oracle is the only dialect that uses query hints. This parameter is ignored for all other dialects. </para> - <para> - eXo JCR only uses query hints for complex queries using the Oracle dialect. For all other dialects this parameter is ignored. - </para> </note> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/multilanguage-support.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -52,10 +52,10 @@ <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>. + 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> <para> - <constant>NLS_CHARACTERSET</constant> has tested well with many European and Asian languages when set at <constant>AL32UTF8</constant>. + <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: @@ -88,7 +88,7 @@ </para> </warning> <para> - To create a database with Unicode encoding using Oracle dialect for the Workspace Container implement the follwing settings: + To create a database with Unicode encoding using Oracle dialect for the Workspace Container, implement the following settings: </para> <programlisting language="XML" role="XML"><![CDATA[<workspace name="collaboration"> @@ -112,7 +112,7 @@ This enables JCR multi-lingual support. </para> <para> - Below is an example of creating a UTF-8 database using the <parameter>db2</parameter> dialect for a Workspace Container with DB2 version 9 and higher: + Below is an example of creating a UTF-8 database using the <parameter>db2</parameter> dialect for a workspace container with DB2 version 9 and higher: </para> <programlisting>DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US @@ -139,7 +139,7 @@ <section id="sect-Reference_Guide-Multilanguage_support_in_eXo_JCR_RDB_backend-MySQL"> <title>MySQL</title> <para> - USing JCR with a MySQL-backend requires a special dialect <ulink url="http://jira.exoplatform.org/browse/JCR-375">MySQL-UTF8&... to be used for internationalization support. + Using JCR with a MySQL-backend requires a special dialect <ulink url="http://jira.exoplatform.org/browse/JCR-375">MySQL-UTF8&... to be used for internationalization support. </para> <para> The database default charset should be <parameter>latin1</parameter> so as to use limited index space effectively (1000 bytes for an <literal>MyISAM</literal> engine and 767 for <literal>InnoDB</literal>). Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/query-handler-config.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/query-handler-config.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/query-handler-config.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -138,7 +138,7 @@ </calloutlist> </programlistingco> - +<!--MARK--> <formalpara> <title>JBoss Cache template configuration</title> <para> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/search-configuration.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -6,6 +6,9 @@ <section id="sect-Reference_Guide-Search_Configuration"> <title>Search Configuration</title> <para> +Search can be configured to perform in a specified way. + </para> + <para> The JCR index configuration file is located at <filename>/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> <para> @@ -35,7 +38,15 @@ </repositories> </repository-service>]]></programlisting> - <table pgwide="0"> + <note> + <para> + Due to sizing constraints in the table below, all references to classes or values that begin with the string <literal>org.exoplatform.services.jcr.impl.core.query.lucene</literal> will be refered to as <literal>$lucene.<replaceable>identifier</replaceable></literal>. + </para> + <para> + For example; <literal>org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex</literal> will appear as <literal>$lucene.SearchIndex</literal> + </para> + </note> + <table pgwide="0" align="left" > <title>Configuration parameters</title> <tgroup cols="4"> <thead> @@ -203,7 +214,7 @@ QueryImpl </entry> <entry> - Class name that implements the javax.jcr.query.Query interface.This class must also extend from the class: org.exoplatform.services.jcr.impl.core.query.AbstractQueryImpl. + Classname that implements the javax.jcr.query.Query interface.This class must also extend from the class: org.exoplatform.services.jcr.impl.core.query.AbstractQueryImpl. </entry> <entry> 1.9 @@ -245,7 +256,7 @@ DefaultXMLExcerpt </entry> <entry> - The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core.query.lucene.ExcerptProvider</literal>. This should be used for the <literal>rep:excerpt()</literal> function in a query. + The name of the class that implements <literal>$lucene.ExcerptProvider</literal>. This should be used for the <literal>rep:excerpt()</literal> function in a query. </entry> <entry> 1.9 @@ -273,7 +284,7 @@ none </entry> <entry> - The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core.query.lucene.SynonymProvider</literal>. The default value is null. + The name of a class that implements <literal>$lucene.SynonymProvider</literal>. The default value is null. </entry> <entry> 1.9 @@ -315,7 +326,7 @@ IndexingConfigurationImpl </entry> <entry> - The name of the class that implements <literal>org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfiguration</literal>. + The name of the class that implements <literal>$lucene.IndexingConfiguration</literal>. </entry> <entry> 1.9 @@ -343,7 +354,7 @@ none </entry> <entry> - The name of a class that implements <literal>org.exoplatform.services.jcr.impl.core.query.lucene.SpellChecker</literal>. + The name of a class that implements <literal>$lucene.SpellChecker</literal>. </entry> <entry> 1.9 @@ -415,23 +426,9 @@ <section id="sect-Reference_Guide-Search_Configuration-Global_Search_Index"> <title>Global Search Index</title> <para> - The global search index is configured in the <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the "query-handler" tag. + By default eXo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content: </para> - -<programlisting>&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; -</programlisting> - <para> - The same analyzer should always used be 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> - <para> - A customized QueryHandler can also be easily created. - </para> - <formalpara> - <title>Customized Search Indexes and Analyzers</title> - <para> - By default eXo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content: - </para> - </formalpara> + <programlistingco> <areaspec> <area coords="4" id="Reference_Guide-Search_Configuration-Global_Search_Index-StandardFilter"/> @@ -466,11 +463,27 @@ </calloutlist> </programlistingco> + <para> + The global search index is configured in the <filename>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the "query-handler" tag. + </para> + +<programlisting>&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; +</programlisting> + <para> + The same analyzer should always be used for indexing and for querying in lucene. Results may be unpredictable in other instances. eXo JCR does this automatically. The StandardAnalyzer (configured by default) can, however, be replaced with another. + </para> + <para> + A customized QueryHandler can also be easily created. + </para> + <formalpara> + <title>Customized Search Indexes and Analyzers</title> + <para> Additional filters can be used in specific cases. The <phrase>ISOLatin1AccentFilter</phrase> filter, for example, which replaces accented characters in the ISO Latin 1 character set (ISO-8859-1) by their unaccented equivalents. </para> + </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. @@ -522,12 +535,12 @@ <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 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: + To configure an application to use a new <literal>SearchIndex</literal>, replace the following code: </para> <programlisting>&lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt; @@ -541,7 +554,7 @@ </programlisting> <para> - To configure an application to use a new Analyzer add the "<parameter>analyzer</parameter>" 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>portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>: </para> <programlisting language="Java" role="JAVA"><![CDATA[<query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"> @@ -581,7 +594,7 @@ </para> </formalpara> <para> - With the below configuration only properties named <parameter>Text</parameter> are indexed for <parameter>nt:unstructured</parameter> node types. This configuration also applies to all nodes whose type extends from <parameter>nt:unstructured</parameter>. + With the configuration below only properties named <parameter>Text</parameter> are indexed for <parameter>nt:unstructured</parameter> node types. This configuration also applies to all nodes whose type extends from <parameter>nt:unstructured</parameter>. </para> <programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0"?> @@ -612,7 +625,7 @@ &lt;/configuration&gt; </programlisting> <para> - If you do not wish to boost the complete node but only certain properties you can also provide a boost value for the listed properties: + If you do not wish to boost the complete node, but only certain properties, you can also provide a boost value for the listed properties: </para> <programlisting>&lt;?xml version="1.0"?&gt; @@ -795,7 +808,7 @@ </configuration>]]></programlisting> <para> - The configuration above sets Lucene <emphasis role="bold">KeywordAnalyzer</emphasis> to index and search the property "<replaceable>mytext</replaceable>" across the entire workspace while the "<replaceable>mytext2</replaceable>" property is searched with the <emphasis role="bold">WhitespaceAnalyzer</emphasis>. + 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. @@ -811,7 +824,7 @@ </para> </formalpara> <para> - For example: the property "<parameter>mytext</parameter>" contains the text; "<emphasis>testing my analyzers</emphasis>" but no analyzers have been configured for this property (and the default analyzer in SerachIndex 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: Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/statistics.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/statistics.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/statistics.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -8,30 +8,33 @@ <section id="sect-Reference_Guide-eXo_JCR_statistics-Statistics_on_the_Database_Access_Layer"> <title>Statistics on the Database Access Layer</title> <para> - In order to have a better idea of the time spent into the database access layer, it cans be interesting to get some statistics on that part of the code, knowing that most of the time spent into eXo JCR is mainly the database access. This statistics will then allow you to identify without using any profiler what is anormally slow in this layer, which could help to fix the problem quickly. + In order to have a better idea of the time spent on the database access layer, administrators can get some statistics about that part of the code, knowing that most of the time spent on eXo JCR is mainly the database access. These statistics will then allow administrators to identify, without using a profiler, what is operating abnormally slowly in this layer, which could help troubleshoot problems quickly. </para> <para> - In case you use <envar>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</envar> or <envar>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</envar> as <envar>WorkspaceDataContainer</envar>, you can get statistics on the time spent into the database access layer. The database access layer (in eXo JCR) is represented by the methods of the interface <envar>org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</envar>, so for all the methods defined in this interface, we can have the following figures: + If <envar>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</envar> or <envar>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</envar> as in use as <envar>WorkspaceDataContainer</envar>, statistics can be obtained on the time spent on the database access layer. </para> + <para> + The database access layer (in eXo JCR) is represented by the methods of the interface <envar>org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</envar>, so for all the methods defined in this interface, the following figures are available: + </para> <itemizedlist> <listitem> <para> - The minimum time spent into the method. + The minimum time spent on the method. </para> </listitem> <listitem> <para> - The maximum time spent into the method. + The maximum time spent on the method. </para> </listitem> <listitem> <para> - The average time spent into the method. + The average time spent on the method. </para> </listitem> <listitem> <para> - The total amount of time spent into the method. + The total amount of time spent on the method. </para> </listitem> <listitem> @@ -44,18 +47,21 @@ Those figures are also available globaly for all the methods which gives us the global behavior of this layer. </para> <para> - If you want to enable the statistics, you just need to set the JVM parameter called <emphasis>JDBCWorkspaceDataContainer.statistics.enabled</emphasis> to <emphasis>true</emphasis>. The corresponding CSV file is <emphasis>StatisticsJDBCStorageConnection-${creation-timestamp}.csv</emphasis> for more details about how the csv files are managed please refer to the section dedicated to the statistics manager. + To enable the statistics, the JVM parameter called <emphasis>JDBCWorkspaceDataContainer.statistics.enabled</emphasis> must be set to <emphasis>true</emphasis>. The corresponding CSV file is <filename>StatisticsJDBCStorageConnection-${creation-timestamp}.csv</filename>. </para> <para> - The format of each column header is ${method-alias}-${metric-alias}. The metric alias are described in the statistics manager section. + For more information about how the CSV files are managed, refer to <xref linkend="sect-Reference_Guide-eXo_JCR_statistics-Statistics_Manager"/>. </para> + <para> + The format of each column header is <replaceable>${method-alias}</replaceable>-<replaceable>${metric-alias}</replaceable>. The metric aliases are described in <xref linkend="sect-Reference_Guide-eXo_JCR_statistics-Statistics_Manager"/>. + </para> <table id="tabl-Reference_Guide-Statistics_on_the_Database_Access_Layer-Method_Alias"> <title>Method Alias</title> <tgroup cols="2"> <tbody> <row> <entry> - global + <literal>global</literal> </entry> <entry> This is the alias for all the methods. @@ -63,7 +69,7 @@ </row> <row> <entry> - getItemDataById + <literal>getItemDataById</literal> </entry> <entry> This is the alias for the method <emphasis>getItemData(String identifier).</emphasis> @@ -71,7 +77,7 @@ </row> <row> <entry> - getItemDataByNodeDataNQPathEntry + <literal>getItemDataByNodeDataNQPathEntry</literal> </entry> <entry> This is the alias for the method <emphasis>getItemData(NodeData parentData, QPathEntry name).</emphasis> @@ -79,7 +85,7 @@ </row> <row> <entry> - getChildNodesData + <literal>getChildNodesData</literal> </entry> <entry> This is the alias for the method <emphasis>getChildNodesData(NodeData parent).</emphasis> @@ -87,7 +93,7 @@ </row> <row> <entry> - getChildNodesCount + <literal>getChildNodesCount</literal> </entry> <entry> This is the alias for the method <emphasis>getChildNodesCount(NodeData parent).</emphasis> @@ -95,7 +101,7 @@ </row> <row> <entry> - getChildPropertiesData + <literal>getChildPropertiesData</literal> </entry> <entry> This is the alias for the method <emphasis>getChildPropertiesData(NodeData parent).</emphasis> @@ -103,7 +109,7 @@ </row> <row> <entry> - listChildPropertiesData + <literal>listChildPropertiesData</literal> </entry> <entry> This is the alias for the method <emphasis>listChildPropertiesData(NodeData parent).</emphasis> @@ -111,7 +117,7 @@ </row> <row> <entry> - getReferencesData + <literal>getReferencesData</literal> </entry> <entry> This is the alias for the method <emphasis>getReferencesData(String nodeIdentifier).</emphasis> @@ -119,7 +125,7 @@ </row> <row> <entry> - commit + <literal>commit</literal> </entry> <entry> This is the alias for the method <emphasis>commit().</emphasis> @@ -127,7 +133,7 @@ </row> <row> <entry> - addNodeData + <literal>addNodeData</literal> </entry> <entry> This is the alias for the method <emphasis>add(NodeData data).</emphasis> @@ -135,7 +141,7 @@ </row> <row> <entry> - addPropertyData + <literal>addPropertyData</literal> </entry> <entry> This is the alias for the method <emphasis>add(PropertyData data).</emphasis> @@ -143,7 +149,7 @@ </row> <row> <entry> - updateNodeData + <literal>updateNodeData</literal> </entry> <entry> This is the alias for the method <emphasis>update(NodeData data).</emphasis> @@ -151,7 +157,7 @@ </row> <row> <entry> - updatePropertyData + <literal>updatePropertyData</literal> </entry> <entry> This is the alias for the method <emphasis>update(PropertyData data).</emphasis> @@ -159,7 +165,7 @@ </row> <row> <entry> - deleteNodeData + <literal>deleteNodeData</literal> </entry> <entry> This is the alias for the method <emphasis>delete(NodeData data).</emphasis> @@ -167,7 +173,7 @@ </row> <row> <entry> - deletePropertyData + <literal>deletePropertyData</literal> </entry> <entry> This is the alias for the method <emphasis>delete(PropertyData data).</emphasis> @@ -175,7 +181,7 @@ </row> <row> <entry> - renameNodeData + <literal>renameNodeData</literal> </entry> <entry> This is the alias for the method <emphasis>rename(NodeData data).</emphasis> @@ -183,7 +189,7 @@ </row> <row> <entry> - rollback + <literal>rollback</literal> </entry> <entry> This is the alias for the method <emphasis>rollback().</emphasis> @@ -191,7 +197,7 @@ </row> <row> <entry> - isOpened + <literal>isOpened</literal> </entry> <entry> This is the alias for the method <emphasis>isOpened().</emphasis> @@ -199,7 +205,7 @@ </row> <row> <entry> - close + <literal>close</literal> </entry> <entry> This is the alias for the method <emphasis>close().</emphasis> @@ -213,128 +219,147 @@ <section id="sect-Reference_Guide-eXo_JCR_statistics-Statistics_on_the_JCR_API_accesses"> <title>Statistics on the JCR API accesses</title> <para> - In order to know exactly how your application uses eXo JCR, it cans be interesting to register all the JCR API accesses in order to easily create real life test scenario based on pure JCR calls and also to tune your eXo JCR to better fit your requirements. + In order to know exactly how an application uses eXo JCR, all the JCR API accesses can be registered in order to easily create real life test scenarios based on pure JCR calls (and also to tune the eXo JCR to better fit requirements). </para> <para> - In order to allow you to specify into the configuration which part of eXo JCR needs to be monitored whitout applying any changes in your code and/or building anything, we choosed to rely on the Load-time Weaving proposed by AspectJ. + To allow specification into the configuration regarding which part of eXo JCR needs to be monitored without applying any changes into code the <application>Load-time Weaving</application> proposed by <literal>AspectJ</literal> has been implemented. </para> <para> - To enable this feature, you will have to add in your classpath the following jar files: + To enable this feature, add the following jar files into the classpath: </para> <itemizedlist> <listitem> <para> - <emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar corresponding to your eXo JCR version that you can get from the jboss maven repository <ulink url="???"><uri>http://repository.jboss.com/maven2/org/...;. + <emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar corresponding to your eXo JCR version that you can get from the jboss maven repository <!-- Broken URL <ulink url="???"><uri>http://repository.jboss.com/maven2/org/...;. </para> </listitem> <listitem> <para> - aspectjrt-1.6.8.jar that you can get from the main maven repository <ulink url="???"><uri>http://repo2.maven.org/maven2/org/aspec...;. + <filename>aspectjrt-1.6.8.jar</filename> that you can get from the main maven repository <ulink url="http://repo2.maven.org/maven2/org/aspectj/aspectjrt">ht...;. </para> </listitem> </itemizedlist> <para> - You will also need to get aspectjweaver-1.6.8.jar from the main maven repository <ulink url="???">http://repo2.maven.org/maven2/org/aspectj/aspectjw...;. At this stage, to enable the statistics on the JCR API accesses, you will need to add the JVM parameter <emphasis>-javaagent:${pathto}/aspectjweaver-1.6.8.jar</emphasis> to your command line, for more details please refer to <ulink url="???">http://www.eclipse.org/aspectj/doc/released/devgui...;. + You will also need to get <filename>aspectjweaver-1.6.8.jar</filename> from the main Maven repository <ulink url="http://repo2.maven.org/maven2/org/aspectj/aspectjweaver"&g...;. </para> <para> - By default, the configuration will collect statistcs on all the methods of the internal interfaces <emphasis>org.exoplatform.services.jcr.core.ExtendedSession</emphasis> and <emphasis>org.exoplatform.services.jcr.core.ExtendedNode</emphasis>, and the JCR API interface <emphasis>javax.jcr.Property</emphasis>. To add and/or remove some interfaces to monitor, you have two configuration files to change that are bundled into the jar <emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar, which are <emphasis>conf/configuration.xml</emphasis> and <emphasis>META-INF/aop.xml</emphasis>. + To enable the statistics on the JCR API accesses add the JVM parameter <emphasis>-javaagent:${pathto}/aspectjweaver-1.6.8.jar</emphasis> to your command line. </para> <para> - The file content below is the content of <emphasis>conf/configuration.xml</emphasis> that you will need to modify to add and/or remove the full qualified name of the interfaces to monitor, into the list of parameter values of the init param called <emphasis>targetInterfaces</emphasis>. + For more information refer to <ulink url="http://www.eclipse.org/aspectj/doc/released/devguide/ltw-config...;. </para> + <para> + By default, the configuration will collect statistics on all the methods of the internal interfaces <emphasis>org.exoplatform.services.jcr.core.ExtendedSession</emphasis> and <emphasis>org.exoplatform.services.jcr.core.ExtendedNode</emphasis>, and the JCR API interface <emphasis>javax.jcr.Property</emphasis>. + </para> + <para> + To add or remove some interfaces to monitor, two configuration files that are bundled into the jar <emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar need to be changed. These are; <filename>conf/configuration.xml</filename> and <filename>META-INF/aop.xml</filename>. + </para> + <para> + The file content below is the content of <emphasis>conf/configuration.xml</emphasis> that will need to be modified to add or remove the full qualified name of the interfaces to monitor into the list of parameter values of the init parameter; <emphasis>targetInterfaces</emphasis>. + </para> -<programlisting>&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"&gt; +<programlisting language="XML" role="XML"><![CDATA[<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"> - &lt;component&gt; - &lt;type&gt;org.exoplatform.services.jcr.statistics.JCRAPIAspectConfig&lt;/type&gt; - &lt;init-params&gt; - &lt;values-param&gt; - &lt;name&gt;targetInterfaces&lt;/name&gt; - &lt;value&gt;org.exoplatform.services.jcr.core.ExtendedSession&lt;/value&gt; - &lt;value&gt;org.exoplatform.services.jcr.core.ExtendedNode&lt;/value&gt; - &lt;value&gt;javax.jcr.Property&lt;/value&gt; - &lt;/values-param&gt; - &lt;/init-params&gt; - &lt;/component&gt; -&lt;/configuration&gt; -</programlisting> + <component> + <type>org.exoplatform.services.jcr.statistics.JCRAPIAspectConfig</type> + <init-params> + <values-param> + <name>targetInterfaces</name> + <value>org.exoplatform.services.jcr.core.ExtendedSession</value> + <value>org.exoplatform.services.jcr.core.ExtendedNode</value> + <value>javax.jcr.Property</value> + </values-param> + </init-params> + </component> +</configuration>]]></programlisting> + <para> - The file content below is the content of <emphasis>META-INF/aop.xml</emphasis> that you will to need to modify to add and/or remove the full qualified name of the interfaces to monitor, into the expression filter of the pointcut called <emphasis>JCRAPIPointcut</emphasis>. As you can see below, by default only JCR API calls from the exoplatform packages are took into account, don't hesistate to modify also this filter to add your own package names. + The file content below is the content of <emphasis>META-INF/aop.xml</emphasis> that will also need to be modified to add or remove interfaces to monitor in the expression filter of the pointcut called <emphasis>JCRAPIPointcut</emphasis>. </para> + <para> + Only JCR API calls from the exoplatform packages are taken into account by default. This filter can be modified to add other package names. + </para> -<programlisting>&lt;aspectj&gt; - &lt;aspects&gt; - &lt;concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect"&gt; - &lt;pointcut name="JCRAPIPointcut" - expression="(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) &amp;&amp; call(public * *(..))" /&gt; - &lt;/concrete-aspect&gt; - &lt;/aspects&gt; - &lt;weaver options="-XnoInline"&gt; - &lt;include within="org.exoplatform..*" /&gt; - &lt;/weaver&gt; -&lt;/aspectj&gt; -</programlisting> +<programlisting language="XML" role="XML"><![CDATA[<aspectj> + <aspects> + <concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect"> + <pointcut name="JCRAPIPointcut" + expression="(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) &amp;&amp; call(public * *(..))" /> + </concrete-aspect> + </aspects> + <weaver options="-XnoInline"> + <include within="org.exoplatform..*" /> + </weaver> +</aspectj>]]></programlisting> + <para> - The corresponding CSV files are of type <emphasis>Statistics${interface-name}-${creation-timestamp}.csv</emphasis> for more details about how the csv files are managed please refer to the section dedicated to the statistics manager. + The corresponding CSV files are named <filename>Statistics<replaceable>${interface-name}</replaceable>-<replaceable>${creation-timestamp}</replaceable>.csv</filename>. For more details about how the CSV files are managed please refer to the section dedicated to the statistics manager. </para> <para> - The format of each column header is ${method-alias}-${metric-alias}. The method alias will be of type ${method-name}(list of parameter types separeted by ; to be compatible with the CSV format). + The format of each column header is <replaceable>${method-alias}</replaceable>-<replaceable>${metric-alias}</replaceable>. The method alias will be of type <replaceable>${method-name}</replaceable> (a list of parameter types separated by '<emphasis role="bold">;</emphasis>' to be compatible with the CSV format). </para> <para> - The metric alias are described in the statistics manager section. + The metric aliases are described in <xref linkend="sect-Reference_Guide-eXo_JCR_statistics-Statistics_Manager"/>. </para> - <remark>Please note that this feature will affect the performances of eXo JCR so it must be used with caution.</remark> + <note> + <para> + This feature will affect the performances of eXo JCR so it must be used with caution. + </para> + </note> </section> <section id="sect-Reference_Guide-eXo_JCR_statistics-Statistics_Manager"> <title>Statistics Manager</title> <para> - The statistics manager manages all the statistics provided by eXo JCR, it is responsible of printing the data into the CSV files but also to expose the statistics through JMX and/or Rest. + The statistics manager manages all the statistics provided by eXo JCR. It is responsible for printing the data into the CSV files but also exposing the statistics through JMX or Rest, or both. </para> <para> - The statistics manager will create all the CSV files for each category of statistics that it manages, the format of those files is <emphasis>Statistics${category-name}-${creation-timestamp}.csv</emphasis>. Those files will be created into the user directory if it is possible otherwise it will create them into the temporary directory. The format of those files is <envar>CSV</envar> (i.e. Comma-Seperated Values), one new line will be added regularily (every 5 seconds by default) and one last line will be added at JVM exit. Each line, will be composed of the 5 figures described below for each method and globaly for all the methods. + The statistics manager will create all the CSV files for each category of statistics that it manages. The format of those files is <emphasis>Statistics<replaceable>${category-name}</replaceable>-<replaceable>${creation-timestamp}</replaceable>.csv</emphasis>. </para> <para> + Those files will be created in the user directory if it is possible, otherwise they will be placed into the temporary directory. The format of those files is <envar>CSV</envar> (i.e. Comma-Separated Values). One new line will be added regularly (every five seconds by default) and one last line will be added at JVM exit. Each line will be composed of the five figures described below for each method and globally for all the methods. + </para> + <table id="tabl-Reference_Guide-Statistics_Manager-Metric_Alias"> <title>Metric Alias</title> <tgroup cols="2"> <tbody> <row> <entry> - Min + <literal>Min</literal> </entry> <entry> - The minimum time spent into the method. + The minimum time spent on the method. </entry> </row> <row> <entry> - Max + <literal>Max</literal> </entry> <entry> - The maximum time spent into the method. + The maximum time spent on the method. </entry> </row> <row> <entry> - Total + <literal>Total</literal> </entry> <entry> - The total amount of time spent into the method. + The total amount of time spent on the method. </entry> </row> <row> <entry> - Avg + <literal>Avg</literal> </entry> <entry> - The average time spent into the method. + The average time spent on the method. </entry> </row> <row> <entry> - Times + <literal>Times</literal> </entry> <entry> The total amount of times the method has been called. @@ -343,75 +368,80 @@ </tbody> </tgroup> </table> - You can disable the persistence of the statistics by setting the JVM parameter called <emphasis>JCRStatisticsManager.persistence.enabled</emphasis> to <emphasis>false</emphasis>, by default it is set to <emphasis>true</emphasis>. You can aslo define the period of time between each record (i.e. line of data into the file) by setting the JVM parameter called <emphasis>JCRStatisticsManager.persistence.timeout</emphasis> to your expected value expressed in milliseconds, by default it is set to <emphasis>5000</emphasis>. + <para> + The persistence of the statistics can be disabled by setting the JVM parameter; <emphasis>JCRStatisticsManager.persistence.enabled</emphasis> to <emphasis>false</emphasis>. It is set to <emphasis>true</emphasis> by default. </para> <para> - You can also access to the statistics thanks to JMX, the available methods are the following: + The period of time between each record (i.e. line of data into the file) can be defined by setting the JVM parameter; <emphasis>JCRStatisticsManager.persistence.timeout</emphasis> to the desired value expressed in milliseconds. It is set to <emphasis>5000</emphasis> by default. </para> <para> + The statistics can also be accessed via JMX. The available methods are: + </para> + <table id="tabl-Reference_Guide-Statistics_Manager-JMX_Methods"> <title>JMX Methods</title> <tgroup cols="2"> <tbody> <row> <entry> - getMin + <literal>getMin</literal> </entry> <entry> - Gives the minimum time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of the statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. + Gives the minimum time spent on the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of the statistics (<literal>JDBCStorageConnection</literal> for example) and the name of the expected method or global for the global value. </entry> </row> <row> <entry> - getMax + <literal>getMax</literal> </entry> <entry> - Gives the maximum time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of the statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. + Gives the maximum time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of the statistics (JDBCStorageConnection for example) and the name of the expected method or global for the global value. </entry> </row> <row> <entry> - getTotal + <literal>getTotal</literal> </entry> <entry> - Gives the total amount of time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of the statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. + Gives the total amount of time spent on the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of the statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. </entry> </row> <row> <entry> - getAvg + <literal>getAvg</literal> </entry> <entry> - Gives the average time spent into the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of the statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. + Gives the average time spent on the method corresponding to the given category name and statistics name. The expected arguments are the name of the category of the statistics JDBCStorageConnection for example) and the name of the expected method or global for the global value. </entry> </row> <row> <entry> - getTimes + <literal>getTimes</literal> </entry> <entry> - Gives the total amount of times the method has been called corresponding to the given category name and statistics name. The expected arguments are the name of the category of the statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. + Gives the total amount of times the method has been called corresponding to the given category name and statistics name. The expected arguments are the name of the category of the statistics (DBCStorageConnection for example) and the name of the expected method or global for the global value. </entry> </row> <row> <entry> - reset + <literal>reset</literal> </entry> <entry> - Reset the statistics for the given category name and statistics name. The expected arguments are the name of the category of the statistics (e.g. JDBCStorageConnection) and the name of the expected method or global for the global value. + Reset the statistics for the given category name and statistics name. The expected arguments are the name of the category of the statistics JDBCStorageConnection for example) and the name of the expected method or global for the global value. </entry> </row> <row> <entry> - resetAll + <literal>resetAll</literal> </entry> <entry> - Reset all the statistics for the given category name. The expected argument is the name of the category of the statistics (e.g. JDBCStorageConnection). + Reset all the statistics for the given category name. The expected argument is the name of the category of the statistics (JDBCStorageConnection for example). </entry> </row> </tbody> </tgroup> </table> + <para> The full name of the related MBean is <emphasis>exo:service=statistic, view=jcr</emphasis>. </para> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/transaction-manager-lookup.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/transaction-manager-lookup.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/transaction-manager-lookup.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -17,7 +17,7 @@ &lt;/component&gt; </programlisting> <para> - JBossStandaloneJTAManagerLookup used in standalone environment. Bur for Application Server environment use GenericTransactionManagerLookup. + JBossStandaloneJTAManagerLookup used in standalone environment. But for Application Server environment use GenericTransactionManagerLookup. </para> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-eXoJCR"> - <title>eXoJCR</title> + <title>eXo JCR</title> <xi:include href="JCR/intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- Triaged <xi:include href="JCR/architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <!-- common configs --><xi:include href="JCR/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -219,7 +219,7 @@ </listitem> <listitem> <para> - <ulink url="http://www.vimeo.com/7255033">Episode 5: GateIn JMX Metrics and Dashboard Demo</ulink> + <ulink url="http://www.vimeo.com/8752541">Episode 5: GateIn JMX Metrics and Dashboard Demo</ulink> </para> </listitem> <listitem> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -124,8 +124,12 @@ <section id="sect-Reference_Guide-Tutorials-Deploying_your_first_Portlet"> <title>Deploying your first Portlet</title> <para> - This section describes how to deploy a portlet in &PRODUCT;. A sample portlet called <filename>SimplestHelloWorld</filename> is located in the <literal>examples</literal> directory at the root of your &PRODUCT; binary package. This sample is used in the following examples. + This section describes how to deploy a portlet in &PRODUCT;. </para> +<!-- SimpleHelloWorld does not seem to be in the product. JIRA comment by jjamrich JBEPP-276 17/May/10 + <para> + A sample portlet called <filename>SimplestHelloWorld</filename> is located in the <literal>examples</literal> directory at the root of your &PRODUCT; binary package. This sample is used in the following examples. + </para> --> <section id="sect-Reference_Guide-Deploying_your_first_Portlet-Compiling"> <title>Compiling</title> <para> @@ -134,7 +138,7 @@ <procedure> <step> <para> - Navigate to the <filename>SimplestHelloWorld</filename> directory and execute: + Navigate to the application directory and execute: </para> <programlisting>mvn package @@ -142,7 +146,7 @@ </step> <step> <para> - If the compile is successfully packaged, the result will be available in: <filename>SimplestHelloWorld/target/SimplestHelloWorld-0.0.1.war </filename>. + If the compile is successfully packaged, the result will be available in: <filename><replaceable>applicationname</replaceable>/target/<replaceable>applicationname</replaceable>-0.0.1.war </filename>. </para> </step> <step> @@ -160,14 +164,14 @@ Create a new portal page and add the portlet to it. </para> - <mediaobject> + <!-- Outdated Screenshot <mediaobject> <imageobject role="html"> <imagedata fileref="images/PortletDevelopment/Standard/first_portlet/deployed.png" format="PNG" align="center" scale="100" /> </imageobject> <imageobject role="fo"> <imagedata fileref="images/PortletDevelopment/Standard/first_portlet/deployed.png" format="PNG" align="center" contentwidth="120mm" /> </imageobject> - </mediaobject> + </mediaobject> --> </step> </procedure> @@ -224,7 +228,7 @@ <section id="sect-Reference_Guide-Deploying_your_first_Portlet-Portlet_Class"> <title>Portlet Class</title> <para> - Below is the <filename>SimplestHelloWorldPortlet/src/main/java/org/gatein/portal/examples/portlets/SimplestHelloWorldPortlet.java </filename> Java source: + Below is the Java source for an example portlet named <filename>SimplestHelloWorldPortlet/src/main/java/org/gatein/portal/examples/portlets/SimplestHelloWorldPortlet.java </filename>: </para> <programlistingco> <areaspec> @@ -398,6 +402,7 @@ </listitem> </orderedlist> +<!-- No examples in binary packages as per comment by jjamrich JIRA JBEPP-276 17/May/10 <formalpara> <title>Compiling the example</title> <para> @@ -436,12 +441,12 @@ <imageobject role="fo"> <imagedata fileref="images/PortletDevelopment/Standard/jsp_portlet/output.png" format="PNG" align="center" contentwidth="120mm" /> </imageobject> - </mediaobject> + </mediaobject> <note> <para> The <literal>EDIT</literal> button only appears for logged-in users. </para> - </note> + </note> --> <section id="sect-Reference_Guide-JavaServer_Pages_Portlet_Example-Package_Structure"> <title>Package Structure</title> <para> @@ -715,12 +720,16 @@ <para> In the third method the action phase is triggered first then the render phase is triggered, which outputs some content back to the web browser based on the available render parameters. - <mediaobject> - <imageobject> - <imagedata fileref="images/PortletDevelopment/Standard/jsp_portlet/process.png" format="PNG" scalefit="1" width="444" /> - </imageobject> - </mediaobject> </para> + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/PortletDevelopment/Standard/jsp_portlet/process.png" format="PNG" align="center" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/PortletDevelopment/Standard/jsp_portlet/process.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> + </mediaobject> + </section> <section id="sect-Reference_Guide-JavaServer_Pages_Portlet_Example-JSF_example_using_the_JBoss_Portlet_Bridge_"> @@ -729,7 +738,7 @@ In order to write a portlet using JSF a 'bridge' is needed. This software allows developers to write a portlet application as if it was a JSF application. The bridge then negotiates the interactions between the two layers. </para> <para> - An example of the JBoss Portlet Bridge is available in <filename>examples/JSFHelloUser</filename>. The configuration is slightly different from a JSP application. This example can be used as a base to configure instead of creating a new application. + An example of the JBoss Portlet Bridge is available in <filename>/portletbridge/examples/</filename>. The configuration is slightly different from a JSP application. This example can be used as a base to configure instead of creating a new application. </para> <para> As in any JSF application, the file <literal>faces-config.xml</literal> is required. It must contain the following information: Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml 2010-05-20 08:39:11 UTC (rev 3139) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml 2010-05-20 08:48:41 UTC (rev 3140) @@ -11,7 +11,7 @@ The Web Services for Remote Portlets (WSRP) specification defines a web service interface for accessing and interacting with interactive presentation-oriented web services. </para> <para> - It has been produced through the efforts of the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is based on the requirements gathered and on the concrete proposals made to the committee. + 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: @@ -31,9 +31,10 @@ <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...;. </para> +<!-- Doesn't seem to offer any more than the para above <para> - The <ulink url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr... is suggested reading for a comprehensive overview of WSRP. - </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"> @@ -42,46 +43,55 @@ 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 our WSRP Producer except that out-of-band registration is not currently handled. The WSRP component supports in-band registration and persistent local state (which are defined at the <emphasis>Complex</emphasis> level). + &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. </para> <para> - On the Consumer side, &PRODUCT_NAME; provides a <emphasis>Medium</emphasis> level of support for WSRP, except that it only handles HTML markup (as &PRODUCT_NAME; itself doesn't handle other markup types). The WSRP component does support explicit portlet cloning and the <literal>PortletManagement</literal> interface. + &PRODUCT_NAME; provides a <emphasis>Medium</emphasis> level of support for the Consumer, excepting HTML markup (as &PRODUCT_NAME; itself doesn't 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 and our Producer requires initialization of cookies (this improves interoperabilty with some consumers). + 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). </para> <para> - The WSRP component does not support custom window states or modes, as Portal doesn't either. The WSRP component does, however, support CSS on both the Producer (though it is more a function of the portlets than an inherent Producer capability) and Consumer. + &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, do need to go through the <ulink url="http://www.oasis-open.org/committees/download.php/6018">... statements</ulink> and perform more interoperability testing (an area that needs to be better supported by the WSRP Technical Committee and Community at large). - </para> --> + <para> + 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> <note> <para> - As of version &PRODUCT_VERSION; of &PRODUCT_NAME;, WSRP is only activated and supported when &PRODUCT_NAME; is deployed on JBoss Application Server. + As of version &PRODUCT_VERSION; of &PRODUCT_NAME;, WSRP is only activated and supported when &PRODUCT_NAME; is deployed on JBoss Application Server (AS). </para> </note> - <!-- - <warning> - <title>DOC TODO</title> - <para> - Replaced all references to <emphasis role="bold">we</emphasis> in this file with either references to WSRP component or EPP. Does this break the meaning? - </para> - </warning> - --> </section> <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Deploying_PRODUCT_NAMEs_WSRP_services"> <title>Deploying &PRODUCT_NAME;'s WSRP services</title> <para> - &PRODUCT_NAME; provides a complete support of WSRP 1.0 standard interfaces and offers both consumer and producer services. + &PRODUCT_NAME; provides a complete support of WSRP 1.0 standard interfaces and offers both Consumer and Producer services. </para> <note> <title>Assumptions</title> <para> - The following list asumes that &PRODUCT_NAME; has been installed into <code>$GATEIN_HOME</code>, that <code>$WSRP_VERSION</code> is the version of the WSRP component in use (at the time of the writing, it was &WSRP_VERSION;) and that <code>$PORTAL_VERSION</code> is the current &PRODUCT_NAME; version (at the time of the writing, it was &PORTAL_VERSION;). + The following list of support files assumes: </para> + <orderedlist> + <listitem> + <para> + That &PRODUCT_NAME; has been installed into <code>$GATEIN_HOME</code>. + </para> + </listitem> + <listitem> + <para> + That <code>$WSRP_VERSION</code> is the version of the WSRP component in use (at the time of the writing, it was &WSRP_VERSION;). + </para> + </listitem> + <listitem> + <para> + That <code>$PORTAL_VERSION</code> is the current &PRODUCT_NAME; version (at the time of the writing, it was &PORTAL_VERSION;). + </para> + </listitem> + </orderedlist> </note> <variablelist> @@ -152,21 +162,21 @@ </varlistentry> </variablelist> <para> - If you are not going to use WSRP in &PRODUCT_NAME;, you can remove <filename>$GATEIN_HOME/lib/gatein.portal.component.wsrp-$PORTAL_VERSION.jar</filename> from your &PRODUCT_NAME; distribution to deactivate WSRP support. + If WSRP is not going to be used in &PRODUCT_NAME;, the <filename>$GATEIN_HOME/lib/gatein.portal.component.wsrp-$PORTAL_VERSION.jar</filename> can be removed from &PRODUCT_NAME; distribution 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> <para> - JBoss WS (the web service stack that &PRODUCT_NAME; uses) should update the port and host name used in WSDL. See 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_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. </para> <para> - If you have modified the host name and port on which your server runs, you will need to update the configuration for the consumer used to consume &PRODUCT_NAME;'s 'self' producer. Please refer to the <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME" /> to learn how to do so. + If the host name and port on which the server runs have been modified, the configuration for the Consumer used to consume &PRODUCT_NAME;'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_in_PRODUCT_NAME" /> to learn 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> <para> - It is possible to use WSRP over SSL for secure exchange of data. Please refer to the <ulink url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu... on how to do so. + 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> @@ -181,14 +191,15 @@ 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> - This is accomplished by using a specific <code>org.gatein.pc.remotable container-runtime-option</code>. Setting its value to <code>true</code> makes the portlet available for remote consumption, while setting its value to <code>false</code> will not publish it remotely. + 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. </para> <para> - As specifying the remotable status for a portlet is optional, you do not need to do anything if you do not need your portlet to be available remotely. + 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 "BasicPortlet" portlet is specified as being remotable. </para> + <programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" standalone="yes"?> <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -206,6 +217,7 @@ </container-runtime-option> </portlet> </portlet-app>]]></programlisting> + <para> It is also possible to specify that all the portlets declared within a given portlet application be remotable by default. </para> @@ -215,6 +227,7 @@ <para> For example: </para> + <programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" standalone="yes"?> <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -241,18 +254,19 @@ </container-runtime-option> </portlet-app> ]]></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;'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_NAME;'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> -<!-- Mark --> + <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>. </para> <para> - The<varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely exposed. + The <varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely exposed. </para> <note> <para> @@ -264,16 +278,16 @@ <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_PRODUCT_NAMEs_WSRP_portlets_from_a_remote_Consumer"> <title>Consuming &PRODUCT_NAME;'s 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's WSDL definition. + 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_NAME; 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;, please 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_NAME;, refer to <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME" />. </para> <para> &PRODUCT_NAME;'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 8080. + 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>. </para> </section> @@ -281,7 +295,7 @@ <title>Consuming remote WSRP portlets in &PRODUCT_NAME;</title> <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Overview"><title>Overview</title> <para> - To be able to consume WSRP portlets exposed by a remote producer, &PRODUCT_NAME;'s WSRP consumer needs to know how to access that remote producer. + To be able to consume WSRP portlets exposed by a remote producer, &PRODUCT_NAME;'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. @@ -297,134 +311,248 @@ <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Configuring_a_remote_producer"> <title>Configuring a remote producer</title> <para> - You need to define access to a remote producer so that its portlets can be consumed within &PRODUCT_NAME;. The WSRP component configures access to Oracle's public WSRP producer. First, it determines how to do so using the configuration portlet. It then shows 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_NAME;. 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> + Oracle does not support chunked encoding. Therefore if <emphasis role="bold">Oracle</emphasis>'s WSDL is used as a producer the following error will occur: + </para> + +<screen>05:15:32,125 ERROR [SOAPFaultHelperJAXWS] SOAP request exception +java.io.IOException: Could not transmit message + at org.jboss.ws.core.client.HTTPRemotingConnection.invoke(HTTPRemotingConnection.java:265) + at org.jboss.ws.core.client.SOAPProtocolConnectionHTTP.invoke(SOAPProtocolConnectionHTTP.java:71) + at org.jboss.ws.core.CommonClient.invoke(CommonClient.java:340) + at org.jboss.ws.core.jaxws.client.ClientImpl.invoke(ClientImpl.java:290) + +.......... +Caused by: org.jboss.remoting.CannotConnectException: Can not connect http client invoker after 1 attempt(s) + at org.jboss.remoting.transport.http.HTTPClientInvoker.makeInvocation(HTTPClientInvoker.java:249) + at org.jboss.remoting.transport.http.HTTPClientInvoker.transport(HTTPClientInvoker.java:161) + at org.jboss.remoting.MicroRemoteClientInvoker.invoke(MicroRemoteClientInvoker.java:165) + at org.jboss.remoting.Client.invoke(Client.java:1724) + at org.jboss.remoting.Client.invoke(Client.java:629) + at org.jboss.ws.core.client.HTTPRemotingConnection.invoke(HTTPRemotingConnection.java:243) + ... 135 more +Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] - Service Unavailable + at org.jboss.ws.core.soap.SOAPMessageUnMarshallerHTTP.read(SOAPMessageUnMarshallerHTTP.java:75) + at org.jboss.remoting.transport.http.HTTPClientInvoker.readResponse(HTTPClientInvoker.java:570) +</screen> + <para> + A workaround for this issue involves editing the chunksize setting in the <filename>standard-jaxws-client-config.xml</filename> file. + </para> + <para> + 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_walk_through-Using_the_configuration_portlet"> <title>Using the configuration portlet</title> <para> - &PRODUCT_NAME; provides a portlet to configure access (among other functions) to remote WSRP Producers grahically. It isn't, however, installed by default, so the first thing the WSRP component will need to do is to install the WSRP configuration portlet using the Application Registry. + &PRODUCT_NAME; provides a portlet to configure access (among other functions) to remote WSRP Producers grahically. This portlet isn'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/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&amp;username=root&amp;password=gtn">here</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> - Use the usual procedure to log in as a Portal administrator and go to the Application Registry. With the default install, you can just go to <ulink url="http://localhost:8080/portal/private/classic/administration/registry">http://localhost:8080/portal/private/classic/administration/registry</ulink>. Add the WSRP Configuration portlet to the Administration category. If you use the Import Applications functionality, the WSRP Configuration portlet will be automatically added to the Administration category. + 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> - Now that the portlet is added to a category, it can be added to a page and used. The WSRP component recommend adding it to the same page as the Application Registry as operations relating to WSRP and adding portlets to categories are somewhat related as the WSRP component will see. Go ahead and add the WSRP Configuration portlet to the page using the standard procedure. + <emphasis role="bold">The WSRP Configuration portlet</emphasis>: </para> - <para> - If all went well, you should see something similar to this: - </para> <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/config_init.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/config_init.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/config_init.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> <para> - This screen presents all the configured consumers associated with their status and possible actions on them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. Note also that a Consumer can be marked as requiring refresh meaning that the information held about it might not be up to date and refreshing it from the remote Producer might be a good idea. This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information. + This screen presents all the configured consumers associated with their status and possible actions on them. </para> <para> - Next, the WSRP component create a new Consumer which the WSRP component will call <literal>oracle</literal>. Type "<literal> oracle</literal>" in the "Create a consumer named:" field then click on "Create consumer": + A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/config_create.png" format="PNG" scalefit="1" valign="middle" width="444" /> - </imageobject> - </mediaobject> <para> - You should now see a form allowing you to enter/modify the information about the Consumer. Set the cache expiration value to 300 seconds, leave the default timeout value for web services (WS) operations and enter the WSDL URL for the producer in the text field and press the "Refresh &amp; Save" button: + 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 "<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 fileref="images/WSRP/config_create.png" format="PNG" align="center" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/config_create.png" format="PNG" align="center" contentwidth="140mm" /> + </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 fileref="images/WSRP/config_wsdl.png" format="PNG" align="center" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/config_wsdl.png" format="PNG" align="center" contentwidth="140mm" /> + </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> - <imagedata align="center" fileref="images/WSRP/config_wsdl.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/config_refresh.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/config_refresh.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> <para> - This will retrieve the service description associated with the Producer which WSRP interface is described by the WSDL file found at the URL you just entered. In our case, querying the service description will allow us to learn that the Producer requires registration but didn't request any registration property: - </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/config_refresh.png" format="PNG" scalefit="1" valign="middle" 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> - Now, assuming that the producer required a value for an <literal>email</literal> registration property, &PRODUCT_NAME;'s WSRP consumer would have informed you that you were missing some information: + Assuming that the producer required a value for an <literal>email</literal> registration property, &PRODUCT_NAME;'s WSRP consumer will report that some information was missing: </para> <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/config_missing.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/config_missing.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/config_missing.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> + <note> + <title>Values</title> <para> - At this point, there is no automated way to learn about which possible values (if any) are expected by the remote Producer. Sometimes, the possible values will be indicated in the registration property description but this is not always the case... Please refer to the specific Producer's documentation. + 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's documentation. </para> </note> <para> - If you entered &quot;&lt;literal&gt;example(a)example.com&lt;/literal&gt;&quot; as the value for the registration property and press "Save &amp; Refresh" once more, you would have seen something similar to: + Entered 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> - <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/config_end.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/config_end.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> + </section> + <section id="sect-Reference_Guide-Configuring_a_remote_producer_walk_through-Using_XML"> <title>Using XML</title> <para> - While the WSRP component recommend you use the WSRP Configuration portlet to configure Consumers, The WSRP component provide an alternative way to configure consumers by editing the XML file located at <filename>$GATEIN_HOME/lib/wsrp-consumer-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename>. + Although using the WSRP Configuration portlet to configure Consumers is recommended, the WSRP component provides an alternative way to configure consumers. </para> + <para> + This is done by editing the XML file located at <filename>$GATEIN_HOME/lib/wsrp-consumer-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename>. + </para> -<programlisting role="XML"> -&lt;?xml version='1.0' encoding='UTF-8' ?&gt; -&lt;deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" +<programlisting language="XML" role="XML"><![CDATA[<?xml version='1.0' encoding='UTF-8' ?> +<deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"&gt; - &lt;deployment&gt; - &lt;wsrp-producer id="self" expiration-cache="300" ws-timeout="30000"&gt; - &lt;endpoint-wsdl-url&gt;http://localhost:8080/wsrp-producer/MarkupService?wsdl&lt;/endpoint-wsdl-url&gt; - &lt;registration-data&gt; - &lt;property&gt; - &lt;name&gt;email&lt;/name&gt; - &lt;lang&gt;en&lt;/lang&gt; - &amp;lt;value&amp;gt;example(a)example.com&amp;lt;/value&amp;gt; - &lt;/property&gt; - &lt;/registration-data&gt; - &lt;/wsrp-producer&gt; - &lt;/deployment&gt; - &lt;deployment&gt; - &lt;wsrp-producer id="oracle" expiration-cache="300"&gt; - &lt;endpoint-wsdl-url&gt;http://portalstandards.oracle.com/portletapp/portlets?WSDL&lt;/endpoint-wsdl-url&gt; - &lt;registration-data/&gt; - &lt;/wsrp-producer&gt; - &lt;/deployment&gt; -&lt;/deployments&gt; -</programlisting> + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> + <deployment> + <wsrp-producer id="self" expiration-cache="300" ws-timeout="30000"> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/MarkupService?wsdl</endpoint-wsdl-url> + <registration-data> + <property> + <name>email</name> + <lang>en</lang> + <value&gt;example(a)example.com&lt;/value&gt; + </property> + </registration-data> + </wsrp-producer> + </deployment> + <deployment> + <wsrp-producer id="oracle" expiration-cache="300"> + <endpoint-wsdl-url>http://portalstandards.oracle.com/portletapp/portlet... + <registration-data/> + </wsrp-producer> + </deployment> +</deployments>]]></programlisting> <para> - The file as shown above specifies access to two producers: <literal>self</literal>, which consumes &PRODUCT_NAME;'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 walk-through above. + The file as shown above specifies access to two producers: <literal>self</literal>, which consumes &PRODUCT_NAME;'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> - <para> - The WSRP component will look at the details of the meaning of elements later on. - </para> + <note> + <para> + An XML Schema defining which elements are available to configure Consumers via XML can be found in <filename> $GATEIN_HOME/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> + </para> + </note> </section> <section id="sect-Reference_Guide-Configuring_a_remote_producer_walk_through-Configuring_access_to_a_remote_portlet"> <title>Configuring access to a remote portlet</title> <para> - If the WSRP component go back to the Application Registry and examine the available portlets by clicking on the Portlet link, you will now be able to see the remote portlets if you click on the REMOTE tab in the left column: + 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> - <imagedata align="center" fileref="images/WSRP/remote_portlets.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/remote_portlets.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/remote_portlets.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> + <para> - These portlets are, of course, available to be used such as regular portlets: they can be used in categories and added to pages. If you use the Import Applications functionality, they will also be automatically imported in categories based on the keywords they define. + These portlets are available to be used as regular portlets: they can be used in categories and added to pages. Using the Import Applications functionality will also automatically import them into categories based on the keywords they define. </para> <para> - More specifically, if you want to add a WSRP portlet to a category, you can access these portlets by selecting <literal>wsrp</literal> in the Application Type drop-down menu: + More specifically, to add a <emphasis>WSRP</emphasis> portlet to a category, select <literal>wsrp</literal> in the Application Type drop-down menu: </para> <mediaobject> <imageobject> @@ -435,33 +563,58 @@ </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> + <title>Configuring access to remote Producers via XML</title> <para> - While the WSRP component recommend you use the WSRP Configuration portlet to configure Consumers, the WSRP component provide an alternative way to configure consumers by editing the XML file located at <filename>$GATEIN_HOME/lib/wsrp-consumer-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename>. + Although using the WSRP Configuration portlet to configure Consumers is recommended, the WSRP component provides an alternative way to configure consumers. </para> + <para> + This is done by editing the XML file located at <filename>$GATEIN_HOME/lib/wsrp-consumer-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename>. + </para> + <note> + <title>XML Elements</title> <para> An XML Schema defining which elements are available to configure Consumers via XML can be found in <filename> $GATEIN_HOME/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> </para> </note> <note> + <title>The Consumer Configuration file</title> <para> - It is important to note how the XML consumers configuration file is processed. It is read the first time the WSRP service starts and the associated information is then put under control of JCR (Java Content Repository). Subsequent launches of the WSRP service will use the JCR-stored information for all producers are already known to &PRODUCT_NAME;. More specifically, <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. The information defined at the XML level is only processed for producer definition for which no information is already present in JCR. Therefore, if you wish to delete a producer configuration, you need to delete the associated information in the database (this can be accomplished using the configuration portlet as the WSRP component saw in <xref linkend="sect-Reference_Guide-Configuring_a! _remote_producer_walk_through-Using_the_configuration_portlet" />) and remove the associated information in <filename>wsrp-consumers-config.xml</filename> (if such information exists) as the producer will be re-created the next time the WSRP is launched if that information is not removed. + 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. + </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_walk_through-Using_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> <para> - Some information needs to be provided to configure access to a remote producer. + The following information needs to be provided to configure access to a remote Producer: </para> + <orderedlist> + <listitem> + <para> + An identifier must be provided for the producer being configured so that it can be referred to later. This is done in the mandatory <literal>id</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element. + </para> + </listitem> + <listitem> + <para> + &PRODUCT_NAME; 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>&lt;endpoint-wsdl-url&gt;</literal> element to specify the URL for the WSDL description of the remote WSRP service. + </para> + </listitem> + </orderedlist> + <para> - First, the WSRP component need to provide an identifier for the producer the WSRP component are configuring so that the WSRP component can refer to it afterwards. This is accomplished via the mandatory <literal>id</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element. - </para> - <para> - &PRODUCT_NAME; also needs to learn about the remote producer's endpoints to be able to connect to the remote web services and perform WSRP invocations. This is accomplished by specifying the URL for the WSDL description for the remote WSRP service, using the <literal>&lt;endpoint-wsdl-url&gt;</literal> element. - </para> - <para> Both the <literal>id</literal> attribute and <literal>&lt;endpoint-wsdl-url&gt;</literal> elements are required for a functional remote producer configuration. </para> </section> @@ -469,75 +622,104 @@ <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 addtional configuration, which, in some cases, might be important to establish a proper connection to the remote producer. + 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> - <para> - One such optional configuration concerns caching. To prevent useless roundtrips between the local consumer and the remote producer, it is possible to cache some of the information sent by the producer (such as the list of offered portlets) for a given duration. The rate at which the information is refreshed is defined by the <literal>expiration-cache</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element which specifies the refreshing period in seconds. For example, providing a value of 120 for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been somehow accessed. If no value is provided, &PRODUCT_NAME; will always access the remote producer regardless of whether the remote information has changed or not. Since, in most instances, the information provided by the producer does not change often, the WSRP component recommend that you use this caching facility to minimize bandwidth usage. - </para> - <para> - It is also possible to define a timeout after which WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, waiting forever on the service that doesn't answer. Use the <literal>ws-timeout</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element to specify how many milliseconds the WSRP service will wait for a response from the remote producer before timing out and giving up. - </para> - <para> - Additionally, some producers require consumers to register with them before authorizing them to access their offered portlets. If you know that information beforehand, you can provide the required registration information in the producer configuration so that the consumer can register with the remote producer when required. - </para> - <note> - <para> - At this time, though, only simple String properties are supported and it is not possible to configure complex registration data. This should, however, be sufficient for most cases. - </para> - </note> - <para> - Registration configuration is done via the <literal>&lt;registration-data&gt;</literal> element. Since &PRODUCT_NAME; can generate the mandatory information for you, if the remote producer does not require any registration properties, you only need to provide an empty <literal>&lt;registration-data&gt;</literal> element. Values for the registration properties required by the remote producer can be provided via <literal>&lt;property&gt;</literal> elements. See the example below for more details. Additionally, you can override the default consumer name automatically provided by &PRODUCT_NAME; via the <literal>&lt;consumer-name&gt;</literal> element. If you choose to provide a consumer name, please remember that this should uniquely identify your consumer. - </para> + + <variablelist> + <title>Optional Configurations</title> + <varlistentry> + <term>Caching</term> + <listitem> + <para> + To prevent unnecessary traffic between the local consumer and the remote producer, it is possible to cache some of the information sent by the producer (such as the list of offered portlets) for a given duration. + </para> + <para> + The rate at which the information is refreshed is defined by the <literal>expiration-cache</literal> attribute of the <literal>&lt;wsrp-producer&gt;</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. + </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>&lt;wsrp-producer&gt;</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> + <para> + Some producers require consumers to register with them before authorizing them to access their offered portlets. If known, some registration information can be provided in the producer configuration beforehand, so that the consumer can register with the remote producer when required. + </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. + </para> + </note> + <para> + This pre-registration configuration is done via the <literal>&lt;registration-data&gt;</literal> element. + </para> + <para> + If the remote producer does not require any registration properties, only an empty <literal>&lt;registration-data&gt;</literal> element need be provided, as &PRODUCT_NAME; can generate the mandatory information. + </para> + <para> + Values for the registration properties required by the remote producer can be provided via <literal>&lt;property&gt;</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>&lt;consumer-name&gt;</literal> element. When providing a consumer name, please remember that it should uniquely identify your consumer. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> </section> <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Examples"> <title>Examples</title> <para> - Here 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. + 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: </para> - <example> - <title>default-wsrp.xml</title> -<programlisting> -&lt;?xml version='1.0' encoding='UTF-8' ?&gt; -&lt;deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" +<programlisting language="XML" role="XML"><![CDATA[<?xml version='1.0' encoding='UTF-8' ?> +<deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"&gt; - &lt;deployment&gt; - &lt;wsrp-producer id="self" expiration-cache="300" ws-timeout="30000"&gt; - &lt;endpoint-wsdl-url&gt;http://localhost:8080/wsrp-producer/MarkupService?wsdl&lt;/endpoint-wsdl-url&gt; - &lt;registration-data/&gt; - &lt;/wsrp-producer&gt; - &lt;/deployment&gt; -&lt;/deployments&gt; -</programlisting> - </example> + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> + <deployment> + <wsrp-producer id="self" expiration-cache="300" ws-timeout="30000"> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/MarkupService?wsdl</endpoint-wsdl-url> + <registration-data/> + </wsrp-producer> + </deployment> +</deployments> +]]></programlisting> <para> - Here is an example of a WSRP descriptor with registration data and cache expiring every minute: + This is an example of a WSRP descriptor with registration data and cache expiring every minute: </para> - <example> - <title>WSRP Descriptor</title> -<programlisting> -&lt;?xml version='1.0' encoding='UTF-8' ?&gt; -&lt;deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" +<programlisting language="XML" role="XML"><![CDATA[<?xml version='1.0' encoding='UTF-8' ?> +<deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"&gt; -&lt;deployments&gt; - &lt;deployment&gt; - &lt;wsrp-producer id="AnotherProducer" expiration-cache="60"&gt; - &lt;endpoint-wsdl-url&gt;http://example.com/producer/producer?WSDL&lt;/endpoint-wsdl-url&gt; - &lt;registration-data&gt; - &lt;property&gt; - &lt;name&gt;property name&lt;/name&gt; - &lt;lang&gt;en&lt;/lang&gt; - &lt;value&gt;property value&lt;/value&gt; - &lt;/property&gt; - &lt;/registration-data&gt; - &lt;/wsrp-producer&gt; - &lt;/deployment&gt; -&lt;/deployments&gt; -</programlisting> - </example> + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> +<deployments> + <deployment> + <wsrp-producer id="AnotherProducer" expiration-cache="60"> + <endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoi... + <registration-data> + <property> + <name>property name</name> + <lang>en</lang> + <value>property value</value> + </property> + </registration-data> + </wsrp-producer> + </deployment> +</deployments> +]]></programlisting> + </section> </section> @@ -553,67 +735,126 @@ Producers often offer several levels of service depending on consumers' subscription levels (for example). This is implemented at the WSRP level with the registration concept: producers can assert which level of service to provide to consumers based on the values of given registration properties. </para> <para> - There might also be cases where you just want to update the registration information because it has changed. For example, the producer required you to provide a valid email and the previously email address is not valid anymore and needs to be updated. + 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. </para> <para> - It is therefore sometimes necessary to modify the registration that concretizes the service agreement between a consumer and a producer. Let's take the example of the producer requiring an email the WSRP component configured in <xref linkend="sect-Reference_Guide-Configuring_a_remote_producer_walk_through-Using_the_configuration_portlet" />. If you recall, the producer was requiring registration and required a value to be provided for the <literal>email</literal> property. + 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_walk_through-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. </para> <para> - Suppose now that the WSRP component would like to update the email address that the WSRP component provided to the remote producer. The WSRP component will need to tell the producer that our registration data has been modified. Let's see how to do this. Assuming you have configured access to the producer as previously described, please go to the configuration screen for the <literal>self</literal> producer and modify the value of <literal>email</literal> to <literal&gt;foo(a)example.com&lt;/literal&gt; instead of&lt;literal&gt;example(a)example.com&lt;/literal&gt;: + To update the email address that was provided, the remote producer must be informed that some registration data has been modified. </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/modify_reg_start.png" format="PNG" scalefit="1" valign="middle" width="444" /> - </imageobject> - </mediaobject> <para> - Now click on "Update properties" to save the change. A "Modify registration" button should now appear to let you send this new data to the remote producer: + The following procedure assumes access to the producer has been configured as previously described. </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/modify_reg_modify.png" format="PNG" scalefit="1" valign="middle" width="444" /> - </imageobject> - </mediaobject> - <para> - Click on this new button and, if everything went well and your updated registration has been accepted by the remote producer, you should see something similar to: - </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/modify_reg_end.png" format="PNG" scalefit="1" valign="middle" width="444" /> - </imageobject> - </mediaobject> + <procedure> + <step> + <para> + Go to the configuration screen for the <literal>self</literal> producer and change the value of <literal>email</literal> to <literal&gt;foo(a)example.com&lt;/literal&gt; instead of&lt;literal&gt;example(a)example.com&lt;/literal&gt;: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/WSRP/modify_reg_start.png" format="PNG" align="center" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/modify_reg_start.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> + </mediaobject> + </step> + <step> + <para> + 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 fileref="images/WSRP/modify_reg_modify.png" format="PNG" align="center" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/modify_reg_modify.png" format="PNG" align="center" contentwidth="140mm" /> + </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: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/WSRP/modify_reg_end.png" format="PNG" align="center" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/modify_reg_end.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> + </mediaobject> + </step> + </procedure> </section> <section id="sect-Reference_Guide-Modifying_a_currently_held_registration-Registration_modification_on_producer_error"> - <title>Registration modification on producer error</title> + <title>Registration modification on Producer error</title> <para> - It can also happen that a producer administrator decided to change its requirement for registered consumers. In this case, invoking operations on the producer will fail with an <exceptionname>OperationFailedFault</exceptionname>. &PRODUCT_NAME; will attempt to help you in this situation. Let's walk through an example using the <literal>self</literal> producer. Let's assume that registration is requiring a valid value for an <literal>email</literal> registration property (as the WSRP component have seen so far). If you go to the configuration screen for this producer, you should see: + 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. </para> + <para> + This section will discuss an example using the <literal>self</literal> producer. + </para> + <para> + Assuming that the registration requires a valid value for an <literal>email</literal> registration property (as has been shown) the configuration screen for this producer should show: + </para> <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/config_self.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/config_self.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/config_self.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> + <para> - Now suppose that the administrator of the producer now additionaly requires a value to be provided for a <literal>name</literal> registration property. The WSRP component will actually see how to do perform this operation in &PRODUCT_NAME; when the WSRP component examine how to configure &PRODUCT_NAME;'s producer in <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Configuring_PRODUCT_NAMEs_WSRP_Producer" />. Operations with this producer will now fail. If you suspect that a registration modification is required, you should go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing "Refresh &amp; Save": + 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 "<emphasis role="bold">Refresh &amp; Save</emphasis>": + </para> <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/modify_reg_self.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/modify_reg_self.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/modify_reg_self.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> + <para> - As you can see, the configuration screen now shows the currently held registration information and the expected information from the producer. Enter a value for the <literal>name</literal> property and then click on "Modify registration". If all went well and the producer accepted your new registration data, you should see something similar to: + 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 "<emphasis role="bold">Modify registration</emphasis>". If the producer accepts the new registration data, the following screen will appear: + </para> <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/modify_reg_self_end.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/modify_reg_self_end.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> + <note> <para> - As of WSRP 1, it is rather difficult to ascertain for sure what caused an <exceptionname>OperationFailedFault</exceptionname> as it is the generic exception returned by producers if something didn't quite happen as expected during a method invocation. This means that <exceptionname>OperationFailedFault</exceptionname> can be caused by several different reasons, one of them being a request to modify the registration data. Please take a look at the log files to see if you can gather more information as to what happened. WSRP 2 introduces an exception that is specific to a request to modify registrations thus reducing the ambiguity that currently exists. + 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. </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. + </para> + <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> @@ -625,63 +866,98 @@ Several operations are available from the consumer list view of the WSRP configuration portlet: </para> <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/consumer_operations.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/consumer_operations.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/consumer_operations.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> + <para> The available operations are: </para> - <itemizedlist> + <variablelist> + <varlistentry> + <term>Configure</term> <listitem> <para> - Configure: displays the consumer details and allows user to edit them + Displays the consumer details and allows user to edit them. </para> </listitem> - <listitem> - <para> - Refresh: forces the consumer to retrieve the service description from the remote producer to refresh the local information (offered portlets, registration information, etc.) - </para> - </listitem> - <listitem> - <para> - Activate/Deactivate: activates/deactivates a consumer, governing whether it will be available to provide portlets and receive portlet invocations - </para> - </listitem> - <listitem> - <para> - Register/Deregister: registers/deregisters a consumer based on whether registration is required and/or acquired - </para> - </listitem> - <listitem> - <para> - Delete: destroys the consumer, after deregisterting it if it was registered - </para> - </listitem> - </itemizedlist> - + </varlistentry> + <varlistentry> + <term>Refresh</term> + <listitem> + <para> + Forces the consumer to retrieve the service description from the remote producer to refresh the local information (such as offered portlets, registration information). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Activate/Deactivate</term> + <listitem> + <para> + Activates or deactivates a consumer, governing whether it will be available to provide portlets and receive portlet invocations. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Register/Deregister</term> + <listitem> + <para> + Registers or deregisters a consumer based on whether registration is required and/or acquired. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Delete</term> + <listitem> + <para> + Destroys the consumer, after deregisterting it if it was registered. + </para> + </listitem> + </varlistentry> + </variablelist> </section> <section id="sect-Reference_Guide-Consumers_maintenance-Erasing_local_registration_data"> <title>Erasing local registration data</title> <para> - There are rare cases where it might be required to erase the local information without being able to deregister first. This is the case when a consumer is registered with a producer that has been modified by its administrator to not require registration anymore. If that ever was to happen (most likely, it won't), you can erase the local registration information from the consumer so that it can resume interacting with the remote producer. To do so, click on "Erase local registration" button next to the registration context information on the consumer configuration screen: + In rare cases, it may be necessary to erase the local data without being able to de-register first. </para> + <para> + 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. + </para> + <para> + 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> - <imagedata align="center" fileref="images/WSRP/erase_registration.png" format="PNG" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/erase_registration.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/erase_registration.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> + <warning> <para> - This operation is dangerous as it can result in inability to interact with the remote producer if invoked when not required. A warning screen will be displayed to give you a chance to change your mind: + This operation is dangerous as it can result in inability to interact with the remote producer if invoked when not required. The warning message below will be displayed before any data is erased. </para> + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/WSRP/erase_registration_warning.png" format="PNG" align="center" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/erase_registration_warning.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> + </mediaobject> </warning> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/erase_registration_warning.png" format="PNG" valign="middle" width="444" /> - </imageobject> - </mediaobject> + </section> </section> @@ -691,84 +967,149 @@ <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Overview"> <title>Overview</title> <para> - You can configure the behavior of Portal's WSRP Producer by using the WSRP administration interface, which is the preferred way, or by editing the <filename>$GATEIN_HOME/wsrp-producer.war/WEB-INF/conf/producer/config.xml</filename> file. Several aspects can be modified with respects to whether registration is required for consumers to access the Producer's services. An XML Schema for the configuration format is available at <filename> $GATEIN_HOME/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename>. + 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>$GATEIN_HOME/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's services. An XML Schema for the configuration format is available at <filename> $GATEIN_HOME/lib/wsrp-integration-api-$WSRP_VERSION.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> <para> - The default producer configuration is to require that consumers register with it before providing access its services but does not require any specific registration properties (apart from what is mandated by the WSRP standard). It does, however, require consumers to be registered before sending them a full service description. This means that our WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. The producer also uses the default <classname>RegistrationPolicy</classname> paired with the default <classname>RegistrationPropertyValidator</classname>. The WSRP component will look into property validators in greater detail later in<xref linkend="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Registration_configuration" />. Suffice to say for now that this allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not. + 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). </para> <para> - &PRODUCT_NAME; provides a web interface to configure the producer's behavior. You can access it by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. Here's what you should see with the default configuration: + It does, however, require consumers to be registered before sending them a full service description. This means that the WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. </para> + <para> + The producer also uses the default <classname>RegistrationPolicy</classname> paired with the default <classname>RegistrationPropertyValidator</classname>. + </para> + <para> + 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_PRODUCT_NAMEs_WSRP_Producer-Registration_configuration" />). + </para> + <para> + &PRODUCT_NAME; 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> - <imagedata align="center" fileref="images/WSRP/producer_default.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/producer_default.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/producer_default.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> + <para> - As would be expected, you can specify whether or not the producer will send the full service description to unregistered consumers, and, if it requires registration, which <classname>RegistrationPolicy</classname> to use (and, if needed, which <classname>RegistrationPropertyValidator</classname>), along with required registration property description for which consumers must provide acceptable values to successfully register. + Administrators can specify whether or not a producer which requires registration will send the full service description to unregistered consumers. </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> <para> - In order to require consumers to register with Portal's producer before interacting with it, you need to configure Portal's behavior with respect to registration. Registration is optional, as are registration properties. The producer can require registration without requiring consumers to pass any registration properties as is the case in the default configuration. Let's configure our producer starting with a blank state: + In order to have consumers register with Portal's producer the Portal's behavior with respect to registration must be configured. </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/producer_blank.png" format="PNG" scalefit="1" valign="middle" width="444" /> - </imageobject> - </mediaobject> <para> - The WSRP component will allow unregistered consumers to see the list of offered portlets so the WSRP component leave the first checkbox ("Access to full service description requires consumers to be registered.") unchecked. The WSRP component will, however, specify that consumers will need to be registered to be able to interact with our producer. Check the second checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer registrations."). The screen should now refresh and display: + 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's registration behavior from a blank state: + </para> <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/producer_registration.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/producer_blank.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/producer_blank.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> - <para> - You can specify the fully-qualified name for your <classname>RegistrationPolicy</classname> and <classname>RegistrationPropertyValidator</classname> there. The WSRP component will keep the default value. See <xref linkend="sect-Reference_Guide-Registration_configuration-Customization_of_Registration_handling_behavior" /> for more details. Let's add, however, a registration property called <literal>email</literal>. Click "Add property" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to figure out its purpose: - </para> + + <procedure> + <step> + <para> + 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 ("<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> - <imagedata align="center" fileref="images/WSRP/producer_email.png" format="PNG" scalefit="1" valign="middle" width="444" /> + <imageobject role="html"> + <imagedata fileref="images/WSRP/producer_registration.png" format="PNG" align="center" scale="100" /> </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/producer_registration.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> </mediaobject> - <para> - Press "Save" to record your modifications. - </para> + </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. + </para> + </step> + <step> + <para> + To add a registration property called <literal>email</literal> click "A<emphasis role="bold">dd 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 fileref="images/WSRP/producer_email.png" format="PNG" align="center" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/WSRP/producer_email.png" format="PNG" align="center" contentwidth="140mm" /> + </imageobject> + </mediaobject> + </step> + <step> + <para> + 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 (xsd:string) properties are supported. <!--If your application requires more complex properties, please let us know.--> </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 WSRP component saw the consumer side of that process 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> <para> - Registration handling behavior can be customized by users to suit their Producer needs. This is accomplished by providing an implementation of the <classname>RegistrationPolicy</classname> interface. This interface defines methods that are called by Portal's Registration service so that decisions can be made appropriately. A default registration policy that provides basic behavior is provided and should be enough for most user needs. + 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> - While the default registration policy provides default behavior for most registration-related aspects, there is still one aspect that requires configuration: whether a given value for a registration property is acceptable by the WSRP Producer. This is accomplished by plugging a <classname>RegistrationPropertyValidator</classname> in the default registration policy. This allows users to define their own validation mechanism. + 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> - Please 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. + 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. </para> <para> - Defining a registration policy is required for the producer to be correctly configured. This is accomplished by specifying the qualified class name of the registration policy. Since the WSRP component anticipate that most users will use the default registration policy, it is possible to provide the class name of your custom property validator instead to customize the default registration policy behavior. Note that property validators are only used by the default policy. + 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. + </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. + </para> <note> <para> - Since the policy or the validator are defined via their class name and dynamically loaded, it is important that you make sure that the identified class is available to the application server. One way to accomplish that is to deploy your policy implementation as JAR file in your AS instance deploy 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. 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. </para> </note> </section> @@ -777,10 +1118,10 @@ <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_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. The WSRP component have experienced such issues and have introduced a way to relax the validation that our WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. Note that the WSRP component only relax our validation algorithm 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. 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. </para> <para> - By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you might want to try to relax the validation mode. This is accomplished by unchecking the "Use strict WSRP compliance." checkbox on the Producer configuration screen. + By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you might want to try to relax the validation mode. This is accomplished by unchecking the "Use strict WSRP compliance" checkbox on the Producer configuration screen. </para> </section> </section>