[gatein-commits] gatein SVN: r9281 - in epp/docs/JPP/trunk: Administration_and_Configuration_Guide/en-US/images and 3 other directories.

Author: jaredmorgs Date: 2013-05-22 01:52:42 -0400 (Wed, 22 May 2013) New Revision: 9281 Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/WSRP.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_create.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_end.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_init.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_missing.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_refresh.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_self.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wsdl.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wss_selected.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/consumer_operations.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration_warning.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_done.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_list.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_portlet_list.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_modified_page.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_original_page.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_selected_page.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_start.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_success.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_end.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_modify.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self_end.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_start.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_blank.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_default.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_email.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_registration.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets.png epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets_category.png Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.ent epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/WSRP.xml epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml Log: Added missing graphics and WSRP section to the Admin Config Guide for Aakanksha to view. Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.ent =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.ent 2013-05-16 04:35:34 UTC (rev 9280) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.ent 2013-05-22 05:52:42 UTC (rev 9281) @@ -14,3 +14,4 @@ <!ENTITY VX "6"> <!ENTITY VY "6.1"> <!ENTITY VZ "6.1.0"> +<!ENTITY WSRP_VERSION "2.2.2.Final"> Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml 2013-05-16 04:35:34 UTC (rev 9280) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Administration_and_Configuration_Guide.xml 2013-05-22 05:52:42 UTC (rev 9281) @@ -1,5 +1,6 @@ <?xml version='1.0' encoding='UTF-8'?> <!-- This document was created with Syntext Serna Free. --><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY WSRP_VERSION ''> <!ENTITY % BOOK_ENTITIES SYSTEM "Administration_and_Configuration_Guide.ent"> %BOOK_ENTITIES; ]> @@ -38,5 +39,2317 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Internationalization_Configuration.xml" encoding="UTF-8"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Localization_Configuration.xml" encoding="UTF-8"/> </part> + <part> + <title>Web Services for Remote Portlets</title> + <chapter id="wsrp-Introduction"> + <title>Introduction</title> + <remark>https://docs.jboss.org/author/display/GTNPORTAL35/Web+Services+... + <para>The Web Services for Remote Portlets specification defines a web service interface for accessing and + interacting with interactive presentation-oriented web services. It has been produced through the efforts of + the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is based on the requirements + gathered and on the concrete proposals made to the committee. + </para> + <para>Scenarios that motivate WSRP functionality include: + </para> + <itemizedlist> + <listitem> + <para>Content hosts, such as portal servers, providing Portlets as presentation-oriented web services + that can be used by aggregation engines. + </para> + </listitem> + <listitem> + <para>Aggregating frameworks, including portal servers, consuming presentation-oriented web services + offered by content providers and integrating them into the framework. + </para> + </listitem> + </itemizedlist> + <para>More information on WSRP can be found on the + <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... website for WSRP</ulink>. + Further suggested reading is the + <ulink url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr... + for a good, albeit technical, overview of WSRP. + </para> + </chapter> + <chapter id="wsrp_support"> + <title>Level of support in JBoss Portal Platform</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Level+of+support</re... + <para>The WSRP Technical Committee defined + <ulink url="http://www.oasis-open.org/committees/download.php/3073">... Use Profiles</ulink> + to help with WSRP interoperability. This section will refer to terms defined in that document. + </para> + <para>JBoss Portal Platform provides a Simple level of support for the WSRP Producer except that out-of-band registration + is not currently handled. In-band registration and persistent local state (which are + defined at the Complex level) are supported. + </para> + <para>On the Consumer side, JBoss Portal Platform provides a Medium level of support for WSRP, except that the consumer only handles + HTML markup (because JBoss Portal Platform itself does not handle other markup types). The platform does support explicit portlet + cloning and it fully supports the PortletManagement interface. + </para> + <para>As far as caching goes, the component has Level 1 Producer and Consumer. Cookie handling is supported properly on the + Consumer and the Producer requires initialization of cookies (it has been found that it improves interoperability + with some consumers). The component does not support custom window states or modes, as JBoss Portal Platform does not. The component does, + however, support CSS on both the Producer (though it is more a function of the portlets than inherent Producer + capability) and Consumer. + </para> + <para>While a complete implementation of WSRP 1.0 is provided, the community developers do need to go through the + <ulink url="http://www.oasis-open.org/committees/download.php/6018">... statements</ulink> + and perform more interoperability testing (an area that needs to be better supported by the WSRP Technical + Committee and Community at large). + </para> + <para>JBoss Portal Platform supports WSRP 2.0 with a complete implementation of the non-optional features. The only + features not implemented are support for lifetimes and leasing + support. + </para> + <note> + <title>Note</title> + <para>As of version &VZ; of JBoss Portal Platform, WSRP is only activated and supported +using JBoss Portal Platform deployed on JBoss Enterprise Application Platform 6. + </para> + </note> + </chapter> + <chapter id="Deploying_JPP_WSRP_Services"> + <title>Deploying JBoss Portal Platform&apos;s WSRP services</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Deploying+GateIn%27s+WS... + <para> +JBoss Portal Platform provides complete support for WSRP 1.0 and 2.0 standard interfaces, and offers both consumer and + producer services. Starting with version 2.1.0-GA of the component, WSRP is packaged as a JBoss Portal Platform + extension, and is self-contained in a package named + <filename><replaceable>JPP_HOME</replaceable>/gatein/extensions/gatein-wsrp-integration.ear</filename> +. +</para> + <para>The only files of interest from a user perspective +are located in the + <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/wsrp</filename> +directory.</para> + <itemizedlist> + <listitem> + <para><filename>gatein-wsse-consumer.xml</filename>, which controls WS-Security support for the consumer.</para> + </listitem> + <listitem> + <para><filename>gatein-wsse-producer.xml</filename> which controls WS-Security support for + the producer.</para> + </listitem> + </itemizedlist> + <para>See + <xref linkend="wss_configuration"/> section for configuration required in these files. </para> + <para> + The extension itself is composed of the following components: + </para> + <itemizedlist> + <listitem> + <para> + <filename>META-INF</filename> + contains files necessary for EAR packaging. + </para> + </listitem> + <listitem> + <para> + The <filename>extension-component-&VZ;.jar</filename>, which contains the components needed to + integrate the WSRP component into JBoss Portal Platform. It also includes the default configuration files for + the WSRP producer and the default WSRP consumers. + </para> + </listitem> + <listitem> + <para> + The <filename>extension-config-&VZ;.jar</filename>, which contains the configuration file + needed by the GateIn extension mechanism to properly register this EAR as an extension. + </para> + </listitem> + <listitem> + <para> + The <filename>extension-war-&VZ;.war</filename>, which contains the configuration files + needed by the portal extension mechanism to properly setup the WSRP service. It includes + <filename>wsrp-configuration.xml</filename> + which, in particular, configures several options for the + <code>WSRPServiceIntegration</code> + component at the heart of the WSRP integration in JBoss Portal Platform. + </para> + </listitem> + <listitem> + <para> + The <filename>lib</filename> directory, which contains the different libraries needed by the WSRP service. + </para> + </listitem> + <listitem> + <para> + The <filename>wsrp-admin-gui-&WSRP_VERSION;.war</filename>, which contains the WSRP Configuration portlet + with which you can configure consumers to access remote servers and how the WSRP producer is + configured. + </para> + </listitem> + <listitem> + <para> + The <filename>wsrp-producer-jb5wsss-&WSRP_VERSION;.war</filename>, which contains the producer-side + support for WS-Security. + </para> + </listitem> + </itemizedlist> + <para> + If you are not going to use WSRP in JBoss Portal Platform, it will not adversely affect your installation to leave it + as is. Otherwise, you can just remove the + <filename>gatein-wsrp-integration.ear</filename> + file from your AS deploy directory. + </para> + <section id="wsrp-ports"> + <title>Considerations to use WSRP when running JBoss Portal Platform on a non-default port or hostname</title> + <para> + The web service stack that JBoss Portal Platform uses is based on JBoss WS. It updates the port and host name used in WSDL. For more information, refer to the <citetitle>Web Services</citetitle> chapter in the JBoss Enterprise Application Platform 6 <citetitle>Administration and Configuration User Guide</citetitle>. + </para> + <para>If you have modified the host name and port on which your server runs, you will + need to + update the configuration for the consumer used to consume JBoss Portal Platform&apos;s &apos;self&apos; producer. </para> + </section> + </chapter> + <chapter id="Securing_WSRP"> + <title>Securing WSRP</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>There are two main ways to secure the communication between a producer and consumer:</para> + <orderedlist> + <listitem> + <para> + <emphasis role="underline">Securing the Transport Layer</emphasis> + + This requires using SSL and a HTTPS endpoint. By using this, the communication between the consumer and producer will be encrypted. + </para> + </listitem> + <listitem> + <para> + <emphasis role="underline">Securing the Contents of the SOAP message</emphasis> + + This option requires using ws-security to handle parts of the SOAP message. With this option you can specify things like encryption, signing, timestamps, etc as well as passing across user credentials to perform a login on the producer side. WS-Security is more powerful and has more options, but is requires more complex configurations. + </para> + </listitem> + </orderedlist> + <para>Depending on requirements, an HTTPs endpoint and/or ws-security can be used.</para> + <section id="WSRP_over_SSL_HTTPS_Endpoints"> + <title>WSRP over SSL with HTTPS endpoints</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para> + It is possible to use WSRP over SSL for a secure exchange of data. Since JBoss Portal Platform does not come initially configured for HTTPS connectors, we will need to configure the producer&apos;s server for this first. This is a global configuration change, and will affect more than just the portal and WSRP. Refer to the +JBoss Enterprise Application Platform 6 <citetitle>Administration and Configuration Guide</citetitle> for instructions about how to configure HTTPS connectors for the server. + </para> + <para> + Once the producer is configured for HTTPS connections, on the consumer you will just need to modify the URL for the WSRP endpoint to point to the new HTTPS based URL. This will require either manually updating the value in the WSRP administration application, or by specifying it using the + <emphasis role="italics">wsrp-consumers-config.xml</emphasis> + configuration file before the server is first started. + </para> + <section id="sid-54264620_SecuringWSRP-SampleConfigurationForEnablingSSLWithWSRP"> + <title>Sample Configuration For Enabling SSL With WSRP</title> +<!--Docs Note - jmorgan - merged these three sections together using procedure tags. +--> <remark>Sources: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <warning> + <para> + The following procedures are provided as an example of configuring HTTPS/SSL with WSRP. </para> + <para>It is not meant to show best practices for configuring HTTPS with the platform, and does things which should not be used in a production server (such as self-signed certificates). Refer to the JBoss Enterprise Application Platform 6 product documentation for detailed, best practice configuration guidelines. + </para> + </warning> + <procedure> + <title>Configure the Producer to Use HTTPS</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>Configure the producer&apos;s server to use HTTPS. This is handled in the same manner that you would configure any JBoss Enterprise Application server for HTTPS.</para> + <step> + <para>Generate the keystore for the producer by executing the following command.</para> + <programlisting>keytool -genkey -alias tomcat -keyalg RSA -keystore producerhttps.keystore -dname &quot;cn=localhost&quot; -keypass changeme -storepass changeme</programlisting> + </step> + <step> + <para> + Configure the server to add an HTTPS connection. This requires modifying the + <emphasis role="italics">standalone/configuration/standalone.xml</emphasis> + file with the following content in bold: + </para> + <programlisting> + &lt;subsystem xmlns=&quot;urn:jboss:domain:web:1.1&quot; default-virtual-server=&quot;default-host&quot; native=&quot;false&quot;&gt; + + &lt;connector name=&quot;http&quot; protocol=&quot;HTTP/1.1&quot; scheme=&quot;http&quot; socket-binding=&quot;http&quot;/&gt; + + <emphasis role="strong">&lt;connector name=&quot;https&quot; protocol=&quot;HTTP/1.1&quot; scheme=&quot;https&quot; socket-binding=&quot;https&quot; secure=&quot;true&quot;&gt;</emphasis> + + <emphasis role="strong">&lt;ssl certificate-key-file=&quot;/path/to/producerhttps.keystore&quot; password=&quot;changeme&quot;/&gt;</emphasis> + + <emphasis role="strong">&lt;/connector&gt;</emphasis> + + &lt;virtual-server name=&quot;default-host&quot; enable-welcome-root=&quot;true&quot;&gt; + + &lt;alias name=&quot;localhost&quot;/&gt; + + &lt;alias name=&quot;example.com&quot;/&gt; + + &lt;/virtual-server&gt; + + ...</programlisting> + </step> + <step> + <para> + Start the server and verify that + <ulink url="https://localhost:8443/portal"/> + is accessible. Note that since you are using a self-signed certificate that your browser will give a warning that the certificate cannot be trusted. + </para> + <note> + <para>In this example case we are accessing the portal using &apos;localhost&apos; hence why we are using &quot;cn=localhost&quot; in the keytool command. If you are using this across another domain, you will need to make the necessary changes.</para> + </note> + </step> + </procedure> + <procedure> + <title>Configure the Consumer to Access the WSRP Endpoint over HTTPS</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <step> + <para>Export the producer&apos;s public key from the producer&apos;s keystore</para> + <programlisting>keytool -export -alias tomcat -file producerkey.rsa -keystore producerhttps.keystore -storepass changeme</programlisting> + </step> + <step> + <para>Import the producer&apos;s public key into a new keystore for the consumer</para> + <programlisting>keytool -import -alias tomcat -file producerkey.rsa -keystore consumerhttps.keystore -storepass changeme -noprompt</programlisting> + </step> + <step> + <para> + Configure the + <emphasis role="italics">bin/standalone.conf</emphasis> + file to add the following line at the end of the file: + </para> + <programlisting>JAVA_OPTS=&quot;$JAVA_OPTS -Djavax.net.ssl.trustStore=/path/to/consumerhttps.keystore -Djavax.net.ssl.trustStorePassword=changeme&quot;</programlisting> + </step> + <step> + <para> + Start the consumer and change the selfv2 producer url to + <ulink url="https://localhost:8443/wsrp-producer/v2/MarkupService?wsdl"/> + and verify that the consumer can access the producer. + </para> + </step> + </procedure> + <note> + <para> + It is possible to modify the + <emphasis role="italics">wsrp-consumers-config.xml</emphasis> + configuration file to change the URL instead of modifying it in the administration GUI. + </para> + </note> + <para> + It is possible to use WSRP over SSL for secure exchange of data. Configure your server appropriately as described in the <citetitle>HTTPS Configuration</citetitle> section of the <citetitle>Installation Guide</citetitle>. + </para> + </section> + </section> + <section id="WSRP_and_WS-Security"> + <title>WSRP and WS-Security</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>Portlets may present different data or options depending on the currently authenticated user. For remote + portlets, this means having to propagate the user credentials from the consumer back to the producer in + a safe and secure manner. The WSRP specification does not directly specify how this should be + accomplished, but delegates this work to the existing WS-Security standards. The WS-Security standards can also be used to secure the soap message, such as encryption and signing the message. + </para> + <warning> + <title>Encryption is strongly recommended</title> + <para>Encrypt the credentials being sent between the consumer and producer, otherwise they + will be sent in plain text and could be easily intercepted. Configure WS-Security to + encrypt and sign the SOAP messages being sent, or secure the transport layer by using an HTTPS endpoint. + Failure to encrypt the soap message or transport layer will result in the username and password being + sent in plain text. + </para> + </warning> + <note> + <title>Web Container Compatibility</title> + <para>WSRP and WS-Security is only supported on JBoss Portal Platform when running on JBoss Enterprise Application Platform 6. + </para> + </note> + </section> + <section id="wsrp-Credentials"> + <title>Credentials</title> + <para>When the consumer sends the user credentials to the producer, it is sending the credentials for the + currently authenticated user in the consumer. This makes signing in to remote portlets transparent + to end users, but also requires that the producer and consumer use the same credentials. This means + that the username and password must be the same and valid on both servers. + </para> + <para>The recommended approach for this situation would be to use a common LDAP configuration. See chapter LDAP_Integration in the Administration and Configuration guide to correctly configure LDAP on JBoss Portal Platform. </para> + <section id="wss_configuration"> + <title><remark>BZ#839355 </remark>WS-Security Configuration</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <section id="sid-54264620_SecuringWSRP-Introduction"> + <title>Introduction</title> + <para>JBoss Enterprise Application Platform 6 uses a different web service implementation than the previous versions: it is now uses the JBossWS CXF Stack instead of the JBossWS Native Stack. Due to these changes, the way we configure WS-Security for WSRP with JBoss Portal Platform on JBoss Enterprise Application Platform 6 has changed.</para> + <note> + <para>We only support one ws-security configuration option for the producer. All consumers accessing the producer will have to conform to this security constraint. This means if the producer requires encryption, all consumers will be required to encrypt their messages when accessing the producer.</para> + <para>We only support one ws-security configuration option to be used by all the consumers. A consumer has the option to enable or disable ws-security, which allows for one or more consumers to use ws-security while the others do not.</para> + </note> + </section> + <section id="sid-54264620_SecuringWSRP-Overview"> + <title>Overview</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>CXF uses interceptors to extend and configure its behavior. There are two main types of interceptors: <firstterm>inInterceptors</firstterm> and <firstterm>outInterceptors</firstterm>. InInterceptors are invoked for communication coming into the client or server, while outInterceptors are invoked when the client or server sends a message.</para> + <para>So for the WSRP case, the communication from the consumer to the producer is governed by the consumer&apos;s OutInterceptor and the producer&apos;s InInterceptors. The communication from the producer to the consumer is governed by the producer&apos;s OutInterceptor and the consumer&apos;s InInterceptor. This may mean having to configure 4 Interceptors.</para> + <para>When dealing with user propagation, only the consumer sends the user credentials to the producer. So Username Tokens only need to be configured for the consumer&apos;s OutInterceptor and the producer&apos;s InInterceptor.</para> + <para>When dealing with things like encryption, you will most likely want to encrypt the message from the consumer to the producer and also the message from the producer to the consumer. This means that encryption properties must be configured for all 4 interceptors.</para> + <para> + Please see the CXF Documentation for more details on interceptors and their types: + <ulink url="http://cxf.apache.org/docs/interceptors.html"/> + </para> + <para> + To support ws-security, JBoss Portal Platform 6 uses CXF&apos;s WSS4J Interceptors which handle all ws-security related tasks. Please see the CXF Documentation for more details: + <ulink url="http://cxf.apache.org/docs/ws-security.html"/> + </para> + </section> + </section> + <section id="WSS4J_Interceptors_and_WSRP"> + <title>WSS4J Interceptors and WSRP</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>The WSS4J Interceptors are configured using using simple property files. + +WSRP looks for specific property files to know whether or not in/out interceptors must be added and configured for either consumers or producer. </para> + <para>Theses files are located in the standalone/configuration/jpp/wsrp/cxf/ws-security directory of your the JBoss Enterprise Application Server 6 home directory. </para> + <para>Consumer-specific files are in the consumer subdirectory while producer-specific files should be located in the producer subdirectory. To add and configure a WSS4J interceptor, you just need to add the proper configuration file in the proper directory. If no configuration file is found for a specific interceptor type, then no such interceptor will be added. </para> + <para>&quot;In&quot; interceptors are configured using WSS4JInInterceptor.properties files while &quot;out&quot; interceptors are configured using WSS4JOutInterceptor.properties files. +</para> + <table frame="all"> + <title>Files needed to configure interceptor for WSRP</title> + <tgroup cols="3" align="justify"> + <colspec colnum="1" colname="c1" colwidth="100"/> + <colspec colnum="2" colname="c2" colwidth="150"/> + <colspec colnum="3" colname="c3" colwidth="400"/> + <thead> + <row> + <entry>Side</entry> + <entry>Interceptor Type</entry> + <entry>Configuration File</entry> + </row> + </thead> + <tbody> + <row> + <entry>Consumer</entry> + <entry>IN</entry> + <entry> + <filename>standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JInInterceptor.properties</filename> + </entry> + </row> + <row> + <entry/> + <entry>OUT</entry> + <entry> + <filename>standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JOutInterceptor.properties</filename> + </entry> + </row> + <row> + <entry>Producer</entry> + <entry>IN</entry> + <entry> + <filename>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/WSS4JInInterceptor.properties</filename> + </entry> + </row> + <row> + <entry/> + <entry>OUT</entry> + <entry> + <filename>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/WSS4JOutInterceptor.properties</filename> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para>Please refer to the CXF or WSS4J documentation for instructions and options available for each type of interceptors.</para> + <section> + <title>User Propagation</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>User propagation can be configured to be used over WSRP with ws-security. What this means is that a user logged into a consumer can have their credentials propagated over to the producer. This allows the producer to authenticate the user and any portlet on the producer (a remote portlet from the consumer&apos;s perspective) will view the user as being properly authenticated. This allows for remote portlets to access things like user information.</para> + <para><note> + <para>This only works if the user&apos;s credentials on the producer and consumer are the same. This may require using a common authentication mechanism, such as LDAP.</para> + <para>This requires some special options when configuring the producer and server.</para> + </note></para> + </section> + </section> + <section> + <title><remark>BZ#839355</remark>WS-Security Consumer Configuration</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para> + In order to configure ws-security on the consumer side, you will have to configure the WSS4J Interceptors as seen above. This will require having to configure the WSS4JInInterceptor and/or WSS4JOutInterceptor. + + You will also need to check the &apos;Enable WS-Security&apos; checkbox on the WSRP Admin Portlet for the consumer configuration to take effect. + </para> + <figure> + <title id="fig-WSRP_Consumers_Configuration">WSRP Consumers Configuration</title> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_wss_selected.png" format="PNG"/> + </imageobject> + </mediaobject> + </figure> + <section> + <title>Special JBoss Portal Platform Configuration Options for User Propagation</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>In order to handle user propagation in JBoss Portal Platform across ws-security, a couple of special configuration options have been created which should be applied to the consumer&apos;s WSS4JOutInterceptor.</para> + <section> + <title>Custom &apos;user&apos; option</title> + <para><informalexample> + <programlisting>user=gtn.current.user</programlisting> + <para>This option sets the &apos;user&apos; property to the currently authenticated user on the consumer.</para> + </informalexample></para> + </section> + <section> + <title>Custom &apos;action&apos; option</title> + <para><informalexample> + <programlisting>action=gtn.UsernameToken.ifCurrentUserAuthenticated</programlisting> + <para>If a user is currently authenticated, it will replace the &apos;gtn.UsernameToken.ifCurrentUserAuthenticated&apos; with &apos;UsernameToken&apos;. If the current user is an unauthenticated user, &apos;gtn.UsernameToken.ifCurrentUserAuthenticated&apos; will be removed from the action list. If no other actions are specified, then the WSS4J interceptor will not be added to the consumer. This allows you to only use ws-security when dealing with authenticated users, and not for anonymous users.</para> + </informalexample><note> + <para>This requires that the user option is set to &apos;gtn.current.user&apos;</para> + </note></para> + </section> + <section> + <title>Custom PasswordCallbackClass</title> + <para>To set the password for the username token, we need to specify the password in a callback class. See the cxf ws-security documentation for more details <ulink url="http://cxf.apache.org/docs/ws-security.html"/></para... + <para>A special callback class has already been created which handles this for you: CurrentUserPasswordCallback. This class will retrieve the currently authenticated user&apos;s password and set this as the password in the callback object.</para> + <para><informalexample> + <programlisting>passwordCallbackClass=org.gatein.wsrp.wss.cxf.consumer.CurrentUserPasswordCallback</programlisting> + </informalexample></para> + </section> + </section> + </section> + <section id="sid-54264620_SecuringWSRP-ProducerConfiguration"> + <title>Producer Configuration</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>The configuration of the producer is similar to that of the consumer. It also requires having to configure the WSS4JInInterceptor and/or WSS4JOutInterceptor.</para> + <section> + <title>Special Configuration Options for User Propagation</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para> + To properly propagate user information on the producer-side, you will need to use GTNSubjectCreatingInterceptor instead of a regular WSS4JInInterceptor. This JBoss Portal Platform specific &quot;in&quot; interceptor is an extension of the traditional WSS4JInInterceptor and therefore can be configured similarly and accept the same configuration properties. To specify that you want to use the GTNSubjectCreatingInterceptor, please create a property file at + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/GTNSubjectCreatingInterceptor.properties</code> + instead of the regular WSS4JInInterceptor.properties file. + </para> + <para>This Interceptor will handle the ws-security headers and retrieve the users credentials. It will then use these credentials to perform a login on the producer site, thus authenticating the user on the producer and makes the user available to remote portlets.</para> + <note> + <para>This class also extends org.jboss.wsf.stack.cxf.security.authentication.SubjectCreatingInterceptor and can accept the same properties this class normally accepts. See the JBossWS documentation for options and more information.</para> + </note> + </section> + <section> + <title>Custom &apos;action&apos; option</title> + <informalexample> + <programlisting>action=gtn.UsernameToken.ifAvailable</programlisting> + </informalexample> + <para>When this option is activated, the interceptor will set the action to &apos;UsernameToken&apos; when the received SOAP message contains ws-security headers. If no ws-security header is included in the message, then no action is taken and the interceptor is not run. This is useful for dealing with authenticated and unauthentcated users trying to access the producer.</para> + </section> + </section> + <section id="sid-54264620_SecuringWSRP-SampleConfigurationusingtheUsernameTokenandUserPropagation"> + <title>Sample Configuration using the UsernameToken and User Propagation</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <warning> + <para>This example configuration does not encrypt the message. This means the username and password will be sent between the producer and consumer in plain text. This is a security concern and is only being shown as a simple example. It is up to administrators to properly configure the WSS4J Interceptors to encrypt messages or to only use https communication between the producer and consumer.</para> + </warning> + <section> + <title>Producer Setup</title> + <orderedlist> + <listitem> + <para> + create the following file: + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/GTNSubjectCreatingInterceptor.properties</code> + </para> + </listitem> + <listitem> + <para> + set the content of + <code>GTNSubjectCreatingInterceptor.properties</code> + created in step 1 to: + </para> + <informalexample> + <programlisting>action=gtn.UsernameToken.ifAvailable</programlisting> + </informalexample> + </listitem> + <listitem> + <para>start the producer server</para> + </listitem> + </orderedlist> + </section> + <section> + <title>Consumer Setup</title> + <orderedlist> + <listitem> + <para> + create the following file: + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JOutInterceptor.properties</code> + </para> + </listitem> + <listitem> + <para> + set the content of the + <code>WSS4JOutInterceptor.properties</code> + created in step 1 to: + </para> + <informalexample> + <programlisting>passwordType=PasswordText +user=gtn.current.user +action=gtn.UsernameToken.ifCurrentUserAuthenticated +passwordCallbackClass=org.gatein.wsrp.wss.cxf.consumer.CurrentUserPasswordCallback</programlisting> + </informalexample> + </listitem> + <listitem> + <para>start the consumer server</para> + </listitem> + <listitem> + <para>in the WSRP admin portlet, click the &apos;enable ws-security&apos; checkbox</para> + </listitem> + <listitem> + <para>access a remote portlet (for example, the user identity portlet included as an example portlet in JBoss Portal Platform) and verify that the authenticated user is the same as the one on the consumer</para> + </listitem> + </orderedlist> + </section> + </section> + <section id="sid-54264620_SecuringWSRP-SampleConfigurationSecuringtheEndpointsusingEncryptionandSigning"> + <title>Sample Configuration Securing the Endpoints using Encryption and Signing</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>The following steps outline how to configure the producer and consumer to encrypt and sign SOAP messages passed between the producer and consumer. This example only deals with SOAP messages being sent between the producer and consumer, and not with user propagation.</para> + <note> + <para> + Some of the configuration options specified here are based on the content at + <ulink url="http://cxf.apache.org/docs/ws-security.html"/> + and + <ulink url="http://www.jroller.com/gmazza/entry/cxf_x509_profile"/> + More information may be available at these sites. + </para> + </note> + <section> + <title>Password Callback Class</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>WSS4J uses a Java class to specify the password when performing any security related actions. For the purpose of these encryption and signing examples, we will use the same password for the producer&apos;s and consumer&apos;s keystore (wsrpAliasPassword). This simplifies things a bit as it means we can use just one password callback class for both the producer and consumer.</para> + <para> + Example + <code>test.TestCallbackHandler</code> + class: + </para> + <informalexample> + <programlisting>package test; +&#160; +import java.io.IOException; +import javax.security.auth.callback.Callback; +import javax.security.auth.callback.CallbackHandler; +import javax.security.auth.callback.UnsupportedCallbackException; +&#160; +import org.apache.ws.security.WSPasswordCallback; +import org.gatein.wsrp.wss.cxf.consumer.CurrentUserPasswordCallback; +&#160; +public class TestCallbackHandler implements CallbackHandler +{ +&#160; +&#160;&#160;&#160; @Override +&#160;&#160;&#160; public void handle(Callback[] callbacks) throws IOException, +&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; UnsupportedCallbackException +&#160;&#160;&#160; { +&#160; +&#160;&#160;&#160;&#160;&#160;&#160;&#160; //First check if we have any user name token call backs to add. +&#160;&#160;&#160;&#160;&#160;&#160;&#160; //NOTE: only needed if using username tokens, and you want the currently authenticated users password added +&#160;&#160;&#160;&#160;&#160;&#160;&#160; CurrentUserPasswordCallback currentUserPasswordCallback = new CurrentUserPasswordCallback(); +&#160;&#160;&#160;&#160;&#160;&#160;&#160; currentUserPasswordCallback.handle(callbacks); +&#160; +&#160;&#160;&#160;&#160;&#160;&#160;&#160; for (Callback callback: callbacks) +&#160;&#160;&#160;&#160;&#160;&#160;&#160; { +&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; if (callback instanceof WSPasswordCallback) +&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; { +&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; WSPasswordCallback wsPWCallback = (WSPasswordCallback)callback; +&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; // since the CurrentUserPasswordCallback already handles the USERNAME_TOKEN case, we don&apos;t want to set it in this case +&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; if (wsPWCallback.getUsage() != WSPasswordCallback.USERNAME_TOKEN) +&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; { +&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; wsPWCallback.setPassword(&quot;wsrpAliasPassword&quot;); +&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; } +&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; } +&#160;&#160;&#160;&#160;&#160;&#160;&#160; } +&#160;&#160;&#160; } +}</programlisting> + </informalexample> + <note> + <para> + CallbackHandler implementations are provided to JBoss Portal Platform using the standard Java + <ulink url="http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoade... + infrastructure. As such, CallbackHandler implementations need to be bundled in a jar containing a file + <code>META-INF/services/javax.security.auth.callback.CallbackHandler</code> + specifying the fully qualified name of the CallbackHandler implementation class. This jar then needs to be put in the + <code>gatein/extensions</code> + directory of your JBoss Portal Platform installation. + </para> + </note> + <para> + You can see a working example of a CallbackHandler implentation at + <ulink url="https://github.com/gatein/gatein-wsrp/tree/master/examples/wss-... + </para> + </section> + <section> + <title>Configuring the Keystores</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <note> + <para>In this example we are making it a bit easier by specifying the same keystore password for both the producer and consumer, as they can use the same password callback class.</para> + </note> + <orderedlist> + <listitem> + <para>Generate the producer&apos;s private encryption keys</para> + <informalexample> + <programlisting>keytool -genkey -alias producerAlias -keypass wsrpAliasPassword -keystore producer.jks -storepass keyStorePassword -dname &quot;cn=producerAlias&quot; -keyalg RSA</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Export the producer&apos;s public key</para> + <informalexample> + <programlisting>keytool -export -alias producerAlias -file producerkey.rsa -keystore producer.jks -storepass keyStorePassword</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Generate the consumer&apos;s private encryption keys</para> + <informalexample> + <programlisting>keytool -genkey -alias consumerAlias -keypass wsrpAliasPassword -keystore consumer.jks -storepass keyStorePassword -dname &quot;cn=consumerAlias&quot; -keyalg RSA</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Export the consumer&apos;s public key</para> + <informalexample> + <programlisting>keytool -export -alias consumerAlias -file consumerkey.rsa -keystore consumer.jks -storepass keyStorePassword</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Import the consumer&apos;s public key into the producer&apos;s keystore</para> + <informalexample> + <programlisting>keytool -import -alias consumerAlias&#160; -file consumerkey.rsa -keystore producer.jks -storepass keyStorePassword -noprompt</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Import the producer&apos;s public key into the consumer&apos;s keystore</para> + <informalexample> + <programlisting>keytool -import -alias producerAlias&#160; -file producerkey.rsa -keystore consumer.jks -storepass keyStorePassword -noprompt</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + Copy the + <code>producer.jks</code> + file to the + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer</code> + directory on the producer + </para> + </listitem> + <listitem> + <para> + Copy the + <code>consumer.jks</code> + file to the + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/consumer</code> + directory on the consumer + </para> + </listitem> + </orderedlist> + </section> + <section> + <title>Configuring the Producer</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <orderedlist> + <listitem> + <para> + Create + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/WSS4JInInterceptor.properties</code> + with the following content. This will configure the incoming message between the producer and the consumer + </para> + <informalexample> + <programlisting>action=Signature Encrypt Timestamp +signaturePropFile=producer-security.properties +decryptionPropFile=producer-security.properties +passwordCallbackClass=test.TestCallbackHandler</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + Create + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/WSS4JOutInterceptor.properties</code> + with the following content. This will configure the outgoing message between the producer and the consumer + </para> + <informalexample> + <programlisting>action=Signature Encrypt Timestamp +signaturePropFile=producer-security.properties +encryptionPropFile=producer-security.properties +passwordCallbackClass=test.TestCallbackHandler +user=producerAlias +encryptionUser=consumerAlias +signatureUser=producerAlias</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + Create + <code>standalone/configuration/gatein/wsrp/cxf/ws-security/producer/producer-security.properties</code> + with the following content: + </para> + <informalexample> + <programlisting>org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=keyStorePassword +org.apache.ws.security.crypto.merlin.file=producer.jks</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + The + <code>passwordCallbackClass</code> + property in these configuration files needs to match the fully qualified name of your CallbackHandler implementation class. In our case, it is + <code>test.TestCallbackHandler</code> + . + </para> + </listitem> + </orderedlist> + </section> + <section> + <title>Configuring the Consumer</title> + <remark>Source: </remark> + <orderedlist> + <listitem> + <para> + Create standalone/ + <code>configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JOutInterceptor.properties</code> + with the following content. This will configure the outgoing message between the consumer and the producer + </para> + <informalexample> + <programlisting>action=Signature Encrypt Timestamp +signaturePropFile=consumer-security.properties +encryptionPropFile=consumer-security.properties +passwordCallbackClass=test.TestCallbackHandler +user=consumerAlias +encryptionUser=producerAlias +signatureUser=consumerAlias</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + Create standalone/ + <code>configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JInInterceptor.properties</code> + with the following content. This will configure the incoming message between the consumer and the producer + </para> + <informalexample> + <programlisting>action=Signature Encrypt Timestamp +signaturePropFile=consumer-security.properties +decryptionPropFile=consumer-security.properties +passwordCallbackClass=test.TestCallbackHandler</programlisting> + </informalexample> + </listitem> + <listitem> + <para>Create standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/consumer-security.properties with the following content:</para> + <informalexample> + <programlisting>org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=keyStorePassword +org.apache.ws.security.crypto.merlin.file=consumer.jks</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + The + <code>passwordCallbackClass</code> + property in these configuration files needs to match the fully qualified name of your CallbackHandler implementation class. In our case, it is + <code>test.TestCallbackHandler</code> + . + </para> + </listitem> + </orderedlist> + </section> + </section> + <section> + <title>Sample Configuration using UsernameToken, Encryption and Signing with User Propagation</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para>The following steps outline how to configure the producer and consumer to encrypt and sign the soap message as well as use user propagation between the producer and consumer.</para> + <section> + <title>Configure the Producer</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para> + Follow the steps outlined in the + <link linkend="sid-54264620_SecuringWSRP-SampleConfigurationSecuringtheEndpointsusingEncryptionandSigning">Sample Configuration Securing the Endpoints using Encryption and Signing</link> + section but make the following changes: + </para> + <orderedlist> + <listitem> + <para> + rename the + <code>WSS4JInInterceptor.properties</code> + file to + <code>GTNSubjectCreatingInterceptor.properties</code> + </para> + </listitem> + <listitem> + <para> + set the action property in + <code>GTNSubjectCreatingInterceptor.properties</code> + as: + </para> + <informalexample> + <programlisting>action= gtn.UsernameToken.ifAvailable Signature Encrypt Timestamp</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + set the passwordType in + <code>GTNSubjectCreatingInterceptor.properties</code> + as: + </para> + <informalexample> + <programlisting>passwordType=PasswordText</programlisting> + </informalexample> + </listitem> + </orderedlist> + </section> + <section> + <title>Configure the Consumer</title> + <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Securing+WSRP#SecuringW... + <para> + Follow the steps outlined in the + <link linkend="sid-54264620_SecuringWSRP-SampleConfigurationSecuringtheEndpointsusingEncryptionandSigning">Sample Configuration Securing the Endpoints using Encryption and Signing</link> + section but make the following changes: + </para> + <orderedlist> + <listitem> + <para> + set the action property in + <code>WSS4JOutInterceptor.properties</code> + as: + </para> + <informalexample> + <programlisting>action=gtn.UsernameToken.ifCurrentUserAuthenticated Signature Encrypt Timestamp</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + set the user in the + <code>WSS4JOutInterceptor.properties</code> + as: + </para> + <informalexample> + <programlisting>user=gtn.current.user</programlisting> + </informalexample> + </listitem> + <listitem> + <para> + set the passwordType in the + <code>WSS4JOutInterceptor.properties</code> + as: + </para> + <informalexample> + <programlisting>passwordType=PasswordText</programlisting> + </informalexample> + </listitem> + </orderedlist> + </section> + </section> + </section> + </chapter> + <chapter> + <title>Making a portlet remotable</title> + <important> + <para> + Only JSR-286 (Portlet 2.0) portlets can be made remotable as the mechanism to expose a portlet to WSRP + relies on a JSR-286-only functionality. + </para> + </important> + <para>JBoss Portal Platform does +not, by default, expose local portlets for consumption + by remote WSRP consumers. In order to make a portlet remotely available, it must be made <firstterm>remotable</firstterm> by marking + it as such in the associated + <filename>portlet.xml</filename>. This is accomplished by using a specific + <code>org.gatein.pc.remotable container-runtime-option</code>. Setting its value to + <code>true</code> + makes the portlet available for remote consumption, while setting its value to + <code>false</code> + will not publish it remotely. As specifying the remotable status for a portlet is optional, you do not need to + do anything if you do not need your portlet to be available remotely. + </para> + <example> + <title>Single Portlet Remotable Example</title> + <para>The &quot;BasicPortlet&quot; portlet is specified as being remotable. + </para> + <para> + <programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> +<portlet-app> + <portlet> + <portlet-name>BasicPortlet</portlet-name> + + ... + + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>true</value> + </container-runtime-option> + </portlet> +</portlet-app>]]></programlisting> + </para> + </example> + <para> + It is also possible to specify that all the portlets declared within a given portlet application to be + remotable by default. This is done by specifying the + <code>container-runtime-option</code> + at the + <code>portlet-app</code> + element level. Individual portlets can override that value to not be remotely exposed. This is an + example: + </para> + <example> + <title>Multiple Portlets Remotable Example</title> + <para> + The example defines two portlets. The + <code>org.gatein.pc.remotable container-runtime-option</code> + being set to + <code>true</code> + at the + <code>portlet-app</code> + level, all portlets defined in this particular portlet application are exposed remotely by JBoss Portal Platform&apos;s + WSRP + producer. +</para> + <programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> +<portlet-app> + + <portlet> + <portlet-name>RemotelyExposedPortlet</portlet-name> + ... + </portlet> + <portlet> + <portlet-name>NotRemotelyExposedPortlet</portlet-name> + ... + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>false</value> + </container-runtime-option> + </portlet> + + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>true</value> + </container-runtime-option> +</portlet-app>]]> + </programlisting> + <para>It is possible to override the default behavior by specifying a value for the + <code>org.gatein.pc.remotable container-runtime-option</code> + at the + <code>portlet</code> + level. </para> + <para>The + <varname>RemotelyExposedPortlet</varname> + inherits the remotable status defined at the + <code>portlet-app</code> + level since it does not specify a value for the <code>org.gatein.pc.remotable container-runtime-option</code>. + The <varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely + exposed. Note that in the absence of a top-level + <code>org.gatein.pc.remotable container-runtime-option</code> + value set to <code>true</code>, portlets are not remotely exposed. + </para> + </example> + </chapter> + <chapter> + <title>Consuming WSRP portlets from a remote Consumer</title> + <para>WSRP Producers vary a lot as far as how they are configured. Most of them require that you specify + the URL for the Producer&apos;s WSDL definition. Please refer to the remote producer&apos;s documentation for specific + instructions. For instructions on how to do so in JBoss Portal Platform, please refer to + Consumer Configuration. + </para> + <para> +JBoss Portal Platform&apos;s Producer is automatically set up when you deploy a portal instance with the WSRP service. + You can access the WSDL file at + <filename>http://{hostname}:{port}/wsrp-producer/v2/MarkupService?wsdl</filename>. If you wish to use only the + WSRP 1 compliant version of the producer, please use the WSDL file found at + <filename>http://{hostname}:{port}/wsrp-producer/v1/MarkupService?wsdl</filename>. + The default hostname is + <literal>localhost</literal> + and the default port is 8080. + </para> + </chapter> + <chapter> + <title>Consuming remote WSRP portlets in JBoss Portal Platform</title> + <section> + <title>Overview</title> + <para> + To be able to consume WSRP portlets exposed by a remote producer, JBoss Portal Platform&apos;s WSRP consumer needs to + know how to access that remote producer. You can configure access to a remote producer using the provided + configuration portlet. Alternatively, it is also possible to configure access to remote producers using an + XML descriptor, though it is recommended (and easier) to do so via the configuration portlet. + </para> + <para> + Once a remote producer has been configured, the portlets that it exposes are then available in the + Application Registry to be added to categories and then to pages. + </para> + </section> + <section> + <title>Configuring a remote producer using the configuration portlet</title> + <para> + This section will cover the steps of defining access to a remote producer using the configuration portlet so that its portlets can be + consumed within JBoss Portal Platform. We will configure access to NetUnity&apos;s public WSRP producer. + </para> + <note> + <para> + Some WSRP producers do not support chunked encoding that is activated by default by JBoss WS. If your + producer does not support chunked encoding, your consumer will not be able to properly connect to the + producer. This will manifest itself with the following error: + <code>Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] - Service Unavailable</code>. + Please see this <ulink url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis... page </ulink> + for more details. + </para> + </note> + <para> +JBoss Portal Platform provides a portlet to configure access (among other functions) to remote WSRP Producers + graphically. Starting with &VZ;, the WSRP configuration portlet is installed by default. You + can find it at + <ulink url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&amp;username=root&amp;password=gtn"> http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... </ulink> + </para> + <para> + You should see a screen similar to: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_init.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>This screen presents all the configured Consumers associated with their status and possible actions on + them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a + portlet provider. Note also that a Consumer can be marked as requiring refresh meaning that the + information held about it might not be up to date and refreshing it from the remote Producer might be a + good idea. This can happen for several reasons: the service description for that remote Producer has not + been fetched yet, the cached version has expired or modifications have been made to the configuration + that could potentially invalidate it, thus requiring re-validation of the information. + </para> + <note> + <title>Note</title> + <para> + The WSRP configuration was not installed by default in previous versions of JBoss Portal Platform. + We include here the legacy instructions on how to install this portlet in case you ever need to + re-install it. + </para> + <para> + Use the usual procedure to log in as a Portal administrator and go to the Application + Registry. With the default install, you can open the + <ulink url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&amp;username=root&amp;password=gtn">Group &gt; Administration &gt; Application Registry </ulink> +screen and add the WSRP Configuration portlet to the Administration category. If you use the Import Applications + functionality, the WSRP Configuration portlet will be automatically added to the Administration + category. + </para> + <para> + Now that the portlet is added to a category, it can be added to a page and used. It is recommended that you add + it to the same page as the Application Registry as operations relating to WSRP and adding portlets to + categories are somewhat related. Go ahead and add the WSRP Configuration portlet to the + page using the standard procedure. + </para> + </note> + <para> + Next, create a new Consumer called <literal>netunity</literal>. Type + &quot;<literal>netunity</literal>&quot; in + the &quot;Create a consumer named:&quot; field then click on &quot;Create consumer&quot;: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_create.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>You should now see a form allowing you to enter/modify the information about the Consumer. + Set the cache expiration value to 300 seconds, leave the default timeout value for web services (WS) + operations and enter the WSDL URL for the producer in the text field + and press the &quot;Refresh &amp; Save&quot; button:</para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_wsdl.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>This will retrieve the service description associated with the Producer which WSRP interface is described + by the WSDL file found at the URL you just entered. In this case, querying the service description will + reveal that the Producer requires registration, requested three registration properties and that + some of these properties are missing values:</para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_missing.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>This particular producer requests simple + <literal>Yes</literal> + or + <literal>No</literal> + values for the three registration properties. Entering <literal>No</literal>, + <literal>Yes</literal> + and + <literal>No</literal> + (in that order) for the values and then pressing the &quot;Refresh &amp; Save&quot; button should result in:</para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_end.png" format="PNG"/> + </imageobject> + </mediaobject> + <note> + <title>Note</title> + <para>At this point, there is no automated way to learn about which possible values (if any) are + expected by the remote Producer. Sometimes, the possible values will be indicated in the + registration + property description but this is not always the case... Please refer to the specific Producer&apos;s + documentation. + </para> + </note> + <para> + If you had been dealing with a producer which required registration but did not require any registration + properties, as is the case for the + <literal>selfv2</literal> + consumer (the consumer that accesses the portlets made remotely available by JBoss Portal Platform&apos;s producer via + WSRP 2), you would have seen something similar to the screenshot below, after pressing the &quot;Refresh &amp; Save&quot; button: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_refresh.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + </section> + <section> + <title>Configuring access to remote producers via XML</title> + <para>While it is recommended you use the WSRP Configuration portlet to configure Consumers, the component provides an + alternative way to configure consumers by adding an XML file called + <filename>wsrp-consumers-config.xml</filename> in the + <filename><replaceable>JPP_DIST</replaceable>/standalone/configuration/gatein/wsrp/</filename> directory. + </para> + <note> + <title>Note</title> + <para>An XML Schema defining which elements are available to configure Consumers via XML can be found + in + <filename><replaceable>JPP_DIST</replaceable>/modules/org/gatein/wsrp/main/wsrp-integration-api-&WSRP_VERSION;.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> + </para> + </note> + <important> + <para>Once the XML configuration file for consumers has been read upon + the WSRP service first start, the associated information is put under control of JCR (Java Content + Repository). Subsequent launches of the WSRP service will use the JCR-stored information and ignore + the content of the XML configuration file. + </para> +<!--<para>It is important to note how the XML consumers configuration file is processed. It is read the first + time the WSRP service starts and the associated information is then put under control of JCR (Java + Content Repository). Subsequent launches of the WSRP service will use the JCR-stored information for + all producers already known to JBoss Enterprise Portal Platform. More specifically, the + <filename>wsrp-consumers-config.xml</filename> + file is scanned for producer identifiers. + Any identifier that is already known will be bypassed and the JCR information associated with this + remote producer will be used. The information defined at the XML level is only processed for producer + definition for which no information is already present in JCR. Therefore, if you wish to delete a + producer configuration, you need to delete the associated information in the database (this can be + accomplished using the configuration portlet as we saw in + <xref linkend="consumer_gui"/>) + <emphasis>AND</emphasis> + remove the associated information in + <filename>wsrp-consumers-config.xml</filename> + (if such information exists) as the producer will be re-created the next time the WSRP is launched if + that information is not removed. + </para>--> </important> + <section> + <title>Required configuration information</title> + <para>This section covers what information needs to be provided to configure access to a remote producer. + </para> + <para>First, you need to provide an identifier for the producer you are configuring so that you can refer to it + afterwards. This is accomplished via the mandatory + <literal>id</literal> + attribute of the + <literal>&lt;wsrp-producer&gt;</literal> + element. + </para> + <para>JBoss Portal Platform also needs to learn about the remote producer&apos;s endpoints to be able to connect to the + remote web services and perform WSRP invocations. This is accomplished by specifying the URL for the + WSDL description for the remote WSRP service, using the + <literal>&lt;endpoint-wsdl-url&gt;</literal> + element. + </para> + <para>Both the + <literal>id</literal> + attribute and + <literal>&lt;endpoint-wsdl-url&gt;</literal> + elements are required for a functional remote producer configuration. + </para> + </section> + <section> + <title>Optional configuration</title> + <para>It is also possible to provide addtional configuration, which, in some cases, might be important to + establish a proper connection to the remote producer. + </para> + <para>One such optional configuration concerns caching. To prevent useless round-trips between the local + consumer and the remote producer, it is possible to cache some of the information sent by the producer + (such as the list of offered portlets) for a given duration. The rate at which the information is + refreshed is + defined by the + <literal>expiration-cache</literal> + attribute of the + <literal>&lt;wsrp-producer&gt;</literal> + element which specifies the refreshing period in seconds. For example, providing a value of 120 for + expiration-cache means that the producer information will not be refreshed for 2 minutes after it has + been somehow accessed. If no value is provided, JBoss Portal Platform will always access the remote producer + regardless of whether the remote information has changed or not. Since, in most instances, the + information provided by the producer does not change often, it is recommended that you use this caching + facility to minimize bandwidth usage. + </para> + <para>It is also possible to define a timeout after which WS operations are considered as failed. This is + helpful to avoid blocking the WSRP service, waiting on the service that does not answer. Use the + <literal>ws-timeout</literal> + attribute of the + <literal>&lt;wsrp-producer&gt;</literal> + element to specify how many milliseconds the WSRP service will wait for a response from the remote + producer before timing out and giving up. + </para> + <para>Additionally, some producers require consumers to register with them before authorizing them to access + their offered portlets. If you know that information beforehand, you can provide the required + registration information in the producer configuration so that the consumer can register with the remote + producer when required. + </para> + <note> + <title>Note</title> + <para>At this time, though, only simple String properties are supported and it is not possible to + configure complex registration data. This should, however, be sufficient for most cases. + </para> + </note> + <para>Registration configuration is done via the + <literal>&lt;registration-data&gt;</literal> + element. Since JBoss Portal Platform can generate the mandatory information for you, if the remote producer does + not require any registration properties, you only need to provide an empty + <literal>&lt;registration-data&gt;</literal> + element. Values for the registration properties + required by the remote producer can be provided via + <literal>&lt;property&gt;</literal> + elements. See the example below for more details. Additionally, you can override the default consumer + name automatically provided by JBoss Portal Platform via the + <literal>&lt;consumer-name&gt;</literal> + element. If you choose to provide a consumer name, please remember that this should uniquely identify + your consumer. + </para> + </section> + <section> + <title>Examples</title> + <remark>NEEDINFO - FILE PATHS - this file was not present at the location specified. Where is this file now?</remark> + <para> + Here is the configuration of the + <literal>selfv1</literal> + and + <literal>selfv2</literal> + consumers as found in + <filename><replaceable>JPP_HOME</replaceable>/gatein/extensions/gatein-wsrp-integration.ear/lib/extension-component-&WSRP_VERSION;.jar/conf/wsrp-consumers-config.xml</filename> + with a cache expiring every 500 seconds and with a 50 second timeout for web service operations. + <note> + <para> + This file contains the default configuration and you should not need to edit it. If you want to make + modifications to it, it is recommended that you follow the procedure detailed in +consumer_gui . + </para> + </note> + </para> + <example> + <title>Example</title> + <para> + <programlisting><![CDATA[ +<?xml version='1.0' encoding='UTF-8' ?> +<deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> + <deployment> + <wsrp-producer id="selfv1" expiration-cache="500" ws-timeout="50000"> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v1/MarkupService?wsdl</endpoint-wsdl-url> + <registration-data/> + </wsrp-producer> + </deployment> + <deployment> + <wsrp-producer id="selfv2" expiration-cache="500" ws-timeout="50000"> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v2/MarkupService?wsdl</endpoint-wsdl-url> + <registration-data/> + </wsrp-producer> + </deployment> +</deployments>]]> + </programlisting> + </para> + </example> + <example> + <title>Registration Data and Cache Expiry Example</title> + <para>This example shows a WSRP descriptor with registration data and cache expiring every minute:</para> + <para> + <programlisting><![CDATA[ +<?xml version='1.0' encoding='UTF-8' ?> +<deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> +<deployments> + <deployment> + <wsrp-producer id="AnotherProducer" expiration-cache="60"> + <endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoi... + <registration-data> + <property> + <name>property name</name> + <lang>en</lang> + <value>property value</value> + </property> + </registration-data> + </wsrp-producer> + </deployment> +</deployments>]]></programlisting> + </para> + </example> + </section> + </section> + <section> + <title>Adding remote portlets to categories</title> + <para> + If you go to the Application Registry and examine the available portlets by clicking on the + Portlet link, you will now be able to see remote portlets if you click on the REMOTE tab in the left + column: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/remote_portlets.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + <para> + These portlets are, of course, available to be used such as regular portlets: they can be used in + categories and added to pages. If you use the Import Applications functionality, they will also be + automatically imported in categories based on the keywords they define. + </para> + <para> + More specifically, if you want to add a WSRP portlet to a category, you can access these portlets by + selecting + <literal>wsrp</literal> + in the Application Type drop-down menu: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/remote_portlets_category.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + </section> + <section> + <title>Adding remote portlets to pages</title> + <para> + Since remote portlets can be manipulated just like regular portlets, you can add them to pages just like you + would do for a regular portlet. Please refer to the appropriate section of the documentation for how to do + so. + </para> + <para> + Of note, though, is that, starting with version 5.2 of JBoss Portal Platform, it is now possible to also add a + remote portlet to a + <filename>pages.xml</filename> + configuration file. + This is accomplished using the + <literal>&lt;wsrp&gt;</literal> + element instead of the + <literal>&lt;portlet&gt;</literal> + element in your + <filename>pages.xml</filename> + document. While + <literal>&lt;portlet&gt;</literal> + references a local portlet using the name of the application in which the portlet is contained and the + portlet name itself to identify which portlet to use, + <literal>&lt;wsrp&gt;</literal> + references a remote portlet using a combination of the consumer identifier for the producer publishing the + portlet and the portlet handle identifying the portlet within the context of the producer. + </para> + <para> + The format for such a reference to a remote portlet is a follows: first, the identifier of the + consumer that accesses the remote producer publishing the remote portlet, then a separator (currently a + period (<literal>.</literal>)) and finally the portlet handle for that + portlet, which is a string provided by the producer to identify the portlet. + </para> + <para> + Since there currently is no easy way to determine the correct portlet handle, it is recommended that you use the + graphical user interface to add remote portlets to pages instead of using + <filename>pages.xml</filename>. + </para> + <note> + <para> + For remote portlets published by JBoss Portal Platform&apos;s WSRP producer, the portlet handles are, at + the time of this writing, following the + <literal>/&lt;portlet application name&gt;.&lt;portlet name&gt;</literal> + format. + </para> + </note> + <section> + <title>Example</title> + <para> + In the following example, two portlets are defined for a page named + <literal>Test</literal> + in the + <filename>pages.xml</filename> + configuration. They are actually references to the same portlet, albeit one accessed locally and the + other + one accessing it via the + <literal>selfv2</literal> + consumer which consumes JBoss Portal Platform&apos;s WSRP producer. You can see that the first one is local (the + <code>&lt;portlet-application&gt;</code> + with the + &apos;<literal>Added locally</literal>&apos; + title) and follows the usual declaration. The second portlet (the one with the + &apos;<literal>Added from selfv2 consumer</literal>&apos; + title) comes from the + <literal>selfv2</literal> + consumer and uses the + <code>&lt;wsrp&gt;</code> + element instead of + <code>&lt;portlet&gt;</code> + element and follows the format for portlets coming from the JBoss Portal Platform&apos;s WSRP producer. + </para> + <example> + <title>Example</title> + <para> + <programlisting><![CDATA[ +<page> + <name>Test</name> + + ... + + <portlet-application> + <portlet> + <application-ref>richFacesPortlet</application-ref> + <portlet-ref>richFacesPortlet</portlet-ref> + </portlet> + <title>Added locally</title> + + ... + + </portlet-application> + + <portlet-application> + <wsrp>selfv2./richFacesPortlet.richFacesPortlet</wsrp> + <title>Added from selfv2 consumer</title> + + ... + + </portlet-application> +</page>]]></programlisting> + </para> + </example> + </section> + </section> + </chapter> + <chapter> + <title>Consumers maintenance</title> + <section> + <title>Modifying a currently held registration</title> + <section> + <title>Registration modification for service upgrade</title> + <para> + Producers often offer several levels of service depending on consumers&apos; subscription levels (for + example). This is implemented at the WSRP level with the registration concept: producers can assert which + level of service to provide to consumers based on the values of given registration properties. + </para> + <para> + There might also be cases where you just want to update the registration information because it has + changed. For example, the producer required you to provide a valid email and the previously email + address is not valid anymore and needs to be updated. + </para> + <para> + It is therefore sometimes necessary to modify the registration that concretizes the service agreement + between a consumer and a producer. The following is an example of a producer requiring a valid email (via an + <literal>email</literal> + registration property) as part of its required information that consumers need to provide to be properly + registered. + </para> + <para> + Suppose now that you would like to update the email address that you provided to the remote producer when + you first registered. You will need to tell the producer that the registration data has been modified. + </para> + <para> + Select the consumer for the remote producer in the available consumers list to + display its configuration. Assuming you want to change the email you registered with to + <literal&gt;foo(a)example.com&lt;/literal&gt;, change its value in the field for the + <literal>email</literal> + registration property: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_start.png" format="PNG"/> + </imageobject> + </mediaobject> + Now click on &quot;Update properties&quot; to save the change. A &quot;Modify registration&quot; button should now appear to + let you send this new data to the remote producer: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_modify.png" format="PNG"/> + </imageobject> + </mediaobject> + Click on this new button and, if everything went well and your updated registration has been accepted by + the remote producer, you should see something similar to: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_end.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + </section> + <section id="reg_mod_error"> + <title>Registration modification on producer error</title> + <para> + It can also happen that a producer administrator decided to change its requirement for registered + consumers. JBoss Portal Platform will attempt to help you in this situation. This section will walk through an example using + the <literal>selfv2</literal> consumer (assuming that registration is requiring a valid value for an + <literal>email</literal> + registration property). If you go to the configuration screen for this consumer, you should see: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/config_self.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>Now suppose that the administrator of the producer now additionally requires a value to be provided for a + <literal>name</literal> + registration property. Steps on how to do perform this operation + in JBoss Portal Platform are outlined in the section on how to configure JBoss Portal Platform&apos;s producer + (<xref linkend="producer_config"/>). + Operations with this producer will now fail. If you suspect that a registration modification is required, + you should go to the configuration screen for this remote producer and refresh the information held by + the consumer by pressing &quot;Refresh &amp; Save&quot;: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_self.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>As you can see, the configuration screen now shows the currently held registration information and + the expected information from the producer. Enter a value for the + <literal>name</literal> + property + and then click on &quot;Modify registration&quot;. If all went well and the producer accepted your new registration + data, you should see something similar to: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/modify_reg_self_end.png" format="PNG"/> + </imageobject> + </mediaobject> + <note> + <title>Note</title> + <para>WSRP 1 makes it rather difficult to ascertain for sure what caused an + <exceptionname>OperationFailedFault</exceptionname> + as it is the generic exception returned by + producers if something did not quite happen as expected during a method invocation. This means that + <exceptionname>OperationFailedFault</exceptionname> + can be caused by several different reasons, one + of them being a request to modify the registration data. Please take a look at the log files to see + if you can gather more information as to what happened. WSRP 2 introduces an exception that is + specific to a request to modify registrations thus reducing the ambiguity that exists when using WSRP 1. + </para> + </note> + </section> + </section> + <section> + <title>Consumer operations</title> + <para> + Several operations are available from the consumer list view of the WSRP configuration portlet: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/consumer_operations.png" format="PNG"/> + </imageobject> + </mediaobject> + </para> + <para> + The available operations are: + </para> + <itemizedlist> + <listitem> + <para>Configure: displays the consumer details and allows user to edit them</para> + </listitem> + <listitem> + <para>Refresh: forces the consumer to retrieve the service description from the remote producer to + refresh + the local information (offered portlets, registration information, etc.) + </para> + </listitem> + <listitem> + <para>Activate/Deactivate: activates/deactivates a consumer, governing whether it will be available to + provide portlets and receive portlet invocations + </para> + </listitem> + <listitem> + <para>Register/Deregister: registers/deregisters a consumer based on whether registration is required + and/or acquired + </para> + </listitem> + <listitem> + <para>Delete: destroys the consumer, after deregistering it if it was registered</para> + </listitem> + <listitem> + <para>Export: exports some or all of the consumer&apos;s portlets to be able to later import them in a + different context + </para> + </listitem> + <listitem> + <para>Import: imports some or all of previously exported portlets</para> + </listitem> + </itemizedlist> + <note> + <title>Note</title> + <para> + Import/Export functionality is only available to WSRP 2 consumers of producers that support this optional + functionality. Import functionality is only available if portlets had previously been exported. + </para> + </note> + </section> + <section> + <title>Importing and exporting portlets</title> + <para>Import and export are new functionality added in WSRP 2. Exporting a portlet allows a consumer to get + an opaque representation of the portlet which can then be use by the corresponding import operation to + reconstitute it. It is mostly used in migration scenarios during batch operations. Since JBoss Portal Platform + does not currently support automated migration of portal data, the functionality that is provided as part of + WSRP 2 is necessarily less complete than it could be with full portal support. + </para> + <para>The import/export implementation in JBoss Portal Platform allows users to export portlets + from a given consumer. + These portlets can then be used to replace existing content on pages. This is accomplished by assigning + previously exported portlets to replace the content displayed by windows on the portal&apos;s pages. Below is an example to make things clearer. + </para> + <para>Clicking on the &quot;Export&quot; action for a given consumer will display the list of portlets currently made + available by this specific consumer. An example of such a list is shown below: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/export_portlet_list.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>Once portlets have been selected, they can be exported by clicking on the &quot;Export&quot; button thus making + them available for later import: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/export_done.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>You can re-import the portlets directly by pressing the &quot;Use for import&quot; button or, on the Consumers list + page, using the &quot;Import&quot; action for a given consumer. This assumes that you used that second option and that + you currently have several available sets of previously exported portlets to import from. After clicking the + action link, you should see a screen similar to the one below: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/export_list.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>As you can see this screen presents the list of available exports with available operations for each: + </para> + <itemizedlist> + <listitem> + <para>View: displays the export details as previously seen when the export was first performed</para> + </listitem> + <listitem> + <para>Delete: deletes the selected export, asking you for confirmation first</para> + </listitem> + <listitem> + <para>Use for import: selects the export to import portlets from</para> + </listitem> + </itemizedlist> + <para>Once you have selected an export to import from, you will see a screen similar to the one below:</para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/import_start.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>The screen displays the list of available exported portlets for the previously selected export. You can + select which portlet you want to import by checking the checkbox next to its name. Next, you need to select + the content of which window the imported portlet will replace. This process is done in three steps. This example + assumes that you have the following page called + <literal>page1</literal> + and containing 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> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/import_original_page.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>In this example, you want to replace the content of the + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + by the content of the + <literal>/ajaxPortlet.JSFAJAXPortlet</literal> + portlet that you previously exported. To do so, you will check the checkbox next to the + <literal>/ajaxPortlet.JSFAJAXPortlet</literal> + portlet name to indicate that you want to import its data and then select the + <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 one seen below: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/import_selected_page.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>Note that, at this point, you still need to select the window which content you want to replace before + being able to complete the import operation. Select the + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + window, at which point the &quot;Import&quot; button will become enabled, indicating that you now have all the + necessary data to perform the import. If all goes well, pressing that button should result in a screen + similar to the one below: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/import_success.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>If you now take a look at the + <literal>page1</literal> + page, you should now see that the content + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + window has been replaced by the content of the + <literal>/ajaxPortlet.JSFAJAXPortlet</literal> + imported portlet and the window renamed appropriately: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/import_modified_page.png" format="PNG"/> + </imageobject> + </mediaobject> + </section> + <section> + <title>Erasing local registration data</title> + <para> + There are rare cases where it might be required to erase the local information without being able to + de-register first. This is the case when a consumer is registered with a producer that has been modified by + its administrator to not require registration anymore. If that ever was to happen (most likely, it will not), + you can erase the local registration information from the consumer so that it can resume interacting with + the remote producer. To do so, click on &quot;Erase local registration&quot; button next to the registration context + information on the consumer configuration screen: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/erase_registration.png" format="PNG"/> + </imageobject> + </mediaobject> + <warning> + <title>Warning:</title> + <para> + This operation is dangerous as it can result in inability to interact with the remote producer if invoked + when not required. A warning screen will be displayed to give you a chance to change your mind: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/WSRP/erase_registration_warning.png" format="PNG"/> + </imageobject> + </mediaobject> + </warning> + </section> + </chapter> + <chapter> + <title>Working with WSRP Extensions</title> + <remark>Source https://docs.jboss.org/author/display/GTNPORTAL35/Working+with+WSRP+exten... + <section> + <title>Overview</title> + <para> + The WSRP specifications allows for implementations to extend the protocol using + <ulink url="http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec-os-01.html#_Ex... + . JBoss Portal Platform, as of its WSRP implementation version 2.2.0, provides a way for client code (e.g. portlets) to interact with such extensions in the form of several classes and interfaces gathered within the + <ulink url="https://github.com/gatein/gatein-wsrp/tree/master/api/src/main/... package </ulink> + , the most important ones being + <code>InvocationHandlerDelegate</code> + , + <code>ConsumerExtensionAccessor</code> + and + <code>ProducerExtensionAccessor</code> + . + </para> + <para> + To be able to use this API, you will need to include the + <code>wsrp-integration-api-$WSRP_VERSION.jar</code> + file to your project, where + <code>$WSRP_VERSION</code> + is the version of the JBoss Portal Platform WSRP implementation you wish to use, 2.2.2.Final being the current one. This can be done by adding the following dependency to your maven project: + </para> + <informalexample> + <programlisting> +&lt;dependency&gt; + &lt;groupId&gt;org.gatein.wsrp&lt;/groupId&gt; + &lt;artifactId&gt;wsrp-integration-api&lt;/artifactId&gt; + &lt;version&gt;$WSRP_VERSION&lt;/version&gt; +&lt;/dependency&gt; +</programlisting> + </informalexample> + <section> + <title>InvocationHandlerDelegate infrastructure</title> + <para> + Using the + <code>InvocationHandlerDelegate</code> + infrastructure, custom behavior can now be inserted on either consumer or producer sides to enrich WSRP applications before and/or after portlet requests and/or responses. Please refer to the Javadoc for + <ulink url="https://github.com/gatein/gatein-wsrp/blob/master/api/src/main/... + <code>org.gatein.wsrp.api.extensions.InvocationHandlerDelegate</code> + </ulink> + for more details on this interface and how to implement it. + </para> + <warning> + <para> + Since + <code>InvocationHandlerDelegate</code> + is a very generic interface, it could potentially be used for more than simply working with WSRP extensions. Moreover, since it has access to internal JBoss Portal Platform classes, it is important to be treat access to these internal classes as + <emphasis role="strong">read-only</emphasis> + to prevent any un-intentional side-effects. + </para> + </warning> + </section> + <section> + <title>Injecting InvocationHandlerDelegate implementations</title> + <para> + Implementations of + <code>InvocationHandlerDelegate</code> + <emphasis role="strong">must</emphasis> + follow the same constraints as + <code>RegistrationPolicy</code> + implementations as detailed in + <ulink url="https://docs.jboss.org/author/pages/viewpage.action?pageId=5426... of Registration handling behavior</ulink> + section of the + <ulink url="https://docs.jboss.org/author/pages/viewpage.action?pageId=5426... GateIn&apos;s WSRP Producer</ulink> + chapter, in essence, they + <emphasis role="strong">must</emphasis> + follow the Java + <ulink url="http://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoade... + <code>ServiceLoader</code> + </ulink> + architectural pattern and be deployed in the appropriate + <code>JPP_HOME/gatein/extensions</code> + directory. + </para> + <para> + You can specify only one + <code>InvocationHandlerDelegate</code> + implementation per side: one implementation for the consumer and another one for the producer. This is accomplished by passing the fully classified class name to the appropriate system property when the portal is started: + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>WSRP side</para> + </entry> + <entry> + <para>System property</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>consumer</para> + </entry> + <entry> + <para>org.gatein.wsrp.consumer.handlers.delegate</para> + </entry> + </row> + <row> + <entry> + <para>producer</para> + </entry> + <entry> + <para>org.gatein.wsrp.producer.handlers.delegate</para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <section> + <title>Example</title> + <informalexample> + <programlisting>./standalone.sh -Dorg.gatein.wsrp.consumer.handlers.delegate=com.example.FooInvocationHandlerDelegate</programlisting> + </informalexample> + <para> + will inject the + <code>com.example.FooInvocationHandlerDelegate</code> + class on the consumer side, assuming that class implements the + <code>org.gatein.wsrp.api.extensions.InvocationHandlerDelegate</code> + interface and is packaged and deployed appropriately as explained above. + </para> + </section> + </section> + <section> + <title>Accessing extensions from client code</title> + <para> + You can access extensions from client code using + <code>ConsumerExtensionAccessor</code> + and + <code>ProducerExtensionAccessor</code> + on the consumer and producer, respectively. Each interface provides several methods but you should only have to ever call two of them on each, as shown in the following table: + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>Interface</para> + </entry> + <entry> + <para>Relevant methods</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + <code>ConsumerExtensionAccessor</code> + </para> + </entry> + <entry> + <itemizedlist> + <listitem> + <para> + <code>public void addRequestExtension(Class targetClass, Object extension)</code> + </para> + </listitem> + <listitem> + <para> + <code>public List&lt;UnmarshalledExtension&gt; getResponseExtensionsFrom(Class responseClass)</code> + </para> + </listitem> + </itemizedlist> + </entry> + </row> + <row> + <entry> + <para> + <code>ProducerExtensionAccessor</code> + </para> + </entry> + <entry> + <itemizedlist> + <listitem> + <para> + <code>List&lt;UnmarshalledExtension&gt; getRequestExtensionsFor(Class targetClass)</code> + </para> + </listitem> + <listitem> + <para> + <code>void addResponseExtension(Class wsrpResponseClass, Object extension)</code> + </para> + </listitem> + </itemizedlist> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>Please refer to the Javadoc for these classes for more details.</para> + <note> + <para>We currently only support adding and accessing extensions from a core subset of WSRP classes pertaining to markup, interaction, resource or event requests and responses, as follows:</para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>Request classes</para> + </entry> + <entry> + <para>Response classes</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + <code>org.oasis.wsrp.v2.InteractionParams</code> + </para> + </entry> + <entry> + <para> + <code>org.oasis.wsrp.v2.MarkupResponse</code> + </para> + </entry> + </row> + <row> + <entry> + <para> + <code>org.oasis.wsrp.v2.EventParams</code> + </para> + </entry> + <entry> + <para> + <code>org.oasis.wsrp.v2.BlockingInteractionResponse</code> + </para> + </entry> + </row> + <row> + <entry> + <para> + <code>org.oasis.wsrp.v2.MarkupParams</code> + </para> + </entry> + <entry> + <para> + <code>org.oasis.wsrp.v2.HandleEventsResponse</code> + </para> + </entry> + </row> + <row> + <entry> + <para> + <code>org.oasis.wsrp.v2.ResourceParams</code> + </para> + </entry> + <entry> + <para> + <code>org.oasis.wsrp.v2.ResourceResponse</code> + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </note> + <note> + <para> + We + <emphasis role="strong">strongly</emphasis> + recommend that you use + <code>org.w3c.dom.Element</code> + values as extensions for interoperability purposes. + </para> + </note> + </section> + </section> + <section> + <title>Example implementation</title> + <para> + We also provide a complete, end-to-end example to get you started, which you can find at + <ulink url="https://github.com/gatein/gatein-wsrp/tree/master/examples/invo... + . This example shows how + <code>ExampleConsumerInvocationHandlerDelegate</code> + , a consumer-side + <code>InvocationHandlerDelegate</code> + implementation, can add information extracted from the consumer and pass it along to the producer, working in conjunction with + <code>ExampleProducerInvocationHandlerDelegate</code> + , the associated producer-side + <code>InvocationHandlerDelegate</code> + , to establish a round-trip communication channel outside of the standard WSRP protocol, implementing the following scenario: + </para> + <itemizedlist> + <listitem> + <para> + <code>ExampleConsumerInvocationHandlerDelegate</code> + attaches to the consumer to add the current session id as an extension to render requests sent to the producer. + </para> + </listitem> + <listitem> + <para> + <code>ExampleProducerInvocationHandlerDelegate</code> + provides the counterpart of + <code>ExampleConsumerInvocationHandlerDelegate</code> + on the producer. It checks incoming render requests for potential extensions matching what + <code>ExampleConsumerInvocationHandlerDelegate</code> + sends and adds an extension of its own to the render response so that the consumer-side delegate can know that the information it passed was properly processed. + </para> + </listitem> + </itemizedlist> + <sidebar> + <para>To activate the InvocationHandlerDelegates on both the consumer and producer, start your JBoss Portal Platform instance as follows:</para> + </sidebar> + </section> + </chapter> + <chapter id="producer_config"> + <title>Configuring JBoss Portal Platform&apos;s WSRP Producer</title> + <remark>Source content taken from https://docs.jboss.org/author/display/GTNPORTAL35/Configuring+GateIn%27s+... . Review this page for revision incorporation history.</remark> + <section> + <title>Overview</title> + <para> + The preferred way to configure the behavior of Portal&apos;s WSRP Producer is through the WSRP configuration portlet. + Alternatively, it is possible to add an XML file called + <filename>wsrp-producer-config.xml</filename> + in the + <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/wsrp</filename> + directory. + Several aspects can be modified with respect to whether registration is required for consumers to access + the Producer&apos;s services. + </para> + <note> + <title>Note</title> + <para>An XML Schema defining which elements are available to configure Consumers via XML can be found + in + <filename><replaceable>JPP_HOME</replaceable>/modules/org/gatein/wsrp/main/wsrp-integration-api-&WSRP_VERSION;.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename> + </para> + </note> + <important> + <title>Important</title> + <para> + It is important to note that once the XML configuration file for the producer has been read upon + the WSRP service first start, the associated information is put under control of the JCR (Java Content + Repository). Subsequent launches of the WSRP service will use the JCR-stored information and ignore + the content of the XML configuration file. + </para> + </important> + </section> + <section> + <title>Default configuration</title> + <para> + The default producer configuration requires that consumers register with it before providing access its + services, but does not require any specific registration properties (apart from what is mandated by the + WSRP standard). It does, however, require consumers to be registered before sending them a full service + description. This means that the WSRP producer will not provide the list of offered portlets and other + capabilities to unregistered consumers. </para> + <para>The producer also uses the default + <classname>RegistrationPolicy</classname> + paired with the default + <classname>RegistrationPropertyValidator</classname>. Property + validators will be discussed in greater detail later in <xref linkend="registration-configuration"/>. This allows users to customize how the Portal&apos;s WSRP Producer determines whether a given registration property + is valid or not. + </para> + <para> +JBoss Portal Platform provides a web interface to configure the producer&apos;s behavior. It is accessed by clicking on the &quot;Producer Configuration&quot; tab of the &quot;WSRP&quot; page of the &quot;admin&quot; portal. The image below is what you + should see with the default configuration: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_default.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>You can specify whether or not the producer will send the full service description to + unregistered consumers, and, if it requires registration, which + <classname>RegistrationPolicy</classname> + to use (and, if needed, which + <classname>RegistrationPropertyValidator</classname>), along with required + registration property description for which consumers must provide acceptable values to successfully + register.</para> + <para>The WSDL URLs to access the Portal&apos;s WSRP producer are displayed either in WSRP 1 + or WSRP 2 mode. + </para> + </section> + <section id="registration-configuration"> + <title>Registration configuration</title> + <para> + In order to require consumers to register with Portal&apos;s producer before interacting with it, you need to + configure Portal&apos;s behavior with respect to registration. Registration is optional, as are registration + properties. The producer can require registration without requiring consumers to pass any registration + properties as is the case in the default configuration. </para> + <para>To configure the producer starting with a blank + state: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_blank.png" format="PNG"/> + </imageobject> + </mediaobject> + <para> + You will allow unregistered consumers to see the list of offered portlets so you leave the first checkbox + (&quot;Access to full service description requires consumers to be registered.&quot;) unchecked. You will, however, + specify that consumers will need to be registered to be able to interact with the producer. Check the second + checkbox (&quot;Requires registration. Modifying this information will trigger invalidation of consumer + registrations.&quot;). The screen should now refresh and display: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_registration.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>You can specify the fully-qualified name for your + <classname>RegistrationPolicy</classname> + and + <classname>RegistrationPropertyValidator</classname> + there. Keep the default value. See + <xref linkend="custom_registration"/> + for further information about other available values. </para> + <para>Add a registration property called + <literal>email</literal>. Click &quot;Add property&quot; and enter the appropriate information in the fields, + providing a description for the registration property that can be used by consumers to figure out its + purpose: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_email.png" format="PNG"/> + </imageobject> + </mediaobject> + <para>Click &quot;Save&quot; to record the modifications. + </para> + <note> + <title>Note</title> + <para>At this time, only String (xsd:string) properties are supported. If your application requires more + complex properties, please supply feedback. + </para> + </note> + <note> + <title>Note</title> + <para>If consumers are already registered with the producer, modifying the configuration of required + registration + information will trigger the invalidation of held registrations, requiring consumers to modify their + registration before being able to access the producer again. You saw the consumer side of that process + in + <xref linkend="reg_mod_error"/>. + </para> + </note> + <section id="custom_registration"> + <title>Customization of Registration handling behavior</title> + <para> + Registration handling behavior can be customized by users to suit their Producer needs. This is + accomplished by providing an implementation of the + <classname>RegistrationPolicy</classname> + interface. This interface defines methods that are called by Portal&apos;s Registration service so that + decisions can be made appropriately. A default registration policy that provides basic + behavior is provided and should be enough for most user needs. + </para> + <para> + While the default registration policy provides default behavior for most registration-related aspects, + there is still one aspect that requires configuration: whether a given value for a registration property + is acceptable by the WSRP Producer. This is accomplished by plugging a + <classname>RegistrationPropertyValidator</classname> + in the default registration policy. This allows users to define their own validation mechanism for registration properties that are passed by a consumer to a producer. + </para> + <para> + Please refer to the + <trademark class="trade">Javadoc</trademark> + for + +<ulink url="https://github.com/gatein/gatein-wsrp/blob/master/producer/src/... + <classname>org.gatein.registration.RegistrationPolicy</classname> + </ulink> and + +<ulink url="https://github.com/gatein/gatein-wsrp/blob/master/producer/src/... + <classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname> + </ulink> for more + details on what is expected of each method. + </para> + <para>Defining a registration policy is required for the producer to be correctly configured. If you don&apos;t provide one, the <literal>DefaultRegistrationPolicy</literal> associated to the <literal>DefaultRegistrationPropertyBehavior</literal> is used. + </para> + <figure> + <title>DefaultRegistrationPolicy</title> + <mediaobject> + <imageobject> + <imagedata width="666" fileref="images/WSRP/producer_default.png"/> + </imageobject> + </mediaobject> + </figure> + <para>JBoss Portal Platform can automatically detect deployed implementations of <literal>RegistrationPolicy</literal> and <literal>RegistrationPropertyValidator</literal>, assuming they conform to the following rules:</para> + <itemizedlist> + <listitem> + <para>The implementations must follow the Java <ulink url=".oracle.com/javase/7/docs/api/java/util/ServiceLoader.html"... architecture:</para> + <itemizedlist> + <listitem> + <para>They must be packaged as JARs</para> + </listitem> + <listitem> + <para>For <literal>RegistrationPolicy</literal> implementations, they must contain a special <filename>META-INF/services/org.gatein.registration.RegistrationPolicy</filename> file.</para> + </listitem> + <listitem> + <para>For <literal>RegistrationPropertyValidator</literal> implementations they must contain<filename>META-INF/services/org.gatein.registration.policies.RegistrationPropertyValidator</filename> and include a line with the fully qualified name of the implementation class.</para> + </listitem> + </itemizedlist> + <note> + <para>It is possible to package several implementations in the same JAR file, provided that each implementation class is referenced on its own line in the appropriate service definition file. To make things easier, we provide an example project of a RegistrationPolicy implementation and packaging at <ulink url="https://github.com/gatein/gatein-wsrp/tree/master/examples/poli... + </note> + </listitem> + <listitem> + <para>The implementation classes must provide a default, no-argument constructor for dynamic instantiation.</para> + </listitem> + <listitem> + <para>The implementation JARs must be deployed in <filename><replaceable>JPP_HOME</replaceable>/gatein/extensions</filename>.</para> + </listitem> + <listitem> + <para>The implementation JARs should use the <filename>.wsrp.jar</filename> extension. This is not mandatory but helps process the file faster by marking it as a WSRP extension.</para> + </listitem> + </itemizedlist> + <para>If you deployed the example <literal>RegistrationPolicy</literal> provided from the github repository (<filename>registration-policy-example.wsrp.jar</filename>) to the <filename>JPP_HOME/gatein/extensions</filename> directory, it will appear in the list of available policies in the producer configuration screen.</para> + </section> + </section> + <section> + <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. </para> + <para>A way to relax + the validation that the WSRP producer performs on the data provided by consumers has been introduced to help with + interoperability by accepting data that would normally be invalid. Note that this validation + algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes. + </para> + <para> + 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 &quot;Use strict WSRP + compliance.&quot; checkbox on the Producer configuration screen. + </para> + </section> + </chapter> + </part> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/> </book> Modified: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml 2013-05-16 04:35:34 UTC (rev 9280) +++ epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/Revision_History.xml 2013-05-22 05:52:42 UTC (rev 9281) @@ -8,6 +8,20 @@ <simpara> <revhistory> <revision> + <revnumber>6.1.0-4</revnumber> + <date>Friday May 17 2013</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Added WSRP part.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.1.0-3</revnumber> <date>Wed May 15 2013</date> <author> Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/WSRP.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/WSRP.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_create.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_create.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_end.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_end.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_init.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_init.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_missing.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_missing.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_refresh.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_refresh.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_self.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_self.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wsdl.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wsdl.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wss_selected.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/config_wss_selected.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/consumer_operations.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/consumer_operations.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration_warning.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/erase_registration_warning.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_done.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_done.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_list.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_list.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_portlet_list.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/export_portlet_list.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_modified_page.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_modified_page.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_original_page.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_original_page.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_selected_page.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_selected_page.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_start.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_start.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_success.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/import_success.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_end.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_end.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_modify.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_modify.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self_end.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_self_end.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_start.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/modify_reg_start.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_blank.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_blank.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_default.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_default.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_email.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_email.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_registration.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/producer_registration.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets_category.png =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Administration_and_Configuration_Guide/en-US/images/remote_portlets_category.png ___________________________________________________________________ Added: svn:mime-type + image/png Modified: epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/WSRP.xml 2013-05-16 04:35:34 UTC (rev 9280) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/WSRP.xml 2013-05-22 05:52:42 UTC (rev 9281) @@ -72,7 +72,7 @@ </note> </section> <section id="Deploying_JPP_WSRP_Services"> - <title><remark>BZ#839355</remark>Deploying JBoss Portal Platform&apos;s WSRP services</title> + <title>Deploying JBoss Portal Platform&apos;s WSRP services</title> <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Deploying+GateIn%27s+WS... <para> JBoss Portal Platform provides complete support for WSRP 1.0 and 2.0 standard interfaces, and offers both consumer and Modified: epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml 2013-05-16 04:35:34 UTC (rev 9280) +++ epp/docs/JPP/trunk/User_Guide/en-US/Revision_History.xml 2013-05-22 05:52:42 UTC (rev 9281) @@ -17,7 +17,7 @@ </author> <revdescription> <simplelist> - <member>BZ#921356 - Removed all instances of &quot;Refer to&quot; in the guide.</member> + <member>BZ#921356 - Removed all instances of &quot;Refer to&quot; in the guide, and replaced with &quot;See&quot;, according to new style guide rules for Enterprise docs.</member> </simplelist> </revdescription> </revision>