[gatein-commits] gatein SVN: r8122 - in epp/docs/branches/5.2: Reference_Guide-eXoJCR-1.14/en-US/modules and 1 other directory.

Author: smumford Date: 2011-11-22 22:39:01 -0500 (Tue, 22 Nov 2011) New Revision: 8122 Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml Log: Porting GateIn revisions 8119 and 8120 Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml 2011-11-22 21:19:52 UTC (rev 8121) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml 2011-11-23 03:39:01 UTC (rev 8122) @@ -153,8 +153,12 @@ <listitem> <para> - This directory contains files necessary for EAR packaging. The only file that is of interest from a user perspective is <filename>gatein-wsse-consumer.xml</filename> which allows you to configure WS-Security support for the consumer. !!!TODO mwringe please detail !!!! + This directory contains files necessary for EAR packaging. The only file that is of interest from a user perspective is <filename>gatein-wsse-consumer.xml</filename> which allows you to configure WS-Security support for the consumer. </para> + + <para> + Refer to <xref linkend="sect-Reference_Guide-Deploying_WSRP-WS-Security_Configuration"/> section for more details. + </para> </listitem> </varlistentry> @@ -213,8 +217,12 @@ <listitem> <para> - This file contains the producer-side support for WS-Security. !!!!TODO mwringe: please detail if there are any user-modifiable configuration file there and how this files is different in AS 6 !!!! + This file contains the producer-side support for WS-Security. The only file of interest from a user perspective is <filename>gatein-wsse-producer.xml</filename> which allows you to configure WS-Security support for the producer. </para> + + <para> + Refer to <xref linkend="sect-Reference_Guide-Deploying_WSRP-WS-Security_Configuration"/> for more details. + </para> </listitem> </varlistentry> </variablelist> @@ -240,7 +248,181 @@ </section> </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Making_a_Portlet_Remotable"> + <section id="sect-Reference_Guide-Deploying_WSRP-WSRP_and_WS-Security"> + <title>WSRP and WS-Security</title> + + <para> + Portlets may present different data or options depending on the currently authenticated user. For remote portlets, this means having to propagate the user credentials from the consumer back to the producer in a safe and secure manner. + </para> + <para> + The WSRP specification does not directly specify how this should be accomplished, but delegates this work to the existing WS-Security standards. + </para> + + <note> + <title>Web Container Compatibility</title> + + <para> + WSRP and WS-Security is currently only supported on JBoss Enterprise Portal Platform when running on top of JBoss AS 5. + </para> + </note> + + <warning> + <title>Encryption</title> + + <para> + <emphasis role="bold">The use of encryption is strongly recommended.</emphasis> + </para> + + <para> + Credentials being sent between the consumer and producer should be encrypted or they will be sent in plain text and could be easily intercepted. + </para> + <para> + You can either configure WS-Security to encrypt and sign the SOAP messages being sent, or secure the transport layer by using an <literal>https</literal> endpoint. + </para> + <para> + Failure to encrypt the SOAP message or transport layer will result in the username and password being sent in plain text. + </para> + + </warning> + + <important> + <title>Credentials</title> + + <para> + When the consumer sends the user credentials to the producer, it is sending the credentials for the currently authenticated user in the consumer. This makes signing in to remote portlets transparent to end users, but also requires that the producer and consumer use the same credentials. + </para> + <para> + The username and password must be the same and valid on both servers. + </para> + + <para> + The recommended approach for this situation would be to use a common LDAP configuration. Please see the User Guide at <ulink type="http" url="docs.redhat.com"></ulink> for information on how to configure LDAP for use with JBoss Enterprise Portal Platform + </para> + </important> + + <para> + This community Wiki <ulink url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity...;, also provides a step-by-step example on how to configure WSRP with WS-Security. + </para> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WS-Security_Configuration"> + <title>WS-Security Configuration</title> + + <para> + JBoss Enterprise Portal Platform uses <application>JBossWS Native</application> to handle ws-security. + </para> + <para> + Refer to the WS-Security section of the <ulink url="http://www.jboss.org/jbossas/docs/5-x">JBoss AS 5 Administration and Configuration Guide </ulink> for in-depth configuration options. + </para> + <para> + Please note that since the consumer passes its credentials to the producer, the consumer will act at the wss client and the producer will act as the wss server. + </para> + + <para> + The following are the JBossWS Native configuration files which need to be configure for WSRP: + </para> + <variablelist> + <title></title> + <varlistentry> + <term>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</term> + <listitem> + <para> + BossWS configuration file for the consumer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml</term> + <listitem> + <para> + JBossWS configuration file for the producer. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WS-Security_Producer_Configuration"> + <title>WS-Security Producer Configuration</title> + + <para> + Other than the JBossWS configuration file mention above, no other configuration changes should be necessary for the producer. + </para> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WS-Security_Consumer_Configuration"> + <title>WS-Security Consumer Configuration</title> + + <para> + The consumer requires some changes before it will function properly with WS-Security. + </para> + <para> + The consumer needs access to the current servlet request since this is used to retrieve the currently authenticated user. In order to access this information, the consumer needs a special servlet-filter added to the portal. + </para> + <procedure> + <title>Add the servlet-filter</title> + <step> + <para> + Open <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> and add the following: + </para> +<programlisting role="XML"><![CDATA[<!-- Filter to put request and response in ServletAccess --> + <filter> + <filter-name>ServletAccessFilter</filter-name> + <filter-class>org.gatein.wsrp.servlet.ServletAccessFilter</filter-class> + </filter> + <filter-mapping> + <filter-name>ServletAccessFilter</filter-name> + <url-pattern>/*</url-pattern> + </filter-mapping>]]> +</programlisting> + </step> + <step> + <para> + Check the <guilabel>Enable WS Security</guilabel> checkbox in the consumer configuration options of the WSRP Configuration portlet + </para> + </step> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_wss_selected.png" format="PNG" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </procedure> + + </section> + + <note> + <title>WS-Security Consumer Checklist</title> + + <para> + In order for the consumer to handle ws-security, the following items must be implemented: + </para> + + <orderedlist> + <listitem> + <para> + The JBossWS configuration files must be configured + </para> + </listitem> + + <listitem> + <para> + The filter must be added to the portal's web.xml + </para> + </listitem> + + <listitem> + <para> + the enable wss feature must be check in the wsrp admin + </para> + </listitem> + </orderedlist> + + <para> + The consumer will not properly handle ws-security unless all three items are correctly configured. + </para> + </note> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Making_a_Portlet_Remotable"> <title>Making a Portlet Remotable</title> <note> @@ -290,22 +472,15 @@ </para> <para> - In the example above, the - <varname> - RemotelyExposedPortlet - </varname> - inherits the remotable status defined at the <code>portlet-app</code> level since it does not specify a value for the <code>org.gatein.pc.remotable container-runtime-option</code>. + In the example above, the <literal>RemotelyExposedPortlet</literal> 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 <literal>NotRemotelyExposedPortlet</literal>, however, overrides the default behavior and is not remotely exposed. </para> <note> + <title>Note</title> <para> Portlets are not remotely exposed if no top-level <code>org.gatein.pc.remotable container-runtime-option</code> value is set to <code>true</code>. </para> @@ -371,7 +546,7 @@ </para> <para> - Access to a remote producer can be configured using WSRP Producer descriptors. Alternatively, a portlet is provided to configure remote producers. + Access to a remote producer can be configured using the provided configuration portlet. Alternatively, it is also possible to configure access to remote producers using an XML descriptor. The configuration portlet is the recommended method. </para> <para> @@ -388,8 +563,11 @@ <title>Configuring a Remote Producer</title> <para> - Access to a remote producer needs to be defined so that portlets can be consumed within JBoss Enterprise Portal Platform. 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. + Access to a remote producer needs to be defined so that portlets can be consumed within JBoss Enterprise Portal Platform. This section will show how to configure access to <emphasis role="bold">NetUnity</emphasis>'s public WSRP producer. </para> + <para> + Firstly using the configuration portlet and 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> <important> <title>Chunked Encoding</title> @@ -483,13 +661,18 @@ <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> + Type "<literal>netunity</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> + <step> + <para> + Click on "<emphasis role="bold">Create consumer</emphasis>" to create a new Consumer called <literal>netunity</literal>. + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/config_create.png" format="PNG" scale="100" /> </imageobject> @@ -497,23 +680,33 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_create.png" format="PNG" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <step> + <para> In the next form, set the cache expiration value to <parameter>300</parameter> seconds. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Leave the default timeout value for web services (WS) operations. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Enter the WSDL URL for the producer in the text field. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Press the "Refresh &amp; Save" button: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/config_wsdl.png" format="PNG" scale="120" /> </imageobject> @@ -521,7 +714,8 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_wsdl.png" format="PNG" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> </procedure> <para> @@ -529,7 +723,7 @@ </para> <para> - In this case, querying the service description will show that the Producer requires registration but did not request any registration property: + In this case, querying the service description will show that the Producer requires registration, that it requested three registration properties and that the current configuration is missing values for these properties: </para> <mediaobject> @@ -538,25 +732,25 @@ </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_refresh.png" format="PNG" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_missing.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. + This particular producer requests simple <literal>Yes</literal> or <literal>No</literal> values for the three registration properties. </para> <para> - Assuming that the producer required a value for an <literal>email</literal> registration property, JBoss Enterprise Portal Platform's WSRP consumer will report that some information was missing: + Enter <literal>No</literal>, <literal>Yes</literal> and <literal>No</literal> (in that order) for the values and then pressing the "Refresh &amp; Save" button should result in: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_missing.png" format="PNG" scale="120" /> + <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scale="120" width="444" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_missing.png" format="PNG" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_end.png" format="PNG" width="444" /> </imageobject> </mediaobject> @@ -564,21 +758,25 @@ <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. + Unfortunately 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: + The Consumer for the <literal>netunity</literal> Producer should now be available as a portlet provider and be ready to be used. </para> + <para> + If the producer had required registration but did not require any registration properties, as is the case for the <literal>selfv2</literal> consumer (the consumer that accesses the portlets made remotely available by JBoss Enterprise Portal Platform's producer via WSRP 2), the following screen would have appeared after pressing the "Refresh &amp; Save" button: + </para> + <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scale="120" /> + <imagedata align="center" fileref="images/WSRP/config_refresh.png" format="PNG" scale="120" width="444" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_end.png" format="PNG" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_refresh.png" format="PNG" width="444" /> </imageobject> </mediaobject> </section> @@ -592,74 +790,33 @@ </para> <para> - This is done by editing the XML file located at <filename>extension-component-<replaceable>&lt;PORTAL_VERSION&gt;</replaceable>.jar/conf/wsrp-consumers-config.xml</filename> in your JBoss AS deploy directory. + This is done by editing the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/wsrp-consumers-config.xml</filename> XML file. </para> +<!-- Removed in GateIn revision 8119 <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 JBoss Enterprise Portal Platform'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>--> + <note> + <title>XML Elements</title> - <note> <para> An XML Schema defining which elements are available to configure Consumers via XML can be found in <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> </para> </note> - </section> +<!-- Removed in GateIn revision 8119 - <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-Adding_remote_portlets_to_categories"> - <title>Adding remote portlets to categories</title> - - <para> - Clicking on the Portlet link in the Application Registry will now show the remote portlets 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="120" /> - </imageobject> - - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" /> - </imageobject> - </mediaobject> - - <para> - 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, to add a <emphasis>WSRP</emphasis> portlet to a category, select <literal>wsrp</literal> in the Application Type drop-down menu: - </para> - - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/remote_portlets_category.png" format="PNG" scalefit="1" valign="middle" /> - </imageobject> - </mediaobject> - </section> - </section> - - <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-Configuring_Access_to_Remote_Producers_via_XML"> + <section id="sect-Reference_Guide_eXo_JCR_1.14-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>WSRP_PATH</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.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><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> - </para> - </note> - - <note> - <title>The Consumer Configuration file</title> - - <para> + </para> --> + <formalpara> + <title>The Consumer Configuration file</title> <para> 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> + </formalpara> <para> Subsequent launches of the WSRP service will use the JCR-stored information for all producers that are already known to JBoss Enterprise Portal Platform. 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. @@ -676,7 +833,6 @@ <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> @@ -789,8 +945,13 @@ <title>Examples</title> <para> - This is the configuration of the <literal>selfv1</literal> and <literal>selfv2</literal> consumers 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>selfv1</literal> and <literal>selfv2</literal> consumers as found in <filename>default-wsrp.xml</filename> with a cache expiring every 500 seconds and with a 50 second timeout for web service operations: </para> + <note> + <para> + This file contains the default configuration and should not need to be edited. If modifications are required, the recommended practice is to follow the procedure detailed in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet"/>. + </para> + </note> <programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default258.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> This is an example of a WSRP descriptor with registration data and cache expiring every minute: @@ -799,7 +960,40 @@ </section> </section> - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consumers_Maintenance"> + <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-Adding_remote_portlets_to_categories"> + <title>Adding remote portlets to categories</title> + + <para> + Clicking on the Portlet link in the Application Registry will now show the remote portlets 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="120" width="444" /> + </imageobject> + + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" width="444" /> + </imageobject> + </mediaobject> + + <para> + 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, to add a <emphasis>WSRP</emphasis> portlet to a category, select <literal>wsrp</literal> in the Application Type drop-down menu: + </para> + + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/WSRP/remote_portlets_category.png" format="PNG" scalefit="1" valign="middle" /> + </imageobject> + </mediaobject> + </section> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consumers_Maintenance"> <title>Consumers Maintenance</title> <section id="sect-Reference_Guide-Consumers_Maintenance-Modifying_a_Currently_Held_Registration"> @@ -833,9 +1027,12 @@ </para> <procedure> - <step><para> + <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 <literal&gt;example(a)example.com&lt;/literal&gt;: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/modify_reg_start.png" format="PNG" scale="100" /> </imageobject> @@ -843,11 +1040,15 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png" format="PNG" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <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> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/modify_reg_modify.png" format="PNG" scale="100" /> </imageobject> @@ -855,11 +1056,15 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png" format="PNG" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <step> + <para> Click on <emphasis role="bold">Modify registration</emphasis> and, if the updated registration details have been accepted by the remote producer the following should appear: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/modify_reg_end.png" format="PNG" scale="120" /> </imageobject> @@ -867,7 +1072,8 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png" format="PNG" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> </procedure> </section> @@ -875,11 +1081,7 @@ <title>Registration Modification on Producer Error</title> <para> - If a Producer administrator changes the requirements for registered consumers, invoking operations on the producer may fail with an - <exceptionname> - OperationFailedFault - </exceptionname> - . JBoss Enterprise Portal Platform will attempt to assist in these cases. + If a Producer administrator changes the requirements for registered consumers, invoking operations on the producer may fail with an <exceptionname>OperationFailedFault</exceptionname>. JBoss Enterprise Portal Platform will attempt to assist in these cases. </para> <para> @@ -940,19 +1142,11 @@ <title><emphasis role="bold">JBoss Enterprise Portal Platform &VY; and WSRP 1 Exceptions</emphasis></title> <para> - 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. + 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. + 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> @@ -1091,9 +1285,12 @@ <procedure> <title></title> - <step><para> + <step> + <para> Click on the "<guilabel>Export</guilabel>" action for a given consumer to display the list of portlets currently made available by this specific consumer. An example list is shown below: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata fileref="images/WSRP/export_portlet_list.png" format="PNG" align="center" scale="120" /> </imageobject> @@ -1101,11 +1298,15 @@ <imageobject role="fo"> <imagedata fileref="images/WSRP/export_portlet_list.png" format="PNG" align="center" contentwidth="150mm" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <step> + <para> Once portlets have been selected, they can be exported by clicking on the "<guilabel>Export</guilabel>" button. This makes them available for later import: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata fileref="images/WSRP/export_done.png" format="PNG" align="center" scale="120" /> </imageobject> @@ -1113,13 +1314,19 @@ <imageobject role="fo"> <imagedata fileref="images/WSRP/export_done.png" format="PNG" align="center" contentwidth="150mm" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <step> + <para> The portlets can be re-imported directly by pressing the "<guilabel>Use for import</guilabel>" button or, on the Consumers list page, using the "<guilabel>Import</guilabel>" action for a given consumer. - </para> <para> + </para> + + <para> The example below assumes that the second option has been used and that several sets of previously exported portlets are available to import from. After clicking the action link, a screen similar to the one below should appear: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata fileref="images/WSRP/export_list.png" format="PNG" align="center" scale="120" /> </imageobject> @@ -1127,9 +1334,12 @@ <imageobject role="fo"> <imagedata fileref="images/WSRP/export_list.png" format="PNG" align="center" contentwidth="150mm" /> </imageobject> - </mediaobject> <para> + </mediaobject> + + <para> This screen presents the list of available exports with available operations for each. - </para> <variablelist> + </para> + <variablelist> <title>Operations:</title> <varlistentry> @@ -1161,11 +1371,15 @@ </para> </listitem> </varlistentry> - </variablelist></step> + </variablelist> + </step> - <step><para> + <step> + <para> Once you have selected an export to import from, you will see a screen similar to the one below: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata fileref="images/WSRP/import_start.png" format="PNG" align="center" scale="120" /> </imageobject> @@ -1173,15 +1387,23 @@ <imageobject role="fo"> <imagedata fileref="images/WSRP/import_start.png" format="PNG" align="center" contentwidth="150mm" /> </imageobject> - </mediaobject> <para> + </mediaobject> + + <para> The screen displays the list of available exported portlets for the previously selected export. You can select which portlet you want to import by checking the checkbox next to its name. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Select the content of which window the imported portlet will replace. This process is done in three steps: - </para> <para> + </para> + + <para> This example assumes that you have the following page called <literal>page1</literal> which contains two windows called <literal>NetUnity WSRP 2 Interop - Cache Markup (remote)</literal> and <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal>, as shown below: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata fileref="images/WSRP/import_original_page.png" format="PNG" align="center" scale="120" /> </imageobject> @@ -1189,18 +1411,27 @@ <imageobject role="fo"> <imagedata fileref="images/WSRP/import_original_page.png" format="PNG" align="center" contentwidth="150mm" /> </imageobject> - </mediaobject> <para> + </mediaobject> + + <para> In this example, we want to replace the content of the <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> with the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet that was previously exported. - </para> <procedure> + </para> + + <procedure> <title></title> - <step><para> + <step> + <para> Check the box next to the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet name to indicate that you want to import its data. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Select <literal>page1</literal> in the list of available pages. The screen will then refresh to display the list of available windows on that page, similar to the image below: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata fileref="images/WSRP/import_selected_page.png" format="PNG" align="center" scale="120" /> </imageobject> @@ -1208,21 +1439,29 @@ <imageobject role="fo"> <imagedata fileref="images/WSRP/import_selected_page.png" format="PNG" align="center" contentwidth="150mm" /> </imageobject> - </mediaobject> <note> + </mediaobject> + + <note> <title>Note</title> <para> At this point, you still need to select which window content you want to replace before being able to complete the import operation </para> - </note></step> + </note> + </step> - <step><para> + <step> + <para> Select the <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> window, which enables the "<guilabel>Import</guilabel>" button. This indicates that all the necessary data to perform the import is available. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Click the "<guilabel>Import</guilabel>" button. A screen similar to the one below will appear: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata fileref="images/WSRP/import_success.png" format="PNG" align="center" scale="120" /> </imageobject> @@ -1230,12 +1469,17 @@ <imageobject role="fo"> <imagedata fileref="images/WSRP/import_success.png" format="PNG" align="center" contentwidth="150mm" /> </imageobject> - </mediaobject></step> - </procedure></step> + </mediaobject> + </step> + </procedure> + </step> - <step><para> + <step> + <para> The <literal>page1</literal> page should now show that the content of <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> window has been replaced by the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> imported portlet and that the window has been renamed appropriately. - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata fileref="images/WSRP/import_modified_page.png" format="PNG" align="center" scale="120" /> </imageobject> @@ -1243,7 +1487,8 @@ <imageobject role="fo"> <imagedata fileref="images/WSRP/import_modified_page.png" format="PNG" align="center" contentwidth="150mm" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> </procedure> </section> </section> @@ -1390,15 +1635,22 @@ </mediaobject> <procedure> - <step><para> + <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> + </para> + </step> - <step><para> + <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> + </para> + + <para> The screen will refresh and display: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/producer_registration.png" format="PNG" width="700" /> </imageobject> @@ -1406,15 +1658,21 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_registration.png" format="PNG" /> </imageobject> - </mediaobject></step> + </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. - </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_eXo_JCR_1.14-Registration_Configuration-Customization_of_Registration_Handling_Behavior" /> for more information. + </para> + </step> - <step><para> + <step> + <para> 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> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/producer_email.png" format="PNG" width="700" /> </imageobject> @@ -1422,11 +1680,14 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_email.png" format="PNG" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <step> + <para> Press "Save" to record the modifications. - </para></step> + </para> + </step> </procedure> <note> Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml 2011-11-22 21:19:52 UTC (rev 8121) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml 2011-11-23 03:39:01 UTC (rev 8122) @@ -153,8 +153,12 @@ <listitem> <para> - This directory contains files necessary for EAR packaging. The only file that is of interest from a user perspective is <filename>gatein-wsse-consumer.xml</filename> which allows you to configure WS-Security support for the consumer. !!!TODO mwringe please detail !!!! + This directory contains files necessary for EAR packaging. The only file that is of interest from a user perspective is <filename>gatein-wsse-consumer.xml</filename> which allows you to configure WS-Security support for the consumer. </para> + + <para> + Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WS-Security_Configuration"/> section for more details. + </para> </listitem> </varlistentry> @@ -213,8 +217,12 @@ <listitem> <para> - This file contains the producer-side support for WS-Security. !!!!TODO mwringe: please detail if there are any user-modifiable configuration file there and how this files is different in AS 6 !!!! + This file contains the producer-side support for WS-Security. The only file of interest from a user perspective is <filename>gatein-wsse-producer.xml</filename> which allows you to configure WS-Security support for the producer. </para> + + <para> + Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WS-Security_Configuration"/> for more details. + </para> </listitem> </varlistentry> </variablelist> @@ -240,6 +248,180 @@ </section> </section> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WSRP_and_WS-Security"> + <title>WSRP and WS-Security</title> + + <para> + Portlets may present different data or options depending on the currently authenticated user. For remote portlets, this means having to propagate the user credentials from the consumer back to the producer in a safe and secure manner. + </para> + <para> + The WSRP specification does not directly specify how this should be accomplished, but delegates this work to the existing WS-Security standards. + </para> + + <note> + <title>Web Container Compatibility</title> + + <para> + WSRP and WS-Security is currently only supported on JBoss Enterprise Portal Platform when running on top of JBoss AS 5. + </para> + </note> + + <warning> + <title>Encryption</title> + + <para> + <emphasis role="bold">The use of encryption is strongly recommended.</emphasis> + </para> + + <para> + Credentials being sent between the consumer and producer should be encrypted or they will be sent in plain text and could be easily intercepted. + </para> + <para> + You can either configure WS-Security to encrypt and sign the SOAP messages being sent, or secure the transport layer by using an <literal>https</literal> endpoint. + </para> + <para> + Failure to encrypt the SOAP message or transport layer will result in the username and password being sent in plain text. + </para> + + </warning> + + <important> + <title>Credentials</title> + + <para> + When the consumer sends the user credentials to the producer, it is sending the credentials for the currently authenticated user in the consumer. This makes signing in to remote portlets transparent to end users, but also requires that the producer and consumer use the same credentials. + </para> + <para> + The username and password must be the same and valid on both servers. + </para> + + <para> + The recommended approach for this situation would be to use a common LDAP configuration. Please see the User Guide at <ulink type="http" url="docs.redhat.com"></ulink> for information on how to configure LDAP for use with JBoss Enterprise Portal Platform + </para> + </important> + + <para> + This community Wiki <ulink url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity...;, also provides a step-by-step example on how to configure WSRP with WS-Security. + </para> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WS-Security_Configuration"> + <title>WS-Security Configuration</title> + + <para> + JBoss Enterprise Portal Platform uses <application>JBossWS Native</application> to handle ws-security. + </para> + <para> + Refer to the WS-Security section of the <ulink url="http://www.jboss.org/jbossas/docs/5-x">JBoss AS 5 Administration and Configuration Guide </ulink> for in-depth configuration options. + </para> + <para> + Please note that since the consumer passes its credentials to the producer, the consumer will act at the wss client and the producer will act as the wss server. + </para> + + <para> + The following are the JBossWS Native configuration files which need to be configure for WSRP: + </para> + <variablelist> + <title></title> + <varlistentry> + <term>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</term> + <listitem> + <para> + BossWS configuration file for the consumer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml</term> + <listitem> + <para> + JBossWS configuration file for the producer. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WS-Security_Producer_Configuration"> + <title>WS-Security Producer Configuration</title> + + <para> + Other than the JBossWS configuration file mention above, no other configuration changes should be necessary for the producer. + </para> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WS-Security_Consumer_Configuration"> + <title>WS-Security Consumer Configuration</title> + + <para> + The consumer requires some changes before it will function properly with WS-Security. + </para> + <para> + The consumer needs access to the current servlet request since this is used to retrieve the currently authenticated user. In order to access this information, the consumer needs a special servlet-filter added to the portal. + </para> + <procedure> + <title>Add the servlet-filter</title> + <step> + <para> + Open <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> and add the following: + </para> +<programlisting role="XML"><![CDATA[<!-- Filter to put request and response in ServletAccess --> + <filter> + <filter-name>ServletAccessFilter</filter-name> + <filter-class>org.gatein.wsrp.servlet.ServletAccessFilter</filter-class> + </filter> + <filter-mapping> + <filter-name>ServletAccessFilter</filter-name> + <url-pattern>/*</url-pattern> + </filter-mapping>]]> +</programlisting> + </step> + <step> + <para> + Check the <guilabel>Enable WS Security</guilabel> checkbox in the consumer configuration options of the WSRP Configuration portlet + </para> + </step> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_wss_selected.png" format="PNG" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </procedure> + + </section> + + <note> + <title>WS-Security Consumer Checklist</title> + + <para> + In order for the consumer to handle ws-security, the following items must be implemented: + </para> + + <orderedlist> + <listitem> + <para> + The JBossWS configuration files must be configured + </para> + </listitem> + + <listitem> + <para> + The filter must be added to the portal's web.xml + </para> + </listitem> + + <listitem> + <para> + the enable wss feature must be check in the wsrp admin + </para> + </listitem> + </orderedlist> + + <para> + The consumer will not properly handle ws-security unless all three items are correctly configured. + </para> + </note> + </section> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Making_a_Portlet_Remotable"> <title>Making a Portlet Remotable</title> @@ -365,26 +547,30 @@ </para> <para> - Access to a remote producer can be configured using WSRP Producer descriptors. Alternatively, a portlet is provided to configure remote producers. + Access to a remote producer can be configured using the provided configuration portlet. Alternatively, it is also possible to configure access to remote producers using an XML descriptor. The configuration portlet is the recommended method. </para> <para> Once a remote producer has been configured, the portlets that it exposes are then available in the Application Registry to be added to categories and then to pages. </para> -<!-- Removed as out of date and not in Community version of doc. +<!-- Removed as out of date and not in Community version of doc. <para> A default consumer named <literal>self</literal>, that consumes the portlets exposed by JBoss Enterprise Portal Platform'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_eXo_JCR_1.14-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 JBoss Enterprise Portal Platform. 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. + Access to a remote producer needs to be defined so that portlets can be consumed within JBoss Enterprise Portal Platform. This section will show how to configure access to <emphasis role="bold">NetUnity</emphasis>'s public WSRP producer. </para> + <para> + Firstly using the configuration portlet and 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> + <important> <title>Chunked Encoding</title> @@ -428,17 +614,23 @@ <procedure id="proc-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Installing_the_configuration_portlet"> <title><emphasis role="bold">Installing the configuration portlet:</emphasis></title> - <step><para> + <step> + <para> Log into the portal as an administrator and go to the Application Registry (Click <ulink url="http://localhost:8080/portal/private/classic/administration/registry">http://localhost:8080/portal/private/classic/administration/registry</ulink> if using the default installation). - </para></step> + </para> + </step> - <step><para> + <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> + </para> + </step> - <step><para> + <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> + </para> + </step> </procedure> <section id="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet"> @@ -477,13 +669,18 @@ <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Using_the_Configuration_portlet-Creating_a_Consumer"> <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> + Type "<literal>netunity</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> + <step> + <para> + Click on "<emphasis role="bold">Create consumer</emphasis>" to create a new Consumer called <literal>netunity</literal>. + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/config_create.png" format="PNG" scale="100" width="444" /> </imageobject> @@ -491,23 +688,33 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_create.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <step> + <para> In the next form, set the cache expiration value to <parameter>300</parameter> seconds. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Leave the default timeout value for web services (WS) operations. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Enter the WSDL URL for the producer in the text field. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Press the "Refresh &amp; Save" button: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/config_wsdl.png" format="PNG" scale="120" width="444" /> </imageobject> @@ -515,7 +722,8 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_wsdl.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> </procedure> <para> @@ -523,34 +731,34 @@ </para> <para> - In this case, querying the service description will show that the Producer requires registration but did not request any registration property: + In this case, querying the service description will show that the Producer requires registration, that it requested three registration properties and that the current configuration is missing values for these properties: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_refresh.png" format="PNG" scale="120" width="444" /> + <imagedata align="center" fileref="images/WSRP/config_missing.png" format="PNG" scale="120" width="444" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_refresh.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_missing.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. + This particular producer requests simple <literal>Yes</literal> or <literal>No</literal> values for the three registration properties. </para> <para> - Assuming that the producer required a value for an <literal>email</literal> registration property, JBoss Enterprise Portal Platform's WSRP consumer will report that some information was missing: + Enter <literal>No</literal>, <literal>Yes</literal> and <literal>No</literal> (in that order) for the values and then pressing the "Refresh &amp; Save" button should result in: </para> <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_missing.png" format="PNG" scale="120" width="444" /> + <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scale="120" width="444" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_missing.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_end.png" format="PNG" width="444" /> </imageobject> </mediaobject> @@ -558,21 +766,25 @@ <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. + Unfortunately 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: + The Consumer for the <literal>netunity</literal> Producer should now be available as a portlet provider and be ready to be used. </para> + <para> + If the producer had required registration but did not require any registration properties, as is the case for the <literal>selfv2</literal> consumer (the consumer that accesses the portlets made remotely available by JBoss Enterprise Portal Platform's producer via WSRP 2), the following screen would have appeared after pressing the "Refresh &amp; Save" button: + </para> + <mediaobject> <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scale="120" width="444" /> + <imagedata align="center" fileref="images/WSRP/config_refresh.png" format="PNG" scale="120" width="444" /> </imageobject> <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_end.png" format="PNG" width="444" /> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_refresh.png" format="PNG" width="444" /> </imageobject> </mediaobject> </section> @@ -586,76 +798,35 @@ </para> <para> - This is done by editing the XML file located at <filename>extension-component-<replaceable>&lt;PORTAL_VERSION&gt;</replaceable>.jar/conf/wsrp-consumers-config.xml</filename> in your JBoss AS deploy directory. + This is done by editing the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/wsrp-consumers-config.xml</filename> XML file. </para> +<!-- Removed in GateIn revision 8119 <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 JBoss Enterprise Portal Platform'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 file as shown above specifies access to two producers: <literal>self</literal>, which consumes JBoss Enterprise Portal Platform'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> + <title>XML Elements</title> + <para> An XML Schema defining which elements are available to configure Consumers via XML can be found in <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> </para> </note> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-Adding_remote_portlets_to_categories"> - <title>Adding remote portlets to categories</title> - - <para> - Clicking on the Portlet link in the Application Registry will now show the remote portlets 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="120" width="444" /> - </imageobject> - - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - - <para> - 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, to add a <emphasis>WSRP</emphasis> portlet to a category, select <literal>wsrp</literal> in the Application Type drop-down menu: - </para> - - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/remote_portlets_category.png" format="PNG" scalefit="1" valign="middle" /> - </imageobject> - </mediaobject> - </section> - </section> +<!-- Removed in GateIn revision 8119 <section id="sect-Reference_Guide_eXo_JCR_1.14-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>WSRP_PATH</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar/conf/wsrp-consumers-config.xml</filename>. - </para> - - <note> - <title>XML Elements</title> + </para> --> + <formalpara> + <title>The Consumer Configuration file</title> <para> + 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> + </formalpara> <para> - An XML Schema defining which elements are available to configure Consumers via XML can be found in <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> - </para> - </note> - - <note> - <title>The Consumer Configuration file</title> - - <para> - 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 JBoss Enterprise Portal Platform. 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> @@ -670,126 +841,164 @@ <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_eXo_JCR_1.14-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> - - <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> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_Access_to_Remote_Producers_via_XML-Required_Configuration_Information"> + <title>Required Configuration Information</title> - <listitem> - <para> - JBoss Enterprise Portal Platform 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> - Both the <literal>id</literal> attribute and <literal>&lt;endpoint-wsdl-url&gt;</literal> elements are required for a functional remote producer configuration. - </para> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-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_eXo_JCR_1.14-Optional_Configuration-Optional_Configurations"> - <title>Optional Configurations</title> + <para> + The following information needs to be provided to configure access to a remote Producer: + </para> - <varlistentry> - <term>Caching</term> - + <orderedlist> <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. + 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> - - <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 <literal>120</literal> for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been accessed. If no value is provided, JBoss Enterprise Portal Platform 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> </listitem> - </varlistentry> - - <varlistentry> - <term>WS Timeout</term> <listitem> <para> - It is also possible to define a timeout after which WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, as it waits on a service that does not answer. + JBoss Enterprise Portal Platform 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> - - <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> + </orderedlist> - <varlistentry> - <term>Pre-registration information</term> + <para> + Both the <literal>id</literal> attribute and <literal>&lt;endpoint-wsdl-url&gt;</literal> elements are required for a functional remote producer configuration. + </para> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-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_eXo_JCR_1.14-Optional_Configuration-Optional_Configurations"> + <title>Optional Configurations</title> - <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> + <varlistentry> + <term>Caching</term> - <note> + <listitem> <para> - Only simple String properties are supported. It is not possible to configure complex registration data. However, this should be sufficient for most cases. + 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> - </note> + + <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 <literal>120</literal> for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been accessed. If no value is provided, JBoss Enterprise Portal Platform 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> + </listitem> + </varlistentry> + + <varlistentry> + <term>WS Timeout</term> - <para> - This pre-registration configuration is done via the <literal>&lt;registration-data&gt;</literal> element. - </para> + <listitem> + <para> + It is also possible to define a timeout after which WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, as it waits on a service that does not answer. + </para> + + <para> + Use the <literal>ws-timeout</literal> attribute of the <literal>&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> - <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 JBoss Enterprise Portal Platform 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 JBoss Enterprise Portal Platform 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> + <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> + Only simple String properties are supported. It is not possible to configure complex registration data. However, this should be sufficient for most cases. + </para> + </note> + + <para> + This pre-registration configuration is done via the <literal>&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 JBoss Enterprise Portal Platform 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 JBoss Enterprise Portal Platform 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_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Examples"> + <title>Examples</title> + + <para> + This is the configuration of the <literal>selfv1</literal> and <literal>selfv2</literal> consumers as found in <filename>default-wsrp.xml</filename> with a cache expiring every 500 seconds and with a 50 second timeout for web service operations: + </para> + + <note> + <para> + This file contains the default configuration and should not need to be edited. If modifications are required, the recommended practice is to follow the procedure detailed in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet"/>. + </para> + </note> +<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default258.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + This is an example of a WSRP descriptor with registration data and cache expiring every minute: + </para> +<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default259.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> </section> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Examples"> - <title>Examples</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-Adding_remote_portlets_to_categories"> + <title>Adding remote portlets to categories</title> <para> - This is the configuration of the <literal>selfv1</literal> and <literal>selfv2</literal> consumers 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: + Clicking on the Portlet link in the Application Registry will now show the remote portlets in the <emphasis role="bold">REMOTE</emphasis> tab in the left column: </para> -<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default258.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/remote_portlets.png" format="PNG" scale="120" width="444" /> + </imageobject> + + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" width="444" /> + </imageobject> + </mediaobject> + <para> - This is an example of a WSRP descriptor with registration data and cache expiring every minute: + 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> -<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default259.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> + 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> + <imagedata align="center" fileref="images/WSRP/remote_portlets_category.png" format="PNG" scalefit="1" valign="middle" /> + </imageobject> + </mediaobject> </section> </section> @@ -827,9 +1036,12 @@ </para> <procedure> - <step><para> + <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 <literal&gt;example(a)example.com&lt;/literal&gt;: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/modify_reg_start.png" format="PNG" scale="100" width="444" /> </imageobject> @@ -837,11 +1049,15 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <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> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/modify_reg_modify.png" format="PNG" scale="100" width="444" /> </imageobject> @@ -849,11 +1065,15 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <step> + <para> Click on <emphasis role="bold">Modify registration</emphasis> and, if the updated registration details have been accepted by the remote producer the following should appear: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/modify_reg_end.png" format="PNG" scale="120" width="444" /> </imageobject> @@ -861,7 +1081,8 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> </procedure> </section> @@ -869,7 +1090,7 @@ <title>Registration Modification on Producer Error</title> <para> - If a Producer administrator changes the requirements for registered consumers, invoking operations on the producer may fail with an <literal>OperationFailedFault</literal>. JBoss Enterprise Portal Platform will attempt to assist in these cases. + If a Producer administrator changes the requirements for registered consumers, invoking operations on the producer may fail with an <exceptionname>OperationFailedFault</exceptionname>. JBoss Enterprise Portal Platform will attempt to assist in these cases. </para> <para> @@ -930,11 +1151,11 @@ <title><emphasis role="bold">JBoss Enterprise Portal Platform &VY; and WSRP 1 Exceptions</emphasis></title> <para> - In WSRP 1, it can be difficult to ascertain what caused an <literal> OperationFailedFault </literal> 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 <literal>OperationFailedFault</literal> failure can be caused by several different reasons, one of them being a request to modify the registration data. + 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> @@ -1073,9 +1294,12 @@ <procedure> <title></title> - <step><para> + <step> + <para> Click on the "<guilabel>Export</guilabel>" action for a given consumer to display the list of portlets currently made available by this specific consumer. An example list is shown below: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/export_portlet_list.png" format="PNG" scale="120" width="444" /> </imageobject> @@ -1083,11 +1307,15 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/export_portlet_list.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <step> + <para> Once portlets have been selected, they can be exported by clicking on the "<guilabel>Export</guilabel>" button. This makes them available for later import: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/export_done.png" format="PNG" scale="120" width="444" /> </imageobject> @@ -1095,13 +1323,19 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/export_done.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <step> + <para> The portlets can be re-imported directly by pressing the "<guilabel>Use for import</guilabel>" button or, on the Consumers list page, using the "<guilabel>Import</guilabel>" action for a given consumer. - </para> <para> + </para> + + <para> The example below assumes that the second option has been used and that several sets of previously exported portlets are available to import from. After clicking the action link, a screen similar to the one below should appear: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/export_list.png" format="PNG" scale="120" width="444" /> </imageobject> @@ -1109,9 +1343,13 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/export_list.png" format="PNG" width="444" /> </imageobject> - </mediaobject> <para> + </mediaobject> + + <para> This screen presents the list of available exports with available operations for each. - </para> <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Importing_and_Exporting_Portlets-Operations"> + </para> + + <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Importing_and_Exporting_Portlets-Operations"> <title>Operations:</title> <varlistentry> @@ -1143,11 +1381,15 @@ </para> </listitem> </varlistentry> - </variablelist></step> + </variablelist> + </step> - <step><para> + <step> + <para> Once you have selected an export to import from, you will see a screen similar to the one below: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/import_start.png" format="PNG" scale="120" width="444" /> </imageobject> @@ -1155,15 +1397,23 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_start.png" format="PNG" width="444" /> </imageobject> - </mediaobject> <para> + </mediaobject> + + <para> The screen displays the list of available exported portlets for the previously selected export. You can select which portlet you want to import by checking the checkbox next to its name. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Select the content of which window the imported portlet will replace. This process is done in three steps: - </para> <para> + </para> + + <para> This example assumes that you have the following page called <literal>page1</literal> which contains two windows called <literal>NetUnity WSRP 2 Interop - Cache Markup (remote)</literal> and <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal>, as shown below: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/import_original_page.png" format="PNG" scale="120" width="444" /> </imageobject> @@ -1171,18 +1421,27 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_original_page.png" format="PNG" width="444" /> </imageobject> - </mediaobject> <para> + </mediaobject> + + <para> In this example, we want to replace the content of the <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> with the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet that was previously exported. - </para> <procedure> + </para> + + <procedure> <title></title> - <step><para> + <step> + <para> Check the box next to the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet name to indicate that you want to import its data. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Select <literal>page1</literal> in the list of available pages. The screen will then refresh to display the list of available windows on that page, similar to the image below: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/import_selected_page.png" format="PNG" scale="120" width="444" /> </imageobject> @@ -1190,21 +1449,29 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_selected_page.png" format="PNG" width="444" /> </imageobject> - </mediaobject> <note> + </mediaobject> + + <note> <title>Note</title> <para> At this point, you still need to select which window content you want to replace before being able to complete the import operation </para> - </note></step> + </note> + </step> - <step><para> + <step> + <para> Select the <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> window, which enables the "<guilabel>Import</guilabel>" button. This indicates that all the necessary data to perform the import is available. - </para></step> + </para> + </step> - <step><para> + <step> + <para> Click the "<guilabel>Import</guilabel>" button. A screen similar to the one below will appear: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/import_success.png" format="PNG" scale="120" width="444" /> </imageobject> @@ -1212,12 +1479,17 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_success.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> - </procedure></step> + </mediaobject> + </step> + </procedure> + </step> - <step><para> + <step> + <para> The <literal>page1</literal> page should now show that the content of <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> window has been replaced by the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> imported portlet and that the window has been renamed appropriately. - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/import_modified_page.png" format="PNG" scale="120" width="444" /> </imageobject> @@ -1225,7 +1497,8 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_modified_page.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> </procedure> </section> </section> @@ -1372,15 +1645,22 @@ </mediaobject> <procedure> - <step><para> + <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> + </para> + </step> - <step><para> + <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> + </para> + + <para> The screen will refresh and display: - </para> <mediaobject> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/producer_registration.png" format="PNG" width="700" /> </imageobject> @@ -1388,15 +1668,21 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_registration.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <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_eXo_JCR_1.14-Registration_Configuration-Customization_of_Registration_Handling_Behavior" /> for more information. - </para></step> + </para> + </step> - <step><para> + <step> + <para> 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> + </para> + + <mediaobject> <imageobject role="html"> <imagedata align="center" fileref="images/WSRP/producer_email.png" format="PNG" width="700" /> </imageobject> @@ -1404,11 +1690,14 @@ <imageobject role="fo"> <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_email.png" format="PNG" width="444" /> </imageobject> - </mediaobject></step> + </mediaobject> + </step> - <step><para> + <step> + <para> Press "Save" to record the modifications. - </para></step> + </para> + </step> </procedure> <note> @@ -1419,7 +1708,7 @@ <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_eXo_JCR_1.14-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_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error" />. </para> </note> @@ -1501,7 +1790,7 @@ <para> However, if you wish to completely remove WSRP from your portal installation, remove the <filename>gatein-wsrp-integration.ear</filename> file from your application server deploy directory. </para> -<!--<para> +<!-- <para> However, if you wish to completely remove WSRP from your portal installation, follow this procedure: </para> <procedure> @@ -1835,6 +2124,6 @@ </step> - </procedure> --> + </procedure> --> </section> </chapter>