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