Author: smumford
Date: 2011-11-30 18:16:45 -0500 (Wed, 30 Nov 2011)
New Revision: 8169
Modified:
epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml
Log:
Ported GateIn WSRP changes (r8166)
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-30 18:05:57 UTC
(rev 8168)
+++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml 2011-11-30 23:16:45 UTC
(rev 8169)
@@ -3,271 +3,237 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
-<chapter id="wsrp">
- <title>Web Services for Remote Portlets (WSRP)</title>
-
- <section>
- <title>Introduction</title>
- <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:
- <itemizedlist>
- <listitem>
- <para>Content hosts, such as portal servers, providing Portlets as
presentation-oriented web services
- that can be used by aggregation engines.
+ <chapter id="wsrp">
+ <title>Web Services for Remote Portlets (WSRP)</title>
+
+ <section>
+ <title>Introduction</title>
+
+ <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:
+ <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>
+
+ <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>. We suggest reading the <ulink
url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr...
for a good, albeit technical, overview of WSRP.
+ </para>
+ </section>
+
+ <section id="wsrp_support">
+ <title>Level of support in JBoss Enterprise Portal Platform</title>
+
+ <para>
+ The WSRP Technical Committee defined <ulink
url="http://www.oasis-open.org/committees/download.php/3073">... Use
Profiles</ulink> to help with WSRP interoperability. We will refer to terms defined
in that document in this section.
+ </para>
+
+ <para>
+ JBoss Enterprise Portal Platform provides a Simple level of support for our
WSRP Producer except that out-of-band registration is not currently handled. We support
in-band registration and persistent local state (which are defined at the Complex level).
+ </para>
+
+ <para>
+ On the Consumer side, JBoss Enterprise Portal Platform provides a Medium
level of support for WSRP, except that we only handle HTML markup (as JBoss Enterprise
Portal Platform itself doesn't handle other markup types). We do support explicit
portlet cloning and we fully support the PortletManagement interface.
+ </para>
+
+ <para>
+ As far as caching goes, we have Level 1 Producer and Consumer. We support
Cookie handling properly on the Consumer and our Producer requires initialization of
cookies (as we have found that it improved interoperabilty with some consumers). We
don't support custom window states or modes, as JBoss Enterprise Portal Platform
doesn't either. We do, however, support CSS on both the Producer (though it's more
a function of the portlets than inherent Producer capability) and Consumer.
+ </para>
+
+ <para>
+ While we provide a complete implementation of WSRP 1.0, we 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 Enterprise Portal Platform supports WSRP 2.0 with a complete
implementation of the non-optional features. The only features that we have not
implemented is support for lifetimes and leasing support.
+ </para>
+
+ <note>
+ <para>
+ As of version &VY; of JBoss Enterprise Portal Platform, WSRP is only
activated and supported when JBoss Enterprise Portal Platform is deployed on JBoss
Application Server.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>Deploying JBoss Enterprise Portal Platform's WSRP
services</title>
+
+ <para>
+ JBoss Enterprise Portal Platform provides a complete support of 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 Enterprise Portal Platform
extension and is now self-contained in an easy to install package named
<filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear</filename>
where <filename>$JBOSS_PROFILE_HOME</filename> refers to your JBoss AS profile
directory (<filename>default</filename>, for instance).
+ </para>
+
+ <para>
+ The extension itself is composed of the following components, assuming
<code>$WSRP_VERSION</code> (at the time of the writing, it was 2.1.0-GA) is
the version of the WSRP component and <code>$PORTAL_VERSION</code> (at the
time of the writing, it was &VY;) is the current JBoss Enterprise Portal Platform
version:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>META-INF</filename> 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. Please see the <link
linkend="wss_configuration">WSRP and WS-Security</link> section for
more details.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
<filename>extension-component-$PORTAL_VERSION.jar</filename>, which contains
the components needed to integrate the WSRP component into JBoss Enterprise Portal
Platform. It also includes the default configuration files for the WSRP producer and the
default WSRP consumers.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
<filename>extension-config-$PORTAL_VERSION.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>
+ <filename>extension-war-$PORTAL_VERSION.war</filename>,
which contains the configuration files needed by the GateIn 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 Enterprise Portal Platform.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename>lib</filename>, which contains the different
libraries needed by the WSRP service.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <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>
+
<filename>wsrp-producer-jb5wsss-$WSRP_VERSION.war</filename>, which 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. Please see the <link
linkend="wss_configuration">WSRP and WS-Security</link> section for
more details.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ If you're not going to use WSRP in JBoss Enterprise Portal Platform, it
won't 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 Enterprise Portal
Platform on a non-default port or hostname</title>
+
+ <para>
+ JBoss WS (the web service stack that JBoss Enterprise Portal Platform
uses) should take care of the details of updating the port and host name used in WSDL. See
the <ulink
url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration...
WS user guide on that subject </ulink> for more details.
+ </para>
+
+ <para>
+ Of course, if you have modified 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 Enterprise Portal Platform's 'self' producer. Please refer to
the <xref linkend="consumer_configuration"/> to learn how to do so.
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Securing WSRP</title>
+
+ <section>
+ <title>Considerations to use WSRP with SSL</title>
+
+ <para>
+ It is possible to use WSRP over SSL for secure exchange of data. Please
refer to the <ulink
url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu...
on how to do so from <ulink
url="http://community.jboss.org/wiki/GateIn">GateIn's
wiki</ulink>.
+ </para>
+ </section>
+
+ <section>
+ <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. 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>
- </listitem>
- <listitem>
- <para>Aggregating frameworks, including portal servers, consuming
presentation-oriented web services
- offered by content providers and integrating them into the framework.
+ </note>
+
+ <warning>
+ <title>Encryption</title>
+
+ <para>
+ You will want to encrypt the credentials being sent between the
consumer and producer, otherwise they will be sent in plain text and could be easily
intercepted. You can either 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. <emphasis role="bold">Use of encryption is strongly
recommended.</emphasis>
</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <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>.
- We suggest reading the
- <ulink
url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr...
- for a good, albeit technical, overview of WSRP.
- </para>
- </section>
-
- <section id="wsrp_support">
- <title>Level of support in JBoss Enterprise Portal Platform</title>
- <para>The WSRP Technical Committee defined
- <ulink
url="http://www.oasis-open.org/committees/download.php/3073">... Use
Profiles</ulink>
- to help with WSRP interoperability. We will refer to terms defined in that
document in
- this section.
- </para>
-
- <para>JBoss Enterprise Portal Platform provides a Simple level of support for
our WSRP Producer except that out-of-band registration
- is not currently handled. We support in-band registration and persistent local
state (which are
- defined at the Complex level).
- </para>
-
- <para>On the Consumer side, JBoss Enterprise Portal Platform provides a
Medium level of support for WSRP, except that we only handle
- HTML markup (as JBoss Enterprise Portal Platform itself doesn't handle other
markup types). We do support explicit portlet
- cloning and we fully support the PortletManagement interface.
- </para>
-
- <para>As far as caching goes, we have Level 1 Producer and Consumer. We
support Cookie handling properly on the
- Consumer and our Producer requires initialization of cookies (as we have found
that it improved interoperabilty
- with some consumers). We don't support custom window states or modes, as
JBoss Enterprise Portal Platform doesn't either. We do,
- however, support CSS on both the Producer (though it's more a function of
the portlets than inherent Producer
- capability) and Consumer.
- </para>
-
- <para>While we provide a complete implementation of WSRP 1.0, we 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 Enterprise Portal Platform supports WSRP 2.0 with a complete
implementation of the non-optional features. The only
- features that we have not implemented is support for lifetimes and leasing
- support.
- </para>
-
- <note>
- <para>As of version &VY; of JBoss Enterprise Portal Platform, WSRP is
only activated and supported
- when JBoss Enterprise Portal Platform is deployed on JBoss Application
Server.
- </para>
- </note>
- </section>
-
- <section>
- <title>Deploying JBoss Enterprise Portal Platform's WSRP
services</title>
- <para>
- JBoss Enterprise Portal Platform provides a complete support of 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 Enterprise Portal Platform
- extension and is now self-contained in an easy to install package named
-
<filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear</filename>
- where
- <filename>$JBOSS_PROFILE_HOME</filename>
- refers to your JBoss AS profile directory
(<filename>default</filename>, for instance).
- </para>
- <para>
- The extension itself is composed of the following components, assuming
- <code>$WSRP_VERSION</code>
- (at the time of the writing, it was 2.1.0-GA) is the version of the WSRP
component and
- <code>$PORTAL_VERSION</code>
- (at the time of the writing, it was &VY;) is the current JBoss Enterprise
Portal Platform version:
- <itemizedlist>
- <listitem>
+ </warning>
+
+ <important>
+ <title>Credentials</title>
+
<para>
- <filename>META-INF</filename>
- 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.
Please see the
- <link linkend="wss_configuration">WSRP and
WS-Security</link> section for more details.
+ 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>
- </listitem>
- <listitem>
+
<para>
-
<filename>extension-component-$PORTAL_VERSION.jar</filename>, which contains
the components needed to
- integrate the WSRP component into JBoss Enterprise Portal Platform. It
also includes the default configuration files for
- the WSRP producer and the default WSRP consumers.
+ The recommended approach for this situation would be to use a common
ldap configuration. Please see the user guide on how to configure ldap for use with JBoss
Enterprise Portal Platform
</para>
- </listitem>
- <listitem>
+ </important>
+
+ <para>
+ The GateIn Wiki article, <ulink
url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity... GateIn
WSRP and Web Service Security</ulink>, also provides a step-by-step example on how
to configure WSRP with WS-Security.
+ </para>
+
+ <section id="wss_configuration">
+ <title>WS-Security Configuration</title>
+
<para>
- <filename>extension-config-$PORTAL_VERSION.jar</filename>,
which contains the configuration file
- needed by the GateIn extension mechanism to properly register this EAR
as an extension.
+ JBoss Enterprise Portal Platform uses JBossWS Native to handle
ws-security. Please see 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 indepth configuration options. 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>
- </listitem>
- <listitem>
+
<para>
- <filename>extension-war-$PORTAL_VERSION.war</filename>,
which contains the configuration files
- needed by the GateIn 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 Enterprise
Portal Platform.
+ The following are the JBossWS Native configuration files which need to
be configure for WSRP:
</para>
- </listitem>
- <listitem>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+
<filename>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</filename>:
JBossWS configuration file for the consumer.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
<filename>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml
</filename>: JBossWS configuration file for the producer.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>WS-Security Producer Configuration</title>
+
<para>
- <filename>lib</filename>, which contains the different
libraries needed by the WSRP service.
+ Other than the JBossWS configuration file mention above, no other
configuration changes should be necessary for the producer.
</para>
- </listitem>
- <listitem>
+ </section>
+
+ <section>
+ <title>WS-Security Consumer Configuration</title>
+
<para>
- <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.
+ The consumer requires a few changes before it will function properly
with WS-Security. The consumer needs access to the current servlet request since this is
used to retrieve the currently authenticated user. In order for the consumer to access
this information, it needs a special servlet-filter added to the portal.
</para>
- </listitem>
- <listitem>
-
<para><filename>wsrp-producer-jb5wsss-$WSRP_VERSION.war</filename>,
which 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. Please see the <link
linkend="wss_configuration">WSRP and WS-Security</link> section
- for more details.
+
+ <para>
+ In
<filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> add the following
information:
</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- If you're not going to use WSRP in JBoss Enterprise Portal Platform, it
won't 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 Enterprise Portal
Platform on a non-default port or hostname</title>
- <para>
- JBoss WS (the web service stack that JBoss Enterprise Portal Platform uses)
should take care of the details of updating the
- port and host name used in WSDL. See the
- <ulink
url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration...
WS user guide on that
- subject
- </ulink>
- for more details.
- </para>
- <para>
- Of course, if you have modified 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 Enterprise
Portal Platform's 'self' producer. Please refer to
- the
- <xref linkend="consumer_configuration"/>
- to learn how to do so.
- </para>
- </section>
- </section>
-
- <section>
- <title>Securing WSRP</title>
- <section>
- <title>Considerations to use WSRP with SSL</title>
- <para>It is possible to use WSRP over SSL for secure exchange of data.
Please refer to the
- <ulink
url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu...
- on how to do so from
- <ulink
url="http://community.jboss.org/wiki/GateIn">GateIn's
wiki</ulink>.
- </para>
- </section>
- <section>
- <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. 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>You will want to encrypt the credentials being sent between the
consumer and producer, otherwise they
- will be sent in plain text and could be easily intercepted. You can
either 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. <emphasis role="bold">Use of
encryption is strongly recommended.</emphasis>
- </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. 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. Please
- see the user guide on how to configure ldap for use with JBoss Enterprise
Portal Platform
- </para>
- </important>
- <para>The GateIn Wiki article, <ulink
url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity...
- GateIn WSRP and Web Service Security</ulink>, also provides a
step-by-step example on how to configure
- WSRP with WS-Security.
- </para>
- <section id="wss_configuration">
- <title>WS-Security Configuration</title>
- <para>JBoss Enterprise Portal Platform uses JBossWS Native to handle
ws-security. Please see 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 indepth configuration options. 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>
- <itemizedlist>
- <listitem>
- <para>
-
<filename>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</filename>:
JBossWS
- configuration file for the consumer.
- </para>
- </listitem>
- <listitem>
- <para>
-
<filename>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml
- </filename>: JBossWS configuration file for the producer.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <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>
- <title>WS-Security Consumer Configuration</title>
- <para>The consumer requires a few changes before it will function
properly with WS-Security. The consumer
- needs access to the current servlet request since this is used to
retrieve the currently authenticated
- user. In order for the consumer to access this information, it needs a
special servlet-filter added to
- the portal.
- </para>
- <para>In
<filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> add the following
information:
- </para>
<programlisting role="XML"><![CDATA[<!-- Filter to put request and
response in ServletAccess -->
<filter>
<filter-name>ServletAccessFilter</filter-name>
@@ -278,62 +244,73 @@
<url-pattern>/*</url-pattern>
</filter-mapping>]]>
</programlisting>
- <para>
- Finally, in the WSRP Configuration portlet, in the consumer configuration
options, you will need to check the 'Enable WS Security' checkbox:
- </para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/config_wss_selected.png"
format="PNG" align="center" valign="middle"
scalefit="1"/>
- </imageobject>
- </mediaobject>
- </section>
- <section>
- <title>WS-Security Consumer Checklist</title>
- <para>
- In order for the consumer to handle ws-security, the following steps must be
completed properly
- </para>
- <itemizedlist>
- <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>
- </itemizedlist>
- <para>The consumer will not properly handle ws-security unless all 3 are
properly configured</para>
- </section>
+ <para>
+ Finally, in the WSRP Configuration portlet, in the consumer
configuration options, you will need to check the 'Enable WS Security' checkbox:
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/WSRP/config_wss_selected.png" format="PNG"
align="center" valign="middle" scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section>
+ <title>WS-Security Consumer Checklist</title>
+
+ <para>
+ In order for the consumer to handle ws-security, the following steps
must be completed properly
+ </para>
+
+ <itemizedlist>
+ <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>
+ </itemizedlist>
+
+ <para>
+ The consumer will not properly handle ws-security unless all 3 are
properly configured
+ </para>
+ </section>
+ </section>
</section>
- </section>
-
- <section>
- <title>Making a portlet remotable</title>
- <important>
+
+ <section>
+ <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>
- 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.
+ JBoss Enterprise Portal Platform does <emphasis
role="bold">NOT</emphasis>, by default, expose local portlets for
consumption by remote WSRP consumers. In order to make a portlet remotely available, it
must be made "remotable" by marking it as such in the associated
<filename>portlet.xml</filename>. 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 don't need your portlet to be available remotely.
</para>
- </important>
- <para>JBoss Enterprise Portal Platform does
- <emphasis role="bold">NOT</emphasis>, by default, expose
local portlets for consumption
- by remote WSRP consumers. In order to make a portlet remotely available, it must
be made "remotable" by marking
- it as such in the associated
- <filename>portlet.xml</filename>. 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 don't need your portlet to be available remotely.
- </para>
- <para>In the following example, the "BasicPortlet" portlet is
specified as being remotable.
- </para>
- <example>
- <title>Example</title>
+
<para>
- <programlisting><![CDATA[
+ In the following example, the "BasicPortlet" portlet is specified
as being remotable.
+ </para>
+
+ <example>
+ <title>Example</title>
+
+ <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"
@@ -351,24 +328,18 @@
</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. Let's look at an
- example:
- </para>
- <example>
- <title>Example</title>
+ </para>
+ </example>
+
<para>
- <programlisting><![CDATA[
+ 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. Let's look at an example:
+ </para>
+
+ <example>
+ <title>Example</title>
+
+ <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"
@@ -395,239 +366,157 @@
</container-runtime-option>
</portlet-app>]]>
</programlisting>
+ </para>
+ </example>
+
+ <para>
+ In the example above, we defined 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
Enterprise Portal Platform's WSRP producer. Note, however, that it is possible to
override the default behavior: specifying a value for the
<code>org.gatein.pc.remotable container-runtime-option</code> at the
<code>portlet</code> level will take precedence over the default. 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>. 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>
-
- <para>
- In the example above, we defined 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 Enterprise Portal Platform's
- WSRP
- producer.
- Note, however, that it is possible to override the default behavior: specifying
a value for the
- <code>org.gatein.pc.remotable container-runtime-option</code>
- at the
- <code>portlet</code>
- level will take precedence over the default. 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>.
- 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>
- </section>
-
- <section>
- <title>Consuming JBoss Enterprise Portal Platform's 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's WSDL definition. Please refer to the remote
producer's documentation for specific
- instructions. For instructions on how to do so in JBoss Enterprise Portal
Platform, please refer to
- <xref linkend="consumer_configuration"/>.
- </para>
- <para>
- JBoss Enterprise Portal Platform'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>
- </section>
-
- <section id="consumer_configuration">
- <title>Consuming remote WSRP portlets in JBoss Enterprise Portal
Platform</title>
+ </section>
+
<section>
- <title>Overview</title>
+ <title>Consuming JBoss Enterprise Portal Platform's WSRP portlets from
a remote Consumer</title>
+
<para>
- To be able to consume WSRP portlets exposed by a remote producer, JBoss
Enterprise Portal Platform's WSRP consumer needs to
- know how to access that remote producer. One 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.
+ WSRP Producers vary a lot as far as how they are configured. Most of them
require that you specify the URL for the Producer's WSDL definition. Please refer to
the remote producer's documentation for specific instructions. For instructions on how
to do so in JBoss Enterprise Portal Platform, please refer to <xref
linkend="consumer_configuration"/>.
</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.
+ JBoss Enterprise Portal Platform'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>
</section>
-
- <section id="consumer_gui">
- <title>Configuring a remote producer using the configuration
portlet</title>
- <para>
- Let's work through the steps of defining access to a remote producer
using the configuration portlet so that its portlets can be
- consumed within JBoss Enterprise Portal Platform. We will configure access to
NetUnity's public WSRP producer.
- </para>
-
- <note>
+
+ <section id="consumer_configuration">
+ <title>Consuming remote WSRP portlets in JBoss Enterprise Portal
Platform</title>
+
+ <section>
+ <title>Overview</title>
+
<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 GateIn's
- <ulink
url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis...
page
- </ulink>
- for more details.
+ To be able to consume WSRP portlets exposed by a remote producer, JBoss
Enterprise Portal Platform's WSRP consumer needs to know how to access that remote
producer. One 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>
- </note>
-
- <para>
- JBoss Enterprise Portal Platform provides a portlet to configure access
(among other functions) to remote WSRP Producers
- grahically. Starting with &VY;, 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&username=root&password=gtn">
-
http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass...
- </ulink>
- </para>
-
- <para>
- You should see a screen similar to:
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/config_init.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
- </imageobject>
- </mediaobject>
- 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>
+
<para>
- The WSRP configuration didn't use to be installed by default in
previous versions of JBoss Enterprise Portal Platform.
- We include here the legacy instructions on how to install this portlet in
case you ever need to
- re-install it.
+ 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 id="consumer_gui">
+ <title>Configuring a remote producer using the configuration
portlet</title>
+
<para>
- Use the usual procedure to log in as a Portal administrator and go to the
Application
- Registry. With the default install, you can just go to
- <ulink
-
url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&username=root&password=gtn">
-
http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass...
- </ulink>
- Add the WSRP Configuration portlet to the Administration category. If you
use the Import Applications
- functionality, the WSRP Configuration portlet will be automatically added
to the Administration
- category.
+ Let's work through the steps of defining access to a remote producer
using the configuration portlet so that its portlets can be consumed within JBoss
Enterprise Portal Platform. We will configure access to NetUnity's public WSRP
producer.
</para>
- <para>
- Now that the portlet is added to a category, it can be added to a page and
used. We recommend adding
- it to the same page as the Application Registry as operations relating to
WSRP and adding portlets to
- categories are somewhat related as we will see. Go ahead and add the WSRP
Configuration portlet to the
- page using the standard procedure.
- </para>
- </note>
-
- <para>
- Next, we create a new Consumer which we will call
<literal>netunity</literal>. Type
- "<literal>netunity</literal>" in
- the "Create a consumer named:" field then click on "Create
consumer":
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/config_create.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
- </imageobject>
- </mediaobject>
- You should now see a form allowing you to enter/modify the information about
the Consumer.
- Set the cache expiration value to 300 seconds, leave the default timeout
value for web services (WS)
- operations and enter the WSDL URL for the producer in the text field
- and press the "Refresh & Save" button:
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/config_wsdl.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
- </imageobject>
- </mediaobject>
- This will retrieve the service description associated with the Producer which
WSRP interface is described
- by the WSDL file found at the URL you just entered. In our case, querying the
service description will
- allow us to learn that the Producer requires registration, requested three
registration properties and that
- we are missing values for these properties:
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/config_missing.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
- </imageobject>
- </mediaobject>
- 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 "Refresh &
Save" button should result in:
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/config_end.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
- </imageobject>
- </mediaobject>
-
+
<note>
- <para>At this point, there is no automated way to learn about which
possible values (if any) are
- expected by the remote Producer. Sometimes, the possible values will be
indicated in the
- registration
- property description but this is not always the case... Please refer to
the specific Producer's
- documentation.
+ <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 GateIn's <ulink
url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis...
page </ulink> for more details.
</para>
</note>
- </para>
-
- <para>
- If we had been dealing with a producer which required registration but
didn't 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), we'd have seen something similar to, after pressing the
"Refresh & Save" button:
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/config_refresh.png"
format="PNG" align="center" valign="middle"
+
+ <para>
+ JBoss Enterprise Portal Platform provides a portlet to configure access
(among other functions) to remote WSRP Producers grahically. Starting with &VY;, 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&username=root&password=gtn">
http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass...
</ulink>
+ </para>
+
+ <para>
+ You should see a screen similar to:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_init.png"
format="PNG" align="center" valign="middle"
scalefit="1"/>
- </imageobject>
- </mediaobject>
- </para>
- </section>
-
- <section id="consumer_xml">
- <title>Configuring access to remote producers via XML</title>
-
- <para>While we recommend you use the WSRP Configuration portlet to
configure Consumers, we provide an
- alternative way to configure consumers by adding an XML file called
- <filename>wsrp-consumers-config.xml</filename> in the
- <filename>$JBOSS_PROFILE_HOME/conf/gatein/</filename>
directory.
+ </imageobject>
+ </mediaobject>
+ 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>
- <para>An XML Schema defining which elements are available to
configure Consumers via XML can be found
- in
- <filename>
-
$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd
- </filename>
+ <para>
+ The WSRP configuration didn't use to be installed by default in
previous versions of JBoss Enterprise Portal Platform. We include here the legacy
instructions on how to install this portlet in case you ever need to re-install it.
</para>
- </note>
- <important>
+
<para>
- It is important to note that 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.
+ Use the usual procedure to log in as a Portal administrator and go to
the Application Registry. With the default install, you can just go to <ulink
+
url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&username=root&password=gtn">
http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass...
</ulink> Add the WSRP Configuration portlet to the Administration category. If you
use the Import Applications functionality, the WSRP Configuration portlet will be
automatically added to the Administration category.
</para>
-
- <!--<para>It is important to note how the XML consumers
configuration file is processed. It is read the first
+
+ <para>
+ Now that the portlet is added to a category, it can be added to a page
and used. We recommend adding it to the same page as the Application Registry as
operations relating to WSRP and adding portlets to categories are somewhat related as we
will see. Go ahead and add the WSRP Configuration portlet to the page using the standard
procedure.
+ </para>
+ </note>
+
+ <para>
+ Next, we create a new Consumer which we will call
<literal>netunity</literal>. Type
"<literal>netunity</literal>" in the "Create a consumer
named:" field then click on "Create consumer":
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_create.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ You should now see a form allowing you to enter/modify the information
about the Consumer. Set the cache expiration value to 300 seconds, leave the default
timeout value for web services (WS) operations and enter the WSDL URL for the producer in
the text field and press the "Refresh & Save" button:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_wsdl.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ This will retrieve the service description associated with the Producer
which WSRP interface is described by the WSDL file found at the URL you just entered. In
our case, querying the service description will allow us to learn that the Producer
requires registration, requested three registration properties and that we are missing
values for these properties:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_missing.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ 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 "Refresh & Save" button should
result in:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_end.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+
+ <note>
+ <para>
+ At this point, there is no automated way to learn about which
possible values (if any) are expected by the remote Producer. Sometimes, the possible
values will be indicated in the registration property description but this is not always
the case... Please refer to the specific Producer's documentation.
+ </para>
+ </note>
+ </para>
+
+ <para>
+ If we had been dealing with a producer which required registration but
didn't 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),
we'd have seen something similar to, after pressing the "Refresh &
Save" button:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_refresh.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ </section>
+
+ <section id="consumer_xml">
+ <title>Configuring access to remote producers via XML</title>
+
+ <para>
+ While we recommend you use the WSRP Configuration portlet to configure
Consumers, we provide an alternative way to configure consumers by adding an XML file
called <filename>wsrp-consumers-config.xml</filename> in the
<filename>$JBOSS_PROFILE_HOME/conf/gatein/</filename> directory.
+ <note>
+ <para>
+ An XML Schema defining which elements are available to configure
Consumers via XML can be found in <filename>
$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd
</filename>
+ </para>
+ </note>
+
+ <important>
+ <para>
+ It is important to note that 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
@@ -645,120 +534,75 @@
(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>
- </para>
-
- <section>
- <title>Required configuration information</title>
-
- <para>Let's now look at which information needs to be provided to
configure access to a remote producer.
+ </important>
</para>
-
- <para>First, we need to provide an identifier for the producer we are
configuring so that we can refer to it
- afterwards. This is accomplished via the mandatory
- <literal>id</literal>
- attribute of the
- <literal><wsrp-producer></literal>
- element.
- </para>
-
- <para>JBoss Enterprise Portal Platform also needs to learn about the
remote producer's endpoints to be able to connect to the
- remote web services and perform WSRP invocations. This is accomplished by
specifying the URL for the
- WSDL description for the remote WSRP service, using the
- <literal><endpoint-wsdl-url></literal>
- element.
- </para>
-
- <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>
- <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 roundtrips between the local
- consumer and the remote producer, it is possible to cache some of the
information sent by the producer
- (such as the list of offered portlets) for a given duration. The rate at
which the information is
- refreshed is
- defined by the
- <literal>expiration-cache</literal>
- attribute of the
- <literal><wsrp-producer></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 Enterprise 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, we recommend
that you use this caching
- facility to minimize bandwidth usage.
- </para>
-
- <para>It is also possible to define a timeout after which WS operations
are considered as failed. This is
- helpful to avoid blocking the WSRP service, waiting forever on the service
that doesn't answer. Use the
- <literal>ws-timeout</literal>
- attribute of the
- <literal><wsrp-producer></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.
- <note>
- <para>At this time, though, only simple String properties are
supported and it is not possible to
- configure complex registration data. This should, however, be
sufficient for most cases.
- </para>
- </note>
- </para>
-
- <para>Registration configuration is done via the
- <literal><registration-data></literal>
- element. Since JBoss Enterprise 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><registration-data></literal>
- element. Values for the registration properties
- required by the remote producer can be provided via
- <literal><property></literal>
- elements. See the example below for more details. Additionally, you can
override the default consumer
- name automatically provided by JBoss Enterprise Portal Platform via the
- <literal><consumer-name></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>
-
- <para>
- Here is the configuration of the
- <literal>selfv1</literal>
- and
- <literal>selfv2</literal>
- consumers as found in
-
<filename>$JBOSS_PROFILE_HOME/deploy/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 shouldn't
need to edit it. If you want to make
- modifications to it, we recommend that you follow the procedure
detailed in
- <xref linkend="consumer_gui"/>.
- </para>
- </note>
- </para>
-
- <example>
- <title>Example</title>
+
+ <section>
+ <title>Required configuration information</title>
+
<para>
- <programlisting><![CDATA[
+ Let's now look at which information needs to be provided to
configure access to a remote producer.
+ </para>
+
+ <para>
+ First, we need to provide an identifier for the producer we are
configuring so that we can refer to it afterwards. This is accomplished via the mandatory
<literal>id</literal> attribute of the
<literal><wsrp-producer></literal> element.
+ </para>
+
+ <para>
+ JBoss Enterprise Portal Platform also needs to learn about the remote
producer's endpoints to be able to connect to the remote web services and perform WSRP
invocations. This is accomplished by specifying the URL for the WSDL description for the
remote WSRP service, using the
<literal><endpoint-wsdl-url></literal> element.
+ </para>
+
+ <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>
+ <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
roundtrips between the local consumer and the remote producer, it is possible to cache
some of the information sent by the producer (such as the list of offered portlets) for a
given duration. The rate at which the information is refreshed is defined by the
<literal>expiration-cache</literal> attribute of the
<literal><wsrp-producer></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 Enterprise 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, we recommend that you use this caching facility to minimize bandwidth us!
age.
+ </para>
+
+ <para>
+ It is also possible to define a timeout after which WS operations are
considered as failed. This is helpful to avoid blocking the WSRP service, waiting forever
on the service that doesn't answer. Use the <literal>ws-timeout</literal>
attribute of the <literal><wsrp-producer></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.
+ <note>
+ <para>
+ At this time, though, only simple String properties are supported
and it is not possible to configure complex registration data. This should, however, be
sufficient for most cases.
+ </para>
+ </note>
+ </para>
+
+ <para>
+ Registration configuration is done via the
<literal><registration-data></literal> element. Since JBoss
Enterprise 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><registration-data></literal> element. Values for the
registration properties required by the remote producer can be provided via
<literal><property></literal> elements. See the example below
for more details. Additionally, you can override the default consumer name automatically
provided by JBoss Enterprise Portal Platform via the
<literal><consumer-name></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>
+
+ <para>
+ Here is the configuration of the <literal>selfv1</literal>
and <literal>selfv2</literal> consumers as found in
<filename>$JBOSS_PROFILE_HOME/deploy/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
shouldn't need to edit it. If you want to make modifications to it, we recommend that
you follow the procedure detailed in <xref linkend="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"
@@ -777,17 +621,18 @@
</deployment>
</deployments>]]>
</programlisting>
- </para>
-
- </example>
-
- <para>Here is an example of a WSRP descriptor with registration data
and cache expiring every minute:
- </para>
-
- <example>
- <title>Example</title>
+ </para>
+ </example>
+
<para>
- <programlisting><![CDATA[
+ Here is an example of a WSRP descriptor with registration data and
cache expiring every minute:
+ </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"
@@ -806,565 +651,530 @@
</wsrp-producer>
</deployment>
</deployments>]]></programlisting>
- </para>
- </example>
+ </para>
+ </example>
+ </section>
</section>
- </section>
-
- <section>
- <title>Adding remote portlets to categories</title>
- <para>
- If we 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 fileref="images/WSRP/remote_portlets.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
- </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
fileref="images/WSRP/remote_portlets_category.png" format="PNG"
align="center"
- valign="middle"
- scalefit="1"/>
- </imageobject>
- </mediaobject>
- </para>
- </section>
- </section>
-
- <section>
- <title>Consumers maintenance</title>
-
- <section>
- <title>Modifying a currently held registration</title>
-
+
<section>
- <title>Registration modification for service upgrade</title>
+ <title>Adding remote portlets to categories</title>
+
<para>
- Producers often offer several levels of service depending on
consumers' subscription levels (for
- example). This is implemented at the WSRP level with the registration
concept: producers can assert which
- level of service to provide to consumers based on the values of given
registration properties.
- </para>
- <para>
- There might also be cases where you just want to update the registration
information because it has
- changed. For example, the producer required you to provide a valid email
and the previously email
- address is not valid anymore and needs to be updated.
- </para>
- <para>
- It is therefore sometimes necessary to modify the registration that
concretizes the service agreement
- between a consumer and a producer. Let's take the example of 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 we would like to update the email address that we
provided to the remote producer when
- we first registered. We will need to tell the producer that our
registration data has been modified.
- Let's see how to do this. 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>foo(a)example.com</literal>, change its value in the
field for the
- <literal>email</literal>
- registration property:
+ If we 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 fileref="images/WSRP/modify_reg_start.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
+ <imagedata fileref="images/WSRP/remote_portlets.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
</imageobject>
</mediaobject>
- Now click on "Update properties" to save the change. A
"Modify registration" button should now appear to
- let you send this new data to the remote producer:
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/modify_reg_modify.png"
format="PNG" align="center"
- valign="middle" scalefit="1"/>
- </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 fileref="images/WSRP/modify_reg_end.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
- </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 Enterprise Portal Platform will attempt to help you in
this situation. Let's walk through an example using
- the <literal>selfv2</literal> consumer. Let's assume 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:
+ 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 fileref="images/WSRP/config_self.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
+ <imagedata
fileref="images/WSRP/remote_portlets_category.png" format="PNG"
align="center"
+ valign="middle"
+ scalefit="1"/>
</imageobject>
</mediaobject>
-
- Now suppose that the administrator of the producer now additionaly
requires a value to be provided for a
- <literal>name</literal>
- registration property. We will actually see how to do perform this
operation
- in JBoss Enterprise Portal Platform when we examine how to configure JBoss
Enterprise Portal Platform's producer in
- <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 "Refresh & Save":
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/modify_reg_self.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
- </imageobject>
- </mediaobject>
-
- As you can see, the configuration screen now shows the currently held
registration information and
- the expected information from the producer. Enter a value for the
- <literal>name</literal>
- property
- and then click on "Modify registration". If all went well and
the producer accepted your new registration
- data, you should see something similar to:
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/WSRP/modify_reg_self_end.png" format="PNG"
align="center"
- valign="middle" scalefit="1"/>
- </imageobject>
- </mediaobject>
-
- <note>
- <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 didn't quite happen as expected during a
method invocation. This means that
- <exceptionname>OperationFailedFault</exceptionname>
- can be caused by several different reasons, one
- of them being a request to modify the registration data. Please take
a look at the log files to see
- if you can gather more information as to what happened. WSRP 2
introduces an exception that is
- specific to a request to modify registrations thus reducing the
ambiguity that exists when using WSRP 1.
- </para>
-
- </note>
</para>
</section>
</section>
-
+
<section>
- <title>Consumer operations</title>
+ <title>Adding remote portlets to pages</title>
+
<para>
- Several operations are available from the consumer list view of the WSRP
configuration portlet:
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/consumer_operations.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
- </imageobject>
- </mediaobject>
+ 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>
- The available operations are:
- <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'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>
+ Of note, though, is that, starting with version 3.2 of GateIn (5.2 of EPP),
it is now possible to also add a remote portlet to a
<filename>pages.xml</filename> configuration file. This is accomplished using
the <literal><wsrp></literal> element instead of the
<literal><portlet></literal> element in your
<filename>pages.xml</filename> document. While
<literal><portlet></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><wsrp></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,
we recommend that you use the graphical user interface to add remote portlets to pages
instead of using <filename>pages.xml</filename>.
+ </para>
+
<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.
+ For remote portlets published by JBoss Enterprise Portal Platform's
WSRP producer, the portlet handles are, at the time of this writing, following the
<literal>/<portlet application name>.<portlet
name></literal> format.
</para>
</note>
- </section>
+
+ <section>
+ <title>Example</title>
+
+ <para>
+ In the following example, we define 2 portlets for a page named
<literal>Test</literal> in our <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 Enterprise Portal Platform's WSRP producer. You can see
that the first one is local (the
<code><portlet-application></code> with the
'<literal>Added locally</literal>' title) and follows the usual
declaration. The second portlet (the one with the '<literal>Added from selfv2
consumer</literal>' title) comes from the <literal>selfv2</literal>
consumer and uses the <code><wsrp></code> element instead of
<code><portlet></code> element and follows the format for
portlets coming from the JBoss Enterprise Portal Platform's WSRP producer.
+ </para>
+
+ <example>
+ <title>Example</title>
+ <para>
+<programlisting><![CDATA[
+<page>
+ <name>Test</name>
- <section>
- <title>Importing and exporting portlets</title>
- <para>Import and export are new functionalities 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 Enterprise Portal Platform
- does not currently support automated migration of portal data, the
functionality that we provide 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 Enterprise Portal Platform
(available since 3.1) 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's pages. Let us walk
- through an example to make things clearer.
- </para>
- <para>Clicking on the "Export" 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 fileref="images/WSRP/export_portlet_list.png"
format="PNG" align="center" valign="middle"/>
- </imageobject>
- </mediaobject>
- <para>Once portlets have been selected, they can be exported by clicking
on the "Export" button thus making
- them available for later import:
- </para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/export_done.png"
format="PNG" align="center" valign="middle"/>
- </imageobject>
- </mediaobject>
- <para>You can re-import the portlets directly by pressing the "Use
for import" button or, on the Consumers list
- page, using the "Import" action for a given consumer. Let's
assume 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 fileref="images/WSRP/export_list.png"
format="PNG" align="center" valign="middle"/>
- </imageobject>
- </mediaobject>
- <para>As you can see this screen presents the list of available exports
with available operations for each.
- <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>
- <para>Once you've selected an export to import from, you will see a
screen similar to the one below:</para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/import_start.png"
format="PNG" align="center" valign="middle"/>
- </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. Let's
- assume in this example 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 fileref="images/WSRP/import_original_page.png"
format="PNG" align="center" valign="middle"/>
- </imageobject>
- </mediaobject>
- <para>In this example, we 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 we previously exported. To do so, we will check the checkbox
next to the
- <literal>/ajaxPortlet.JSFAJAXPortlet</literal>
- portlet name to indicate that we 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 fileref="images/WSRP/import_selected_page.png"
format="PNG" align="center" valign="middle"/>
- </imageobject>
- </mediaobject>
- <para>Note that, at this point, we still need to select the window which
content we want to replace before
- being able to complete the import operation. Let's select the
- <literal>/samples-remotecontroller-portlet.RemoteControl
(remote)</literal>
- window, at which point the "Import" button will become enabled,
indicating that we 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 fileref="images/WSRP/import_success.png"
format="PNG" align="center" valign="middle"/>
- </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 fileref="images/WSRP/import_modified_page.png"
format="PNG" align="center" valign="middle"/>
- </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
- deregister first. This is the case when a consumer is registered with a
producer that has been modified by
- its administrator to not require registration anymore. If that ever was to
happen (most likely, it won't),
- you can erase the local registration information from the consumer so that it
can resume interacting with
- the remote producer. To do so, click on "Erase local registration"
button next to the registration context
- information on the consumer configuration screen:
- </para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/WSRP/erase_registration.png"
format="PNG" align="center" valign="middle"/>
- </imageobject>
- </mediaobject>
- <para>
- <emphasis>Warning:</emphasis>
- 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
fileref="images/WSRP/erase_registration_warning.png" format="PNG"
align="center"
- valign="middle"/>
- </imageobject>
- </mediaobject>
- </section>
- </section>
+ <portlet-application>
+ <portlet>
+ <application-ref>richFacesPortlet</application-ref>
+ <portlet-ref>richFacesPortlet</portlet-ref>
+ </portlet>
+ <title>Added locally</title>
- <section id="producer_config">
- <title>Configuring JBoss Enterprise Portal Platform's WSRP
Producer</title>
+ ...
+
+ </portlet-application>
+
+ <portlet-application>
+ <wsrp>selfv2./richFacesPortlet.richFacesPortlet</wsrp>
+ <title>Added from selfv2 consumer</title>
+
+ ...
+
+ </portlet-application>
+</page>]]></programlisting>
+ </para>
+ </example>
+ </section>
+ </section>
+
<section>
- <title>Overview</title>
- <para>
- The preferred way to configure the behavior of Portal's WSRP Producer is
via the WSRP configuration portlet.
- Alternatively, it is possible to add an XML file called
- <filename>wsrp-producer-config.xml</filename>
- in the
- <filename>$JBOSS_PROFILE_HOME/conf/gatein/</filename>
- directory.
- Several aspects can be modified with respects to whether registration is
required for consumers to access
- the Producer's services.
- <note>
- <para>An XML Schema defining which elements are available to
configure Consumers via XML can be found
- in
- <filename>
-
$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_producer_1_0.xsd
- </filename>
+ <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' 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>
- </note>
- <important>
+
<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 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.
+ 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>
- </important>
+
+ <para>
+ It is therefore sometimes necessary to modify the registration that
concretizes the service agreement between a consumer and a producer. Let's take the
example of 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 we would like to update the email address that we
provided to the remote producer when we first registered. We will need to tell the
producer that our registration data has been modified. Let's see how to do this.
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>foo(a)example.com</literal>, change its value in the field for the
<literal>email</literal> registration property:
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/WSRP/modify_reg_start.png" format="PNG"
align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ Now click on "Update properties" to save the change. A
"Modify registration" button should now appear to let you send this new data to
the remote producer:
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/WSRP/modify_reg_modify.png" format="PNG"
align="center"
+ valign="middle" scalefit="1"/>
+ </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 fileref="images/WSRP/modify_reg_end.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </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 Enterprise Portal Platform will attempt to
help you in this situation. Let's walk through an example using the
<literal>selfv2</literal> consumer. Let's assume 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:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_self.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ Now suppose that the administrator of the producer now additionaly
requires a value to be provided for a <literal>name</literal> registration
property. We will actually see how to do perform this operation in JBoss Enterprise Portal
Platform when we examine how to configure JBoss Enterprise Portal Platform's producer
in <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 "Refresh & Save":
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/modify_reg_self.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ As you can see, the configuration screen now shows the currently held
registration information and the expected information from the producer. Enter a value for
the <literal>name</literal> property and then click on "Modify
registration". If all went well and the producer accepted your new registration data,
you should see something similar to:
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/WSRP/modify_reg_self_end.png" format="PNG"
align="center"
+ valign="middle" scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+
+ <note>
+ <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 didn't quite happen as expected during a method invocation. This means that
+ <exceptionname>
+ OperationFailedFault
+ </exceptionname>
+ can be caused by several different reasons, one of them being a
request to modify the registration data. Please take a look at the log files to see if you
can gather more information as to what happened. WSRP 2 introduces an exception that is
specific to a request to modify registrations thus reducing the ambiguity that exists when
using WSRP 1.
+ </para>
+ </note>
+ </para>
+ </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
fileref="images/WSRP/consumer_operations.png" format="PNG"
align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+
+ <para>
+ The available operations are:
+ <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'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>
+ </para>
+
<note>
<para>
- The default configuration file for the producer can be found at
-
<filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-producer-config.xml</filename>
+ 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>
- </para>
- </section>
- <section>
- <title>Default configuration</title>
- <para>
- The default producer configuration is to require that consumers register with
it before providing access its
- services but does not require any specific registration properties (apart
from what is mandated by the
- WSRP standard). It does, however, require consumers to be registered before
sending them a full service
- description. This means that our WSRP producer will not provide the list of
offered portlets and other
- capabilities to unregistered consumers. The producer also uses the default
- <classname>RegistrationPolicy</classname>
- paired with the default
- <classname>RegistrationPropertyValidator</classname>. We will
look into property
- validators in greater detail later in<xref
linkend="registration-configuration"/>. Suffice to say for now
- that this allows users to customize how Portal's WSRP Producer decides
whether a given registration property
- is valid or not.
- </para>
- <para>
- JBoss Enterprise Portal Platform provides a web interface to configure the
producer's behavior. You can access it
- by clicking on the "Producer Configuration" tab of the
"WSRP" page of the "admin" portal. Here's what you
- should see with the default configuration:
+ </section>
+
+ <section>
+ <title>Importing and exporting portlets</title>
+
+ <para>
+ Import and export are new functionalities 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 Enterprise Portal Platform does
not currently support automated migration of portal data, the functionality that we
provide 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 Enterprise Portal Platform
(available since 3.1) 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's pages. Let us walk through an example to make things clearer.
+ </para>
+
+ <para>
+ Clicking on the "Export" 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 fileref="images/WSRP/producer_default.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
+ <imagedata fileref="images/WSRP/export_portlet_list.png"
format="PNG" align="center" valign="middle"/>
</imageobject>
</mediaobject>
- As would be expected, you can specify whether or not the producer will send
the full service description to
- unregistered consumers, and, if it requires registration, which
- <classname>RegistrationPolicy</classname>
- to use (and, if needed, which
- <classname>RegistrationPropertyValidator</classname>), along with
required
- registration property description for which consumers must provide acceptable
values to successfully
- register.
- </para>
- <para>New in JBoss Enterprise Portal Platform, we now display the WSDL
URLs to access JBoss Enterprise Portal Platform's WSRP producer 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's producer before
interacting with it, you need to
- configure Portal's behavior with respect to registration. Registration is
optional, as are registration
- properties. The producer can require registration without requiring consumers
to pass any registration
- properties as is the case in the default configuration. Let's configure
our producer starting with a blank
- state:
+
+ <para>
+ Once portlets have been selected, they can be exported by clicking on the
"Export" button thus making them available for later import:
+ </para>
+
<mediaobject>
<imageobject>
- <imagedata fileref="images/WSRP/producer_blank.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
+ <imagedata fileref="images/WSRP/export_done.png"
format="PNG" align="center" valign="middle"/>
</imageobject>
</mediaobject>
- We will allow unregistered consumers to see the list of offered portlets so
we leave the first checkbox
- ("Access to full service description requires consumers to be
registered.") unchecked. We will, however,
- specify that consumers will need to be registered to be able to interact with
our producer. Check the second
- checkbox ("Requires registration. Modifying this information will
trigger invalidation of consumer
- registrations."). The screen should now refresh and display:
+
+ <para>
+ You can re-import the portlets directly by pressing the "Use for
import" button or, on the Consumers list page, using the "Import" action
for a given consumer. Let's assume 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 fileref="images/WSRP/producer_registration.png"
format="PNG" align="center"
- valign="middle" scalefit="1"/>
+ <imagedata fileref="images/WSRP/export_list.png"
format="PNG" align="center" valign="middle"/>
</imageobject>
</mediaobject>
- You can specify the fully-qualified name for your
- <classname>RegistrationPolicy</classname>
- and
- <classname>RegistrationPropertyValidator</classname>
- there. We will keep the default value. See
- <xref linkend="custom_registration"/>
- for more details. Let's add, however, a registration property called
- <literal>email</literal>. Click "Add property" and
enter the appropriate information in the fields,
- providing a description for the registration property that can be used by
consumers to figure out its
- purpose:
+
+ <para>
+ As you can see this screen presents the list of available exports with
available operations for each.
+ <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>
+
+ <para>
+ Once you've selected an export to import from, you will see a screen
similar to the one below:
+ </para>
+
<mediaobject>
<imageobject>
- <imagedata fileref="images/WSRP/producer_email.png"
format="PNG" align="center" valign="middle"
- scalefit="1"/>
+ <imagedata fileref="images/WSRP/import_start.png"
format="PNG" align="center" valign="middle"/>
</imageobject>
</mediaobject>
- Press "Save" to record your modifications.
-
- <note>
- <para>At this time, only String (xsd:string) properties are
supported. If your application requires more
- complex properties, please let us know.
- </para>
- </note>
-
- <note>
- <para>If consumers are already registered with the producer,
modifying the configuration of required
- registration
- information will trigger the invalidation of held registrations,
requiring consumers to modify their
- registration before being able to access the producer again. We saw the
consumer side of that process
- in
- <xref linkend="reg_mod_error"/>.
- </para>
-
- </note>
- </para>
-
- <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'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.
+ 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. Let's assume in
this example 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 fileref="images/WSRP/import_original_page.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+
<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.
+ In this example, we 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
we previously exported. To do so, we will check the checkbox next to the
<literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet name to indicate that
we 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 fileref="images/WSRP/import_selected_page.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+
<para>
- Please refer to the
- <trademark class="trade">Javadoc</trademark>
- for
-
<classname>org.gatein.registration.RegistrationPolicy</classname>
- and
-
<classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname>
- for more
- details on what is expected of each method.
+ Note that, at this point, we still need to select the window which content
we want to replace before being able to complete the import operation. Let's select
the <literal>/samples-remotecontroller-portlet.RemoteControl
(remote)</literal> window, at which point the "Import" button will become
enabled, indicating that we 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>
- <para>Defining a registration policy is required for the producer to be
correctly configured. This is
- accomplished by specifying the qualified class name of the registration
policy. Since we anticipate that
- most users will use the default registration policy, it is possible to
provide the class
- name of your custom property validator instead to customize the default
registration policy behavior.
- Note that property validators are only used by the default policy.
-
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/import_success.png"
format="PNG" align="center" valign="middle"/>
+ </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 fileref="images/WSRP/import_modified_page.png"
format="PNG" align="center" valign="middle"/>
+ </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 deregister first. This is the case when a consumer is
registered with a producer that has been modified by its administrator to not require
registration anymore. If that ever was to happen (most likely, it won't), you can
erase the local registration information from the consumer so that it can resume
interacting with the remote producer. To do so, click on "Erase local
registration" button next to the registration context information on the consumer
configuration screen:
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/erase_registration.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ <emphasis>Warning:</emphasis> 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
fileref="images/WSRP/erase_registration_warning.png" format="PNG"
align="center"
+ valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+ </section>
+
+ <section id="producer_config">
+ <title>Configuring JBoss Enterprise Portal Platform's WSRP
Producer</title>
+
+ <section>
+ <title>Overview</title>
+
+ <para>
+ The preferred way to configure the behavior of Portal's WSRP Producer
is via the WSRP configuration portlet. Alternatively, it is possible to add an XML file
called <filename>wsrp-producer-config.xml</filename> in the
<filename>$JBOSS_PROFILE_HOME/conf/gatein/</filename> directory. Several
aspects can be modified with respects to whether registration is required for consumers to
access the Producer's services.
<note>
- <para>Since the policy or the validator are defined via their
class name and dynamically loaded, it is
- important that you make sure that the identified class is available
to the application server. One
- way
- to accomplish that is to deploy your policy implementation as JAR
file in your AS instance deploy
- directory. Note also that, since both policies and validators are
dynamically instantiated, they
- must
- provide a default, no-argument constructor.
+ <para>
+ An XML Schema defining which elements are available to configure
Consumers via XML can be found in <filename>
$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_producer_1_0.xsd
</filename>
</para>
</note>
+
+ <important>
+ <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 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>
+
+ <note>
+ <para>
+ The default configuration file for the producer can be found at
<filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-producer-config.xml</filename>
+ </para>
+ </note>
</para>
</section>
+
+ <section>
+ <title>Default configuration</title>
+
+ <para>
+ The default producer configuration is to require that consumers register
with it before providing access its services but does not require any specific
registration properties (apart from what is mandated by the WSRP standard). It does,
however, require consumers to be registered before sending them a full service
description. This means that our WSRP producer will not provide the list of offered
portlets and other capabilities to unregistered consumers. The producer also uses the
default <classname>RegistrationPolicy</classname> paired with the default
<classname>RegistrationPropertyValidator</classname>. We will look into
property validators in greater detail later in<xref
linkend="registration-configuration"/>. Suffice to say for now that this
allows users to customize how Portal's WSRP Producer decides whether a given
registration property is valid or not.
+ </para>
+
+ <para>
+ JBoss Enterprise Portal Platform provides a web interface to configure the
producer's behavior. You can access it by clicking on the "Producer
Configuration" tab of the "WSRP" page of the "admin" portal.
Here's what you should see with the default configuration:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/producer_default.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ As would be expected, you can specify whether or not the producer will
send the full service description to unregistered consumers, and, if it requires
registration, which <classname>RegistrationPolicy</classname> to use (and, if
needed, which <classname>RegistrationPropertyValidator</classname>), along
with required registration property description for which consumers must provide
acceptable values to successfully register.
+ </para>
+
+ <para>
+ New in JBoss Enterprise Portal Platform, we now display the WSDL URLs to
access JBoss Enterprise Portal Platform's WSRP producer 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's producer
before interacting with it, you need to configure Portal's behavior with respect to
registration. Registration is optional, as are registration properties. The producer can
require registration without requiring consumers to pass any registration properties as is
the case in the default configuration. Let's configure our producer starting with a
blank state:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/producer_blank.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ We will allow unregistered consumers to see the list of offered portlets
so we leave the first checkbox ("Access to full service description requires
consumers to be registered.") unchecked. We will, however, specify that consumers
will need to be registered to be able to interact with our producer. Check the second
checkbox ("Requires registration. Modifying this information will trigger
invalidation of consumer registrations."). The screen should now refresh and display:
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/WSRP/producer_registration.png" format="PNG"
align="center"
+ valign="middle" scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ You can specify the fully-qualified name for your
<classname>RegistrationPolicy</classname> and
<classname>RegistrationPropertyValidator</classname> there. We will keep the
default value. See <xref linkend="custom_registration"/> for more details.
Let's add, however, a registration property called
<literal>email</literal>. Click "Add property" and enter the
appropriate information in the fields, providing a description for the registration
property that can be used by consumers to figure out its purpose:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/producer_email.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ Press "Save" to record your modifications.
+ <note>
+ <para>
+ At this time, only String (xsd:string) properties are supported. If
your application requires more complex properties, please let us know.
+ </para>
+ </note>
+
+ <note>
+ <para>
+ If consumers are already registered with the producer, modifying the
configuration of required registration information will trigger the invalidation of held
registrations, requiring consumers to modify their registration before being able to
access the producer again. We saw the consumer side of that process in <xref
linkend="reg_mod_error"/>.
+ </para>
+ </note>
+ </para>
+
+ <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'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.
+ </para>
+
+ <para>
+ Please refer to the <trademark
class="trade">Javadoc</trademark> for
<classname>org.gatein.registration.RegistrationPolicy</classname> and
<classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname>
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. This is accomplished by specifying the qualified class name of the
registration policy. Since we anticipate that most users will use the default registration
policy, it is possible to provide the class name of your custom property validator instead
to customize the default registration policy behavior. Note that property validators are
only used by the default policy.
+ <note>
+ <para>
+ Since the policy or the validator are defined via their class
name and dynamically loaded, it is important that you make sure that the identified class
is available to the application server. One way to accomplish that is to deploy your
policy implementation as JAR file in your AS instance deploy directory. Note also that,
since both policies and validators are dynamically instantiated, they must provide a
default, no-argument constructor.
+ </para>
+ </note>
+ </para>
+ </section>
+ </section>
+
+ <section id="strict-mode">
+ <title>WSRP validation mode</title>
+
+ <para>
+ The lack of conformance kit and the wording of the WSRP specification
leaves room for differing interpretations, resulting in interoperability issues. It is
therefore possible to encounter issues when using consumers from different vendors. We
have experienced such issues and have introduced a way to relax the validation that our
WSRP producer performs on the data provided by consumers to help with interoperability by
accepting data that would normally be invalid. Note that we only relax our validation
algorithm on aspects of the specification that are deemed harmless such as invalid
language codes.
+ </para>
+
+ <para>
+ By default, the WSRP producer is configured in strict mode. If you
experience issues with a given consumer, you might want to try to relax the validation
mode. This is accomplished by unchecking the "Use strict WSRP compliance."
checkbox on the Producer configuration screen.
+ </para>
+ </section>
</section>
- <section id="strict-mode">
- <title>WSRP validation mode</title>
- <para>The lack of conformance kit and the wording of the WSRP
specification leaves room for differing
- interpretations, resulting in interoperability issues. It is therefore
possible to encounter issues when
- using consumers from different vendors. We have experienced such issues and
have introduced a way to relax
- the validation that our WSRP producer performs on the data provided by
consumers to help with
- interoperability by accepting data that would normally be invalid. Note that
we only relax our validation
- algorithm on aspects of the specification that are deemed harmless such as
invalid language codes.
- </para>
- <para>
- By default, the WSRP producer is configured in strict mode. If you experience
issues with a given consumer,
- you might want to try to relax the validation mode. This is accomplished by
unchecking the "Use strict WSRP
- compliance." checkbox on the Producer configuration screen.
- </para>
- </section>
-
- </section>
-</chapter>
+ </chapter>