Author: smumford Date: 2010-11-10 02:00:09 -0500 (Wed, 10 Nov 2010) New Revision: 5000 Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/Middleware_Feedback.xml epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/Reference_Guide.ent epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/modules/WSRP.xml Log: JBEPP-517: Added first changes for WSRP 2 content Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/Middleware_Feedback.xml =================================================================== --- epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/Middleware_Feedback.xml 2010-11-10 06:08:36 UTC (rev 4999) +++ epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/Middleware_Feedback.xml 2010-11-10 07:00:09 UTC (rev 5000) @@ -15,7 +15,7 @@ These entities should not affect translated documents, since Bugzilla is not localised. --><title>Give us Feedback</title> <para> - If you find a typographical error, or know how this guide can be improved, we would love to hear from you. Submit a report in Bugzilla against the product <literal>&PRODUCT_NAME;</literal>. The following link will take you to a pre-filled bug report for this book: <ulink url="https://bugzilla.redhat.com/enter_bug.cgi?product=JBoss%20Enter...;. + If you find a typographical error, or know how this guide can be improved, we would love to hear from you. Submit a report in Bugzilla against the product <literal>&PRODUCT;</literal>. The following link will take you to a pre-filled bug report for this book: <ulink url="https://bugzilla.redhat.com/enter_bug.cgi?product=JBoss%20Enter...;. </para> <!-- <para> Fill out the following template and add it to Bugzilla's <literal>Description</literal> field. Be as specific as possible when describing the issue; this will help ensure that we can fix it quickly. Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/Reference_Guide.ent =================================================================== --- epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/Reference_Guide.ent 2010-11-10 06:08:36 UTC (rev 4999) +++ epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/Reference_Guide.ent 2010-11-10 07:00:09 UTC (rev 5000) @@ -1,9 +1,5 @@ <!ENTITY PRODUCT "JBoss Enterprise Portal Platform"> -<!ENTITY PRODUCT_NAME "JBoss Enterprise Portal Platform"> -<!ENTITY PRODUCT_VERSION "5.1.0"> -<!ENTITY VERSION "5.0.1"> -<!ENTITY PORTAL_VERSION "5.1.0"> -<!ENTITY WSRP_VERSION "2.0.0"> +<!ENTITY VERSION "5.1.0"> <!ENTITY BOOKID "Reference Guide"> <!ENTITY YEAR "2010"> <!ENTITY HOLDER "Red Hat, Inc"> Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/modules/WSRP.xml 2010-11-10 06:08:36 UTC (rev 4999) +++ epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/modules/WSRP.xml 2010-11-10 07:00:09 UTC (rev 5000) @@ -14,7 +14,8 @@ It has been produced through the efforts of the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is based on the requirements gathered and the proposals made to the committee. </para> <para> - Scenarios that motivate WSRP functionality include: + Scenarios that motivate WSRP functionality include: + </para> <itemizedlist> <listitem> <para> @@ -27,27 +28,23 @@ </para> </listitem> </itemizedlist> - </para> + <para> More information on WSRP can be found on the official <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp...;. We suggest reading the <ulink url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr... for a good, albeit technical, overview of WSRP. </para> - <!-- Doesn't seem to offer any more than the para above -<para> -The <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... is suggested reading for a comprehensive overview of WSRP. -</para> --> </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Level_of_support_in_PRODUCT"> - <title>Level of support in &PRODUCT;</title> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Level_of_Support"> + <title>Level of Support</title> <para> The WSRP Technical Committee defined <ulink url="http://www.oasis-open.org/committees/download.php/3073">... Use Profiles</ulink> to help with WSRP interoperability. Terms defined in that document will be used in this section. </para> <para> - &PRODUCT_NAME; provides a <emphasis>Simple</emphasis> level of support for the WSRP Producer, with the exception of out-of-band registration. In-band registration and persistent local state (which are defined at the <emphasis>Complex</emphasis> level) are supported. + &PRODUCT; provides a <emphasis>Simple</emphasis> level of support for the WSRP Producer, with the exception of out-of-band registration. In-band registration and persistent local state (which are defined at the <emphasis>Complex</emphasis> level) are supported. </para> <para> - &PRODUCT_NAME; provides a <emphasis>Medium</emphasis> level of support for the Consumer, excepting HTML markup (as &PRODUCT_NAME; itself doesn&#39;t handle other markup types). Explicit portlet cloning and the <literal>PortletManagement</literal> interface are supported. + &PRODUCT; provides a <emphasis>Medium</emphasis> level of support for the Consumer, excepting HTML markup (as &PRODUCT; itself does not handle other markup types). Explicit portlet cloning and the <literal>PortletManagement</literal> interface are supported. </para> <para> The WSRP component has Level 1 Producer and Consumer caching. Cookie handling is supported properly on the Consumer. The Producer requires cookie initialization (as this improves interoperabilty with some consumers). @@ -56,16 +53,24 @@ &PRODUCT; does not support custom window states or modes, therefore neither does the WSRP component. It does, however, support CSS on both the Producer (although this is more a function of the portlets than an inherent Producer capability) and Consumer. </para> <para> - While &PRODUCT; provides a complete implementation of WSRP 1.0, more interoperability testing (based on the <ulink url="http://www.oasis-open.org/committees/download.php/6018">... statements</ulink>) is planned for future releases. - </para> + &PRODUCT; 5.0 provides a complete implementation of WSRP 1.0 while &PRODUCT; 5.1 includes an implementation of WSRP 2.0. + </para> + <para> + All optional features in WSRP 2 are implemented except support for lifetimes and leasing support. + </para> + <note> + <para> + As of version &VERSION; of &PRODUCT;, WSRP is only activated and supported when &PRODUCT; is deployed on JBoss Application Server. + </para> + </note> + <para> + Users should familiarize themselves with the appropriate sections of this chapter based on their version of &PRODUCT;. + </para> </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Deploying_PRODUCT_NAMEs_WSRP_services"> - <title>Deploying &PRODUCT_NAME;&#39;s WSRP services</title> - <para> - &PRODUCT_NAME; provides a complete support of WSRP 1.0 standard interfaces and offers both Consumer and Producer services. - </para> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Deploying_WSRP"> + <title>Deploying WSRP</title> <note> <title>Assumptions</title> <para> @@ -74,22 +79,22 @@ <orderedlist> <listitem> <para> - That the directory &PRODUCT_NAME; has been installed into will be referred to as <replaceable>PORTAL_HOME</replaceable>. + That the directory &PRODUCT; has been installed into will be referred to as <replaceable>PORTAL_HOME</replaceable>. </para> </listitem> <listitem> <para> - That <replaceable>WSRP_VERSION</replaceable> is the version of the WSRP component in use (at the time of the writing, it was &WSRP_VERSION;). + That <replaceable>WSRP_VERSION</replaceable> is the version of the WSRP component in use. </para> </listitem> <listitem> <para> - That <replaceable>PORTAL_VERSION</replaceable> is the current &PRODUCT_NAME; version (at the time of the writing, it was &PORTAL_VERSION;). + That <replaceable>PORTAL_VERSION</replaceable> is the version of &PRODUCT; in use. </para> </listitem> </orderedlist> </note> - <variablelist id="vari-Reference_Guide-Deploying_PRODUCT_NAMEs_WSRP_services-WSRP_support_files"> + <variablelist id="vari-Reference_Guide-Deploying_WSRP-WSRP_support_files"> <title>WSRP support files</title> <varlistentry> <term><replaceable>PORTAL_HOME</replaceable>/wsrp-admin-gui.war</term> @@ -131,6 +136,14 @@ </para> </listitem> </varlistentry> + <varlistentry> + <term><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-producer-lib-$WSRP_VERSION.jar</term> + <listitem> + <para> + This file contains the classes needed by the WSRP producer. + </para> + </listitem> + </varlistentry> <varlistentry> <term><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-wsrp1-ws-<replaceable>WSRP_VERSION</replaceable>.jar</term> <listitem> @@ -139,60 +152,59 @@ </para> </listitem> </varlistentry> - <!-- DOC TODO: Uncomment this entry for version 5.1.0. Check to see if WSRP1 entry is still relevant -<varlistentry> -<term><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-wsrp2-ws-<replaceable>WSRP_VERSION</replaceable>.jar</term> -<listitem> -<para> -This file contains the JAX-WS classes for WSRP version 2. -</para> -</listitem> -</varlistentry> --> + <varlistentry> + <term><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-wsrp2-ws-<replaceable>WSRP_VERSION</replaceable>.jar</term> + <listitem> + <para> + This file contains the JAX-WS classes for WSRP version 2. + </para> + </listitem> + </varlistentry> <varlistentry> <term><replaceable>PORTAL_HOME</replaceable>/lib/gatein.portal.component.wsrp-<replaceable>PORTAL_VERSION</replaceable>.jar</term> <listitem> <para> - This file contains the code to integrate the WSRP service into &PRODUCT_NAME;. + This file contains the code to integrate the WSRP service into &PRODUCT;. </para> </listitem> </varlistentry> </variablelist> <para> - If WSRP is not going to be used in &PRODUCT_NAME;, the <filename><replaceable>PORTAL_HOME</replaceable>/lib/gatein.portal.component.wsrp-<replaceable>PORTAL_VERSION</replaceable>.jar</filename> can be removed from &PRODUCT_NAME; distribution to deactivate WSRP support. + If WSRP is not going to be used in your &PRODUCT; instance, the <filename><replaceable>PORTAL_HOME</replaceable>/lib/gatein.portal.component.wsrp-<replaceable>PORTAL_VERSION</replaceable>.jar</filename> can be removed to deactivate WSRP support. </para> - <section id="sect-Reference_Guide-Deploying_PRODUCT_NAMEs_WSRP_services-Considerations_for_use_with_non_default_port_or_hostname"> - <title>Considerations for use with non-default port or hostname</title> + + <section id="sect-Reference_Guide-Deploying_WSRP-Non_default_Ports_or_Hostnames"> + <title>Non-default Ports or Hostnames</title> <para> - JBoss WS (the web service stack that &PRODUCT_NAME; uses) should update the port and host name used in WSDL. Refer to the JBoss WS <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... guide</ulink> for more information. + JBoss WS (the web service stack that &PRODUCT; uses) should update the port and host name used in WSDL. Refer to the JBoss WS <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... guide</ulink> for more information. </para> <para> - If the host name and port on which the server runs have been modified, the configuration for the Consumer used to consume &PRODUCT_NAME;&#39;s &#39;self&#39; Producer will need to be updated. Refer to <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME" /> to learn how to do this. + If the host name and port on which the server runs have been modified, the configuration for the Consumer used to consume &PRODUCT;'s "self" Producer will need to be updated. Refer to <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets" /> for directions on how to do this. </para> </section> - <section id="sect-Reference_Guide-Deploying_PRODUCT_NAMEs_WSRP_services-Considerations_to_use_WSRP_with_SSL"> - <title>Considerations to use WSRP with SSL</title> + <section id="sect-Reference_Guide-Deploying_WSRP-Using_WSRP_with_SSL"> + <title>Using WSRP with SSL</title> <para> It is possible to use WSRP over SSL for secure exchange of data. Refer to these <ulink url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu... for how to do this. </para> </section> - </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Making_a_portlet_remotable"> - <title>Making a portlet remotable</title> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Making_a_Portlet_Remotable"> + <title>Making a Portlet Remotable</title> <note> <para> Only JSR-286 (Portlet 2.0) portlets can be made remotable as the mechanism to expose a portlet to WSRP relies on a JSR-286-only functionality. </para> </note> <para> - &PRODUCT_NAME; does <emphasis role="bold">NOT</emphasis>, by default, expose local portlets for consumption by remote WSRP consumers. + &PRODUCT; does <emphasis role="bold">NOT</emphasis>, by default, expose local portlets for consumption by remote WSRP consumers. </para> <para> - In order to make a portlet remotely available, it must be made &#34;remotable&#34; by marking it as such in the associated <filename>portlet.xml</filename>. + In order to make a portlet remotely available, it must be made "remotable" by marking it as such in the associated <filename>portlet.xml</filename>. </para> <para> A specific <code>org.gatein.pc.remotable container-runtime-option</code> is used to accomplish this. Setting its value to <code>true</code> makes the portlet available for remote consumption, while setting its value to <code>false</code> will not publish it remotely. @@ -201,7 +213,7 @@ As specifying the remotable status for a portlet is optional, nothing need be done if portlets do not need to be remotely available. </para> <para> - In the following example, the &#34;BasicPortlet&#34; portlet is specified as being remotable. + In the following example, the "BasicPortlet" portlet is specified as being remotable. </para> <programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default255.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> @@ -217,7 +229,7 @@ <programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default256.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - This example defines two portlets. As the <code>org.gatein.pc.remotable container-runtime-option</code> is set to <code>true</code> at the <code>portlet-app</code> level, all portlets defined in this particular portlet application are exposed remotely by &PRODUCT_NAME;&#39;s WSRP Producer. + This example defines two portlets. As the <code>org.gatein.pc.remotable container-runtime-option</code> is set to <code>true</code> at the <code>portlet-app</code> level, all portlets defined in this particular portlet application are exposed remotely by &PRODUCT;'s WSRP Producer. </para> <para> It is possible to override this default behavior. Specifying a value for the <code>org.gatein.pc.remotable container-runtime-option</code> at the <code>portlet</code> level will take precedence over the default. @@ -236,16 +248,22 @@ </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_PRODUCT_NAMEs_WSRP_portlets_from_a_remote_Consumer"> - <title>Consuming &PRODUCT_NAME;&#39;s WSRP portlets from a remote Consumer</title> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_WSRP_portlets_from_a_remote_Consumer"> + <title>Consuming WSRP portlets from a remote Consumer</title> + <important> + <title><emphasis role="bold">DOC NOTE</emphasis></title> + <para> + Is this section relevant? Do we want users consuming portlets produced by EPP elsewhere? + </para> + </important> <para> - Configuration is extremely variable between different WSRP Consumers. Most, however, require a specification of the URL for the Producer&#39;s WSDL definition. If the &PRODUCT_NAME; Consumer is not being used, refer to the documentation for the Consumer that is in use for specific instructions. + Configuration is extremely variable between different WSRP Consumers. Most, however, require a specification of the URL for the Producer's WSDL definition. If the &PRODUCT; Consumer is not being used, refer to the documentation for the Consumer that is in use for specific instructions. </para> <para> - For instructions on how to specify this URL in &PRODUCT_NAME;, refer to <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME" />. + For instructions on how to specify this URL in &PRODUCT;, refer to <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets" />. </para> <para> - &PRODUCT_NAME;&#39;s Producer is automatically set up when a portal instance is deployed with the WSRP service. + &PRODUCT;'s Producer is automatically set up when a portal instance is deployed with the WSRP service. </para> <para> The WSDL file can be accessed at <filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/MarkupService?wsdl</filename>. The default hostname is <literal>localhost</literal> and the default port is <literal>8080</literal>. @@ -253,12 +271,12 @@ </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME"> - <title>Consuming remote WSRP portlets in &PRODUCT_NAME;</title> - <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Overview"> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets"> + <title>Consuming Remote WSRP Portlets</title> + <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-Overview"> <title>Overview</title> <para> - To be able to consume WSRP portlets exposed by a remote producer, &PRODUCT_NAME;&#39;s WSRP consumer must be configured to access that remote producer. + To be able to consume WSRP portlets exposed by a remote producer, &PRODUCT;'s WSRP consumer must be configured to access that remote producer. </para> <para> Access to a remote producer can be configured using WSRP Producer descriptors. Alternatively, a portlet is provided to configure remote producers. @@ -267,17 +285,16 @@ Once a remote producer has been configured, the portlets that it exposes are then available in the Application Registry to be added to categories and then to pages. </para> <para> - A default consumer named <literal>self</literal>, that consumes the portlets exposed by &PRODUCT_NAME;&#39;s producer, has been configured as a way to test the WSRP producer service and to check that portlets are correctly published via WSRP. + A default consumer named <literal>self</literal>, that consumes the portlets exposed by &PRODUCT;'s producer, has been configured as a way to test the WSRP producer service and to check that portlets are correctly published via WSRP. </para> </section> - <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Configuring_a_remote_producer"> - <title>Configuring a remote producer</title> + <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-Configuring_a_Remote_Producer"> + <title>Configuring a Remote Producer</title> <para> - Access to a remote producer needs to be defined so that portlets can be consumed within &PRODUCT_NAME;. This section will show how to configure access to <emphasis role="bold">Oracle</emphasis>&#39;s public WSRP producer. Firstly using the configuration portlet. Then how the same result can be accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet. + Access to a remote producer needs to be defined so that portlets can be consumed within &PRODUCT;. This section will show how to configure access to <emphasis role="bold">Oracle</emphasis>'s public WSRP producer. Firstly using the configuration portlet. Then how the same result can be accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet. </para> - <!-- Warning added as per notification from Chris Laprun --> <important> <title>Chunked Encoding</title> <para> @@ -290,12 +307,22 @@ Refer to <ulink type="http" url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis... for more information. </para> </important> - <section id="sect-Reference_Guide-Configuring_a_remote_producer-Using_the_configuration_portlet"> - <title>Using the configuration portlet</title> + <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-The_Configuration_Portlet"> + <title>The Configuration Portlet</title> <para> - &PRODUCT_NAME; provides a portlet to configure access (among other functions) to remote WSRP Producers grahically. This portlet isn&#39;t installed by default, so it must be installed using the Application Registry. - </para> + &PRODUCT; provides a portlet to configure access (among other functions) to remote WSRP Producers grahically. + </para> + <formalpara> + <title><emphasis role="bold">&PRODUCT; 5.0: Installing the Configuration Portlet</emphasis></title> + <para> + This portlet is not installed by default in &PRODUCT; 5.0. It must be installed using the Application Registry. + </para> + </formalpara> + <para> + To install the configuration portlet: + </para> <procedure> + <title><emphasis role="bold"></emphasis></title> <step> <para> Log into the portal as an administrator and go to the Application Registry (Click <ulink url="http://localhost:8080/portal/private/classic/administration/registry">http://localhost:8080/portal/private/classic/administration/registry</ulink> if using the default installation). @@ -306,132 +333,143 @@ Add the WSRP Configuration portlet to the Administration category. If the Import Applications functionality is used, the WSRP Configuration portlet will be automatically added to the Administration category. </para> </step> + <step> + <para> + Once the portlet is added to a category, it can be added to a page and used. It is recommended that it be added to the same page as the Application Registry (as other operations relating to WSRP and adding portlets to categories are somewhat related). Add the WSRP Configuration portlet to the page using the standard procedure. + </para> + </step> </procedure> - - <para> - Once the portlet is added to a category, it can be added to a page and used. It is recommended that it be added to the same page as the Application Registry (as other operations relating to WSRP and adding portlets to categories are somewhat related). Add the WSRP Configuration portlet to the page using the standard procedure. - </para> - <para> - <emphasis role="bold">The WSRP Configuration portlet</emphasis>: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_init.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_init.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - <para> - This screen presents all the configured consumers associated with their status and possible actions on them. - </para> - <para> - A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. - </para> - <para> - Note also that a Consumer can be marked as requiring <emphasis>refresh</emphasis>, which means that the information held about it might not be up to date. Refreshing it from the remote Producer will update this information. - </para> - <para> - This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information. - </para> - <procedure> - <step> - <para> - Type &#34;<literal> oracle</literal>&#34; into the &#34;<emphasis role="bold">Create a consumer named:</emphasis>&#34; field. - </para> - </step> - <step> - <para> - Click on &#34;<emphasis role="bold">Create consumer</emphasis>&#34; to create a new Consumer called <literal>oracle</literal>. - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_create.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_create.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - </step> - <step> - <para> - In the next form, set the cache expiration value to <parameter>300</parameter> seconds. - </para> - </step> - <step> - <para> - Leave the default timeout value for web services (WS) operations. - </para> - </step> - <step> - <para> - Enter the WSDL URL for the producer in the text field. - </para> - </step> - <step> - <para> - Press the &#34;Refresh &amp; Save&#34; button: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_wsdl.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_wsdl.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - </step> - </procedure> - - <para> - This will retrieve the service description associated with the Producer which WSRP interface is described by the WSDL file found at the URL entered. - </para> - <para> - In this case, querying the service description will suggest that the Producer requires registration but did not request any registration property: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_refresh.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_refresh.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - <para> - The Consumer for the <literal>oracle</literal> Producer should now be available as a portlet provider and be ready to be used. - </para> - <para> - Assuming that the producer required a value for an <literal>email</literal> registration property, &PRODUCT_NAME;&#39;s WSRP consumer will report that some information was missing: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_missing.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_missing.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - <note> - <title>Values</title> - <para> - As at this release there is no automated way to learn about which possible values (if any) are expected by the remote Producer. Possible values may be indicated in the registration property description but this is not always the case. Refer to the specific Producer&#39;s documentation. - </para> - </note> - <para> - Enter an address for the registration property (&amp;#34;&lt;literal&gt;example(a)example.com&lt;/literal&gt;&amp;#34;) and press &#34;<emphasis role="bold">Save &amp; Refresh</emphasis>&#34; once more: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_end.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> + <formalpara> + <title><emphasis role="bold">&PRODUCT; 5.1: Accessing the Configuration Portlet</emphasis></title> + <para> + The Configuration Portlet is installed by default in &PRODUCT; 5.1. It is available at: <ulink type="http" url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&amp;username=root&amp;password=gtn"></ulink> + </para> + </formalpara> + <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-The_Configuration_Portlet-Using_the_Configuration_Portlet"> + <title><emphasis role="bold">Using the Configuration portlet</emphasis></title> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_init.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_init.png" format="PNG" /> + </imageobject> + </mediaobject> + <para> + This screen presents all the configured consumers associated with their status and possible actions on them. + </para> + <para> + A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. + </para> + <para> + Note also that a Consumer can be marked as requiring <emphasis>refresh</emphasis>, which means that the information held about it might not be up to date. Refreshing it from the remote Producer will update this information. + </para> + <para> + This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information. + </para> + <para> + To create a new Concumer: + </para> + <procedure> + <title><emphasis role="bold">Creating a Consumer</emphasis></title> + <step> + <para> + Type "<literal> oracle</literal>" into the "<emphasis role="bold">Create a consumer named:</emphasis>" field. + </para> + </step> + <step> + <para> + Click on "<emphasis role="bold">Create consumer</emphasis>" to create a new Consumer called <literal>oracle</literal>. + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_create.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_create.png" format="PNG" /> + </imageobject> + </mediaobject> + </step> + <step> + <para> + In the next form, set the cache expiration value to <parameter>300</parameter> seconds. + </para> + </step> + <step> + <para> + Leave the default timeout value for web services (WS) operations. + </para> + </step> + <step> + <para> + Enter the WSDL URL for the producer in the text field. + </para> + </step> + <step> + <para> + Press the "Refresh &amp; Save" button: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_wsdl.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_wsdl.png" format="PNG" /> + </imageobject> + </mediaobject> + </step> + </procedure> + + <para> + This will retrieve the service description associated with the Producer which WSRP interface is described by the WSDL file found at the URL entered. + </para> + <para> + In this case, querying the service description will suggest that the Producer requires registration but did not request any registration property: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_refresh.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_refresh.png" format="PNG" /> + </imageobject> + </mediaobject> + <para> + The Consumer for the <literal>oracle</literal> Producer should now be available as a portlet provider and be ready to be used. + </para> + <para> + Assuming that the producer required a value for an <literal>email</literal> registration property, &PRODUCT;'s WSRP consumer will report that some information was missing: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_missing.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_missing.png" format="PNG" /> + </imageobject> + </mediaobject> + <note> + <title>Values</title> + <para> + As at this release there is no automated way to learn about which possible values (if any) are expected by the remote Producer. Possible values may be indicated in the registration property description but this is not always the case. Refer to the specific Producer's documentation. + </para> + </note> + <para> + Enter an address for the registration property (&quot;&lt;literal&gt;example(a)example.com&lt;/literal&gt;&quot;) and press "<emphasis role="bold">Save &amp; Refresh</emphasis>" once more: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_end.png" format="PNG" /> + </imageobject> + </mediaobject> + </section> <!-- Close Section: <number><title> --> </section> - <section id="sect-Reference_Guide-Configuring_a_remote_producer-Using_XML"> + <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-Using_XML"> <title>Using XML</title> <para> Although using the WSRP Configuration portlet to configure Consumers is recommended, the WSRP component provides an alternative way to configure consumers. @@ -442,7 +480,7 @@ <programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default257.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - The file as shown above specifies access to two producers: <literal>self</literal>, which consumes &PRODUCT_NAME;&#39;s own WSRP producer (albeit in a version that assumes that the producer requires a value for an <literal>email</literal> registration property), and <literal>oracle</literal>, which consumes Oracle&#39;s public producer, both in configurations as shown in the procedure above. + The file as shown above specifies access to two producers: <literal>self</literal>, which consumes &PRODUCT;'s own WSRP producer (albeit in a version that assumes that the producer requires a value for an <literal>email</literal> registration property), and <literal>oracle</literal>, which consumes Oracle's public producer, both in configurations as shown in the procedure above. </para> <note> <para> @@ -452,17 +490,17 @@ </section> - <section id="sect-Reference_Guide-Configuring_a_remote_producer-Configuring_access_to_a_remote_portlet"> - <title>Configuring access to a remote portlet</title> + <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-Configuring_Access_to_a_Remote_Portlet"> + <title>Configuring Access to a Remote Portlet</title> <para> Clicking on the Portlet link in the Application Registry will now show the remote potlets in the <emphasis role="bold">REMOTE</emphasis> tab in the left column: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/remote_portlets.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/remote_portlets.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" /> </imageobject> </mediaobject> <para> @@ -480,8 +518,8 @@ </section> - <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Configuring_access_to_remote_Producers_via_XML"> - <title>Configuring access to remote Producers via XML</title> + <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-Configuring_Access_to_Remote_Producers_via_XML"> + <title>Configuring Access to Remote Producers via XML</title> <para> Again, configuring consumers via XML is done by editing <filename><replaceable>PORTAL_HOME</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar/conf/wsrp-consumers-config.xml</filename>. </para> @@ -497,20 +535,20 @@ It is important to understand how the XML Consumers configuration file is processed. It is read the first time the WSRP service starts and the associated information is then put under control of the JCR (Java Content Repository). </para> <para> - Subsequent launches of the WSRP service will use the JCR-stored information for all producers that are already known to &PRODUCT_NAME;. More specifically, the <filename>wsrp-consumers-config.xml</filename> file is scanned for producer identifiers. Any identifier that is already known will be bypassed and the JCR information associated with this remote producer will be used. + Subsequent launches of the WSRP service will use the JCR-stored information for all producers that are already known to &PRODUCT;. More specifically, the <filename>wsrp-consumers-config.xml</filename> file is scanned for producer identifiers. Any identifier that is already known will be bypassed and the JCR information associated with this remote producer will be used. </para> <para> The information defined at the XML level is only processed for producer definition for which no information is already present in the JCR. </para> <para> - Therefore, to delete a Producer configuration, the associated information in the database must be deleted (this can be accomplished using the configuration portlet as shown in <xref linkend="sect-Reference_Guide-Configuring_a_remote_producer-Using_the_configuration_portlet" />). + Therefore, to delete a Producer configuration, the associated information in the database must be deleted (this can be accomplished using the configuration portlet as shown in <xref linkend="sect-Reference_Guide-Configuring_a_Remote_Producer-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> + <section id="sect-Reference_Guide-Configuring_Access_to_Remote_Producers_via_XML-Required_Configuration_Information"> + <title>Required Configuration Information</title> <para> The following information needs to be provided to configure access to a remote Producer: </para> @@ -522,7 +560,7 @@ </listitem> <listitem> <para> - &PRODUCT_NAME; also needs to know about the remote Producer&#39;s endpoints to be able to connect to the remote web services and perform WSRP invocations. Use the <literal>&#60;endpoint-wsdl-url&#62;</literal> element to specify the URL for the WSDL description of the remote WSRP service. + &PRODUCT; also needs to know about the remote Producer's endpoints to be able to connect to the remote web services and perform WSRP invocations. Use the <literal>&#60;endpoint-wsdl-url&#62;</literal> element to specify the URL for the WSDL description of the remote WSRP service. </para> </listitem> </orderedlist> @@ -532,12 +570,12 @@ </section> - <section id="sect-Reference_Guide-Configuring_access_to_remote_Producers_via_XML-Optional_configuration"> - <title>Optional configuration</title> + <section id="sect-Reference_Guide-Configuring_Access_to_Remote_Producers_via_XML-Optional_Configuration"> + <title>Optional Configuration</title> <para> It is also possible to provide additional configuration, which, in some cases, might be important to establish a proper connection to the remote producer. </para> - <variablelist id="vari-Reference_Guide-Optional_configuration-Optional_Configurations"> + <variablelist id="vari-Reference_Guide-Optional_Configuration-Optional_Configurations"> <title>Optional Configurations</title> <varlistentry> <term>Caching</term> @@ -549,7 +587,7 @@ The rate at which the information is refreshed is defined by the <literal>expiration-cache</literal> attribute of the <literal>&#60;wsrp-producer&#62;</literal> element (in seconds). </para> <para> - For example; providing a value of 120 for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been accessed. If no value is provided, &PRODUCT_NAME; will always access the remote producer regardless of whether the remote information has changed or not. + For example; providing a value of 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; 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. @@ -577,13 +615,13 @@ This pre-registration configuration is done via the <literal>&#60;registration-data&#62;</literal> element. </para> <para> - If the remote producer does not require any registration properties, only an empty <literal>&#60;registration-data&#62;</literal> element need be provided, as &PRODUCT_NAME; can generate the mandatory information. + If the remote producer does not require any registration properties, only an empty <literal>&#60;registration-data&#62;</literal> element need be provided, as &PRODUCT; can generate the mandatory information. </para> <para> Values for the registration properties required by the remote producer can be provided via <literal>&#60;property&#62;</literal> elements. Refer to the example below for more details. </para> <para> - Additionally, the default consumer name automatically provided by &PRODUCT_NAME; can be overridden via the <literal>&#60;consumer-name&#62;</literal> element. When providing a consumer name, please remember that it should uniquely identify your consumer. + Additionally, the default consumer name automatically provided by &PRODUCT; can be overridden via the <literal>&#60;consumer-name&#62;</literal> element. When providing a consumer name, please remember that it should uniquely identify your consumer. </para> </listitem> </varlistentry> @@ -593,7 +631,7 @@ </section> - <section id="sect-Reference_Guide-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME-Examples"> + <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-Examples"> <title>Examples</title> <para> This is the configuration of the <literal>self</literal> producer as found in <filename>default-wsrp.xml</filename> with a cache expiring every five minutes and with a 30 second timeout for web service operations: @@ -610,14 +648,14 @@ </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consumers_maintenance"> - <title>Consumers maintenance</title> - <section id="sect-Reference_Guide-Consumers_maintenance-Modifying_a_currently_held_registration"> - <title>Modifying a currently held registration</title> - <section id="sect-Reference_Guide-Modifying_a_currently_held_registration-Registration_modification_for_service_upgrade"> - <title>Registration modification for service upgrade</title> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consumers_Maintenance"> + <title>Consumers Maintenance</title> + <section id="sect-Reference_Guide-Consumers_Maintenance-Modifying_a_Currently_Held_Registration"> + <title>Modifying a Currently Held Registration</title> + <section id="sect-Reference_Guide-Modifying_a_Currently_Held_Registration-Registration_Modification_for_Service_Upgrade"> + <title>Registration Modification for Service Upgrade</title> <para> - Producers often offer several levels of service depending on consumers&#39; subscription levels (for example). This is implemented at the WSRP level with the registration concept: producers can assert which level of service to provide to consumers based on the values of given registration properties. + Producers often offer several levels of service depending on consumers' subscription levels (for example). This is implemented at the WSRP level with the registration concept: producers can assert which level of service to provide to consumers based on the values of given registration properties. </para> <para> There may also be cases where the registration information has changed and must be updated. For example, the producer required you to provide a valid email and the previous email address is not valid anymore and needs to be updated. @@ -626,7 +664,7 @@ Therefore at times it may be necessary to modify the registration that sets the service agreement between a consumer and a producer. </para> <para> - For example; the producer requiring an email that was configured in <xref linkend="sect-Reference_Guide-Configuring_a_remote_producer-Using_the_configuration_portlet" />. In that case the producer was requiring registration and required a value to be provided for the <literal>email</literal> property. + For example; the producer requiring an email that was configured in <xref linkend="sect-Reference_Guide-Configuring_a_Remote_Producer-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> To update the email address that was provided, the remote producer must be informed that some registration data has been modified. @@ -641,23 +679,23 @@ </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_start.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/modify_reg_start.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png" format="PNG" /> </imageobject> </mediaobject> </step> <step> <para> - Click on &#34;<emphasis role="bold">Update properties</emphasis>&#34; to save the change. A &#34;<emphasis role="bold">Modify registration</emphasis>&#34; button should now appear to let you send this new data to the remote producer: + Click on "<emphasis role="bold">Update properties</emphasis>" to save the change. A "<emphasis role="bold">Modify registration</emphasis>" button should now appear to let you send this new data to the remote producer: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_modify.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/modify_reg_modify.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png" format="PNG" /> </imageobject> </mediaobject> </step> @@ -667,10 +705,10 @@ </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_end.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/modify_reg_end.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png" format="PNG" /> </imageobject> </mediaobject> </step> @@ -678,10 +716,10 @@ </section> - <section id="sect-Reference_Guide-Modifying_a_currently_held_registration-Registration_modification_on_Producer_error"> - <title>Registration modification on Producer error</title> + <section id="sect-Reference_Guide-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error"> + <title>Registration Modification on Producer Error</title> <para> - Invoking operations on the producer may fail with an <exceptionname>OperationFailedFault</exceptionname> if the producer administrator has changed its requirement for registered consumers. &PRODUCT_NAME; will attempt to assist in these cases. + Invoking operations on the producer may fail with an <exceptionname>OperationFailedFault</exceptionname> if the producer administrator has changed its requirement for registered consumers. &PRODUCT; will attempt to assist in these cases. </para> <para> This section will discuss an example using the <literal>self</literal> producer. @@ -691,43 +729,44 @@ </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_self.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/config_self.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_self.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_self.png" format="PNG" /> </imageobject> </mediaobject> <para> If the administrator of the producer now requires an additional value to be provided for a <literal>name</literal> registration property operations with this producer will fail. </para> <para> - If a registration modification is required, go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing &#34;<emphasis role="bold">Refresh &amp; Save</emphasis>&#34;: + If a registration modification is required, go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing "<emphasis role="bold">Refresh &amp; Save</emphasis>": </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_self.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/modify_reg_self.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self.png" format="PNG" /> </imageobject> </mediaobject> <para> The configuration screen now shows the currently held registration information and the expected information from the producer. </para> <para> - Enter a value for the <literal>name</literal> property and then click on &#34;<emphasis role="bold">Modify registration</emphasis>&#34;. If the producer accepts the new registration data, the following screen will appear: + Enter a value for the <literal>name</literal> property and then click on "<emphasis role="bold">Modify registration</emphasis>". If the producer accepts the new registration data, the following screen will appear: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" /> </imageobject> </mediaobject> <note> + <title><emphasis role="bold">&PRODUCT; 5.0 and WSRP 1 Exceptions</emphasis></title> <para> - As of WSRP 1, it can be difficult to ascertain what caused an <exceptionname>OperationFailedFault</exceptionname> as it is a generic exception returned by producers during a failed method invocation. + In WSRP 1, it can be difficult to ascertain what caused an <exceptionname>OperationFailedFault</exceptionname> as it is a generic exception returned by producers during a failed method invocation. </para> <para> An <exceptionname>OperationFailedFault</exceptionname> failure can be caused by several different reasons, one of them being a request to modify the registration data. @@ -744,17 +783,17 @@ </section> - <section id="sect-Reference_Guide-Consumers_maintenance-Consumer_operations"> - <title>Consumer operations</title> + <section id="sect-Reference_Guide-Consumers_Maintenance-Consumer_Operations"> + <title>Consumer Operations</title> <para> Several operations are available from the consumer list view of the WSRP configuration portlet: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/consumer_operations.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/consumer_operations.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/consumer_operations.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/consumer_operations.png" format="PNG" /> </imageobject> </mediaobject> <para> @@ -802,11 +841,57 @@ </listitem> </varlistentry> </variablelist> + <formalpara> + <title><emphasis role="bold">&PRODUCT; 5.1: Additional Functionalities in WSRP 2.0</emphasis></title> + <para> + In addition to those listed above, the WSRP 2.0 implementation in &PRODUCT; 5.1 also includes the following functions: + </para> + </formalpara> + <variablelist> + <title></title> + <varlistentry> + <term>Export</term> + <listitem> + <para> + Exports some or all of the consumer's portlets to be able to later import them in a different context + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Import</term> + <listitem> + <para> + Imports some or all of previously exported portlets. + </para> + </listitem> + </varlistentry> + </variablelist> + <section> + <title><emphasis role="bold">Importing and Exporting Portlets</emphasis></title> + <para> + Import and export are new functionalities added in WSRP 2. + </para> + <para> + Exporting a portlet allows a consumer to get an opaque representation of the portlet which can then be use by the corresponding import operation to reconstitute it. + </para> + <para> + This is mostly used in migration scenarios during batch operations. Since &PRODUCT; does not currently support automated migration of portal data, the functionality provided as part of WSRP 2 is necessarily less complete than it could be with full portal support. + </para> + <para> + The import/export implementation in &PRODUCT; allows users to export portlets from a given consumer and then import them back to replace existing portlets assigned to windows on pages by the previously exported portlets. + </para> + <note> + <title><emphasis role="bold">DOC TODO</emphasis></title> + <para> + Walk-through exporting portlets and then importing them. + </para> + </note> + </section> </section> - <section id="sect-Reference_Guide-Consumers_maintenance-Erasing_local_registration_data"> - <title>Erasing local registration data</title> + <section id="sect-Reference_Guide-Consumers_Maintenance-Erasing_Local_Registration_Data"> + <title>Erasing Local Registration Data</title> <para> In rare cases, it may be necessary to erase the local data without being able to de-register first. </para> @@ -817,14 +902,14 @@ 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 &#34;<emphasis role="bold">Erase local registration</emphasis>&#34; button next to the registration context information on the consumer configuration screen: + To do this click on the "<emphasis role="bold">Erase local registration</emphasis>" button next to the registration context information on the consumer configuration screen: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/erase_registration.png" format="PNG" scale="80" width="444" /> + <imagedata align="center" fileref="images/WSRP/erase_registration.png" format="PNG" scale="80" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration.png" format="PNG" /> </imageobject> </mediaobject> <warning> @@ -833,10 +918,10 @@ </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/erase_registration_warning.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/erase_registration_warning.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration_warning.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration_warning.png" format="PNG" /> </imageobject> </mediaobject> </warning> @@ -845,21 +930,21 @@ </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Configuring_PRODUCT_NAMEs_WSRP_Producer"> - <title>Configuring &PRODUCT_NAME;&#39;s WSRP Producer</title> - <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Overview"> + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Configuring_the_WSRP_Producer"> + <title>Configuring the WSRP Producer</title> + <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-Overview"> <title>Overview</title> <para> - The behavior of the Portal&#39;s WSRP Producer can be configured using the WSRP administration interface, (this is the recommended method), or by editing the <filename><replaceable>PORTAL_HOME</replaceable>/wsrp-producer.war/WEB-INF/conf/producer/config.xml</filename> file. + The behavior of the Portal's WSRP Producer can be configured using the WSRP administration interface, (this is the recommended method), or by editing the <filename><replaceable>PORTAL_HOME</replaceable>/wsrp-producer.war/WEB-INF/conf/producer/config.xml</filename> file. </para> <para> - Several aspects can be modified with respect to whether registration is required for consumers to access the Producer&#39;s services. An XML Schema for the configuration format is available at <filename> <replaceable>PORTAL_HOME</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename>. + Several aspects can be modified with respect to whether registration is required for consumers to access the Producer's services. An XML Schema for the configuration format is available at <filename> <replaceable>PORTAL_HOME</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename>. </para> </section> - <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Default_configuration"> - <title>Default configuration</title> + <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-Default_Configuration"> + <title>Default Configuration</title> <para> The default producer configuration requires that consumers register with it before providing access to its services. However it does not require any specific registration properties (excepting those mandated by the WSRP standard). </para> @@ -870,20 +955,20 @@ The producer also uses the default <classname>RegistrationPolicy</classname> paired with the default <classname>RegistrationPropertyValidator</classname>. </para> <para> - This allows users to customize how Portal&#39;s WSRP Producer decides whether a given registration property is valid or not (however property validators are discussed in greater detail in <xref linkend="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Registration_configuration" />). + This allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not (however property validators are discussed in greater detail in <xref linkend="sect-Reference_Guide-Configuring_the_WSRP_Producer-Registration_Configuration" />). </para> <para> - &PRODUCT_NAME; provides a web interface to configure the producer&#39;s behavior. It can be accessed by clicking on the &#34;<emphasis role="bold">Producer Configuration</emphasis>&#34; tab of the &#34;<emphasis role="bold">WSRP</emphasis>&#34; page of the &#34;<emphasis role="bold">admin</emphasis>&#34; portal. + &PRODUCT; provides a web interface to configure the producer's behavior. It can be accessed by clicking on the "<emphasis role="bold">Producer Configuration</emphasis>" tab of the "<emphasis role="bold">WSRP</emphasis>" page of the "<emphasis role="bold">admin</emphasis>" portal. </para> <para> The default configuration should show: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_default.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/producer_default.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_default.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_default.png" format="PNG" /> </imageobject> </mediaobject> <para> @@ -895,89 +980,89 @@ </section> - <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-Registration_configuration"> - <title>Registration configuration</title> + <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-Registration_Configuration"> + <title>Registration Configuration</title> <para> - In order to have consumers register with Portal&#39;s producer the Portal&#39;s behavior with respect to registration must be configured. + In order to have consumers register with Portal's producer the Portal's behavior with respect to registration must be configured. </para> <para> Registration is optional, as are registration properties. The producer can require registration without requiring consumers to pass any registration properties as is the case in the default configuration. </para> <para> - The following section discusses configuring a producer&#39;s registration behavior from a blank state: + The following section discusses configuring a producer's registration behavior from a blank state: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_blank.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/producer_blank.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_blank.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_blank.png" format="PNG" /> </imageobject> </mediaobject> <procedure> <step> <para> - To allow unregistered consumers to see the list of offered portlets, leave the first checkbox (&#34;<emphasis role="bold">Access to full service description requires consumers to be registered.</emphasis>&#34;) unchecked. + To allow unregistered consumers to see the list of offered portlets, leave the first checkbox ("<emphasis role="bold">Access to full service description requires consumers to be registered.</emphasis>") unchecked. </para> </step> <step> <para> - To specify, however, that consumers will need to be registered to be able to interact with the producer, check the second box (&#34;<emphasis role="bold">Requires registration. Modifying this information will trigger invalidation of consumer registrations.&#34;</emphasis>). + To specify, however, that consumers will need to be registered to be able to interact with the producer, check the second box ("<emphasis role="bold">Requires registration. Modifying this information will trigger invalidation of consumer registrations."</emphasis>). </para> <para> The screen will refresh and display: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_registration.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/producer_registration.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_registration.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_registration.png" format="PNG" /> </imageobject> </mediaobject> </step> <step> <para> - The fully-qualified name for the <classname>RegistrationPolicy</classname> and <classname>RegistrationPropertyValidator</classname> can be specified here. The default values are acceptable. Refer to <xref linkend="sect-Reference_Guide-Registration_configuration-Customization_of_Registration_handling_behavior" /> for more information. + The fully-qualified name for the <classname>RegistrationPolicy</classname> and <classname>RegistrationPropertyValidator</classname> can be specified here. The default values are acceptable. Refer to <xref linkend="sect-Reference_Guide-Registration_Configuration-Customization_of_Registration_Handling_Behavior" /> for more information. </para> </step> <step> <para> - To add a registration property called <literal>email</literal> click &#34;<emphasis role="bold">Add property</emphasis>&#34; and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to determine its purpose: + To add a registration property called <literal>email</literal> click "<emphasis role="bold">Add property</emphasis>" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to determine its purpose: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_email.png" format="PNG" scale="100" width="444" /> + <imagedata align="center" fileref="images/WSRP/producer_email.png" format="PNG" scale="100" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_email.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_email.png" format="PNG" /> </imageobject> </mediaobject> </step> <step> <para> - Press &#34;Save&#34; to record the modifications. + Press "Save" to record the modifications. </para> </step> </procedure> <note> <para> - At this time, only String (xsd:string) properties are supported. <!-- If your application requires more complex properties, please let us know. --> + At this time, only String (xsd:string) properties are supported. </para> </note> <note> <para> - If consumers are already registered with the producer, modifying the configuration of required registration information will trigger the invalidation of held registrations, requiring consumers to modify their registration before being able to access the producer again. The consumer side of that process is documented in <xref linkend="sect-Reference_Guide-Modifying_a_currently_held_registration-Registration_modification_on_Producer_error" />. + If consumers are already registered with the producer, modifying the configuration of required registration information will trigger the invalidation of held registrations, requiring consumers to modify their registration before being able to access the producer again. The consumer side of that process is documented in <xref linkend="sect-Reference_Guide-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error" />. </para> </note> - <section id="sect-Reference_Guide-Registration_configuration-Customization_of_Registration_handling_behavior"> - <title>Customization of Registration handling behavior</title> + <section id="sect-Reference_Guide-Registration_Configuration-Customization_of_Registration_Handling_Behavior"> + <title>Customization of Registration Handling Behavior</title> <para> Registration handling behavior can be customized by users to suit their Producer needs. This is done with an implementation of the <classname>RegistrationPolicy</classname> interface. </para> <para> - This interface defines methods that are called by Portal&#39;s Registration service so that decisions can be made appropriately. A default registration policy that provides basic behavior is provided and should be enough for most user needs. + This interface defines methods that are called by Portal's Registration service so that decisions can be made appropriately. A default registration policy that provides basic behavior is provided and should be enough for most user needs. </para> <para> While the default registration policy provides default behavior for most registration-related aspects, one aspect requires specific configuration: whether a given value for a registration property is acceptable by the WSRP Producer. @@ -1001,13 +1086,13 @@ </section> - <section id="sect-Reference_Guide-Configuring_PRODUCT_NAMEs_WSRP_Producer-WSRP_validation_mode"> - <title>WSRP validation mode</title> + <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-WSRP_Validation_Mode"> + <title>WSRP Validation Mode</title> <para> The lack of conformance kit and the wording of the WSRP specification leaves room for differing interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when using consumers from different vendors. Experience from these issues has produced a way to relax the validation that the WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. Note that the our validation algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes. </para> <para> - By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you might want to try to relax the validation mode. This is accomplished by unchecking the &#34;Use strict WSRP compliance&#34; checkbox on the Producer configuration screen. + By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you 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>