Author: chris.laprun(a)jboss.com
Date: 2007-05-25 00:32:24 -0400 (Fri, 25 May 2007)
New Revision: 7333
Modified:
docs/trunk/referenceGuide/en/modules/wsrp.xml
Log:
- Added information on level of support of WSRP 1.0 spec.
- Added information on processing of Producer descriptors.
- Started adding info about configuration portlet.
- Need to update graphics.
Modified: docs/trunk/referenceGuide/en/modules/wsrp.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/wsrp.xml 2007-05-25 02:37:52 UTC (rev 7332)
+++ docs/trunk/referenceGuide/en/modules/wsrp.xml 2007-05-25 04:32:24 UTC (rev 7333)
@@ -39,6 +39,33 @@
</sect1>
<sect1>
+ <title>Level of support in JBoss Portal</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 Portal 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 Portal provides a Medium level of support
for WSRP, except that we only handle
+ HTML markup (as Portal 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 Portal 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>
+ </sect1>
+
+ <sect1>
<title>Deploying JBoss Portal's WSRP services</title>
<para>JBoss Portal provides a complete support of WSRP 1.0 standard
interfaces and offers
both consumer and producer services. WSRP support is provided by the
<emphasis>portal-wsrp.sar</emphasis>
@@ -62,7 +89,7 @@
WS (bundled with JBoss Application Server 4.0.4.GA) that prevents the complete
deployment of JBoss
Portal's WSRP service if the user is not online or behind a firewall/proxy.
For this reason, we recommend
that you deploy Portal on JBoss Application Server 4.0.5.GA. Alternatively, you
can also perform a manual
- upgrade of JBoss WS, in which case we recommend that you use JBoss WS version
1.0.4.GA (and later).
+ upgrade of JBoss WS, in which case we recommend that you use JBoss WS version
1.2.1.GA (and later).
Please follow the instructions on
<ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WSRP_UpdateJBossWS&quo... to
upgrade JBoss WS</ulink>
as found on <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossPortal">J... Portal's
wiki</ulink>.
@@ -72,8 +99,9 @@
<sect2 id="wsrp-ports">
<title>Considerations to use WSRP when running Portal on a non-default
port</title>
<para>If you have modified the port number on which Portal runs, you will
also need
- <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WSRPChangePorts"&... the
port information for WSRP</ulink>
- as found on <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossPortal">J... Portal's
wiki</ulink>.
+ <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WSRPChangePorts"&... the
port information for
+ WSRP</ulink> as found on <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossPortal">J...
Portal's
+ wiki</ulink>.
</para>
</sect2>
@@ -89,10 +117,10 @@
<sect1>
<title>Making a portlet remotable</title>
- <para>JBoss Portal does not, by default, expose local portlets for
consumption by remote WSRP consumers. In order
- to make a portlet remotely available, it must be made "remotable" by
adding a <emphasis>remotable</emphasis>
- element to the <emphasis>jboss-portlet.xml</emphasis> deployment
descriptor for that portlet. If a
- <emphasis>jboss-portlet.xml</emphasis> file does not exist, one must
be added to the
+ <para>JBoss Portal 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 adding a
+ <emphasis>remotable</emphasis> element to the
<emphasis>jboss-portlet.xml</emphasis> deployment descriptor for
+ that portlet. If a <emphasis>jboss-portlet.xml</emphasis> file does
not exist, one must be added to the
<emphasis>WEB-INF</emphasis> folder of the web application
containing the portlet.
</para>
<para>In the following example, the "BasicPortlet" portlet is
specified as being remotable. The
@@ -101,9 +129,7 @@
<para>
<programlisting><![CDATA[
<?xml version="1.0" standalone="yes"?>
-<!DOCTYPE portlet-app PUBLIC
- "-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
- "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd">
+<!DOCTYPE portlet-app PUBLIC "-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
"http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd">
<portlet-app>
<portlet>
<portlet-name>BasicPortlet</portlet-name>
@@ -113,7 +139,8 @@
</para>
<para>
It is also possible to specify that all the portlets declared within a given
<emphasis>jboss-portlet.xml</emphasis>
- file have a specific "remotable" status by default. Usually, this
feature will be used to remotely expose
+ file have a specific "remotable" status by default. This is done by
adding a single <emphasis>remotable</emphasis>
+ element to the root <emphasis>portlet-app</emphasis> element.
Usually, this feature will be used to remotely expose
several portlets without having to specify the status for all the declared
portlets. Let's look at an example:
</para>
<para>
@@ -154,7 +181,8 @@
<title>Consuming JBoss Portal's WSRP portlets from a remote
Consumer</title>
<para>WSRP Consumers vary a lot as far as how they are configured. Most of
them require that you either specify
the URL for the Producer's WSDL definition or the URLs for the individual
endpoints. Please refer to your
- Consumer's documentation for specific instructions.
+ Consumer's documentation for specific instructions. For instructions on how
to do so in JBoss Portal, please
+ refer to <xref linkend="#consumer_configuration"/>.
</para>
<para>
JBoss Portal's Producer is automatically set up when you deploy a portal
instance with the WSRP service.
@@ -170,20 +198,18 @@
</para>
</sect1>
- <sect1>
+ <sect1 id="consumer_configuration">
<title>Consuming remote WSRP portlets in JBoss Portal</title>
<sect2>
<title>Overview</title>
<para>
To be able to consume WSRP portlets exposed by a remote producer, JBoss
Portal's WSRP consumer needs to know
- how to access that remote producer. One can configure access to a remote
producer via
- <emphasis>*-wsrp.xml</emphasis> descriptors. These files can be
dropped in the deploy directory of the JBoss
- application server or nested in .sar files. It is possible to configure
access to several different
- producers within a single <emphasis>-wsrp.xml</emphasis> file or
use one file per producer.
+ how to access that remote producer. One can configure access to a remote
producer using WSRP Producer
+ descriptors. Alternatively, a portlet is provided to configure remote
producers.
</para>
<para>
- Once a remote producer has been configured in a
<emphasis>-wsrp.xml</emphasis> file, it becomes available
- in the list of portlet provider in the Management portlet on the Admin page
of JBoss Portal. You can then
+ Once a remote producer has been configured, it can be made available
+ in the list of portlet providers in the Management portlet on the Admin page
of JBoss Portal. You can then
examine the list of portlets that are exposed by this producer and configure
the portlets just like you
would for local portlets.
</para>
@@ -194,16 +220,28 @@
identifier in the portlet providers list in the Management portlet of the
Admin page. All local portlets
marked as remotable are exposed as remote portlets via the
<emphasis>self</emphasis> portlet
provider so that you can check that they work as expected with WSRP. The
<emphasis>portal-wsrp.sar</emphasis>
- file contains a <emphasis>default-wsrp.xml</emphasis> that
configures this default producer. This file can
- be edited or removed if needed.
+ file contains a WSRP Producer descriptor
(<emphasis>default-wsrp.xml</emphasis>) that configures this
+ default producer. This file can be edited or removed if needed.
</para>
+ </sect2>
+
+ <sect2>
+ <title>Configuring a remote producer walk-through</title>
<para>
Let's work through the steps of defining access to a remote producer so
that its portlets can be
- consumed within JBoss Portal. We will configure access to BEA's public
WSRP producer. To do so, you will
- need to create a <emphasis>-wsrp.xml</emphasis> file (which we
will call here
- <emphasis>public-bea-wsrp.xml</emphasis> but the name does not
matter as long as it ends with
- <emphasis>-wsrp.xml</emphasis>) as follows:
+ consumed within JBoss Portal. We will configure access to BEA's public
WSRP producer. We will first examine
+ how to do so using an XML descriptor then see how the same can be
accomplished using the configuration
+ portlet.
+ </para>
+
+ <sect3>
+ <title>Using a WSRP Producer XML descriptor</title>
+
+ <para>We will create a
<emphasis>public-bea-wsrp.xml</emphasis> descriptor. Note that the actual name
does not
+ matter as long as it ends with
<emphasis>-wsrp.xml</emphasis>.
<programlisting><![CDATA[
+<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer
Configuration 2.6//EN"
+ "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">
<?xml version="1.0" standalone="yes"?>
<deployments>
<deployment>
@@ -222,12 +260,21 @@
This producer descriptor gives access to BEA's public WSRP producer. We
will look at the details of the
different elements later. Note for now the
<emphasis>producer-id</emphasis> element with a "bea" value. Put
this file in the deploy directory and start the server (with JBoss Portal and
its WSRP service deployed).
- </para>
- <para>
+ </para></sect3>
+
+ <sect3>
+ <title>Using the configuration portlet</title>
+ <para>TODO</para>
+ </sect3>
+
+ <sect3>
+ <title>Configuring access to a remote portlet</title>
+ <para>
Let's now look at the Admin page and the Management portlet. Click on the
"Portlets" link at the top to
manage the portlets. Once this is done, look at the list of available portlet
providers. If all went well,
you should see something similar to this:
+ TODO: update image
<mediaobject>
<imageobject>
<imagedata fileref="images/wsrp/portlets.png"
format="png" align="center" valign="middle"/>
@@ -241,6 +288,7 @@
the portlets exposed by the default WSRP producer. The "bea"
provider corresponds to BEA's public producer
we just configured. Select it and click on "Change portlet
provider". You should now see something similar to:
+ TODO: update image
<mediaobject>
<imageobject>
<imagedata fileref="images/wsrp/bea.png"
format="png" align="center" valign="middle"/>
@@ -248,20 +296,46 @@
</mediaobject>
</para>
<para>
- From there on out, you should be able to configure WSRP portlets just as any
other. In particular, you
+ From there on out, you should be able to configure WSRP portlets just as any
other. In particular, you
can create an instance of one of the remote portlets offered by BEA's public
producer just like you would
create an instance of a local portlet and then assign it to a window in a page. If you
go to that page, you
should see something similar to below for this portlet:
+ TODO: update image
<mediaobject>
<imageobject>
<imagedata fileref="images/wsrp/result.png"
format="png" align="center" valign="middle"/>
</imageobject>
</mediaobject>
</para>
+ </sect3>
</sect2>
<sect2>
+ <title>WSRP Producer descriptors</title>
+
+ <para>
+ A WSRP Producer descriptor is an XML file which name ends in
<emphasis>-wsrp.xml</emphasis> and
+ which can be dropped in the deploy directory of the JBoss application server
or nested in .sar files. It is
+ possible to configure access to several different producers within a single
descriptor or use one file per
+ producer, depending on your needs. The DTD for the WSRP Producer descriptor
format can be found at
+
<emphasis>portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd</emphasis>.
+ <note>It is important to note how WSRP Producer descriptors are
processed. They are read the first time the
+ WSRP service starts and the associated information is then put in the
Portal database. Subsequent launch
+ of the WSRP service will use the database-stored information for all
producers which identifier is
+ already known to Portal. More specifically, all the descriptors are
scanned for producer identifiers.
+ Any identifier that is already known will be bypassed and the
configuration associated with this remote
+ producer in the database will be used. If a producer identifier is found
that wasn't already in the
+ database, that producer information will be processed and recorded in the
database. Therefore, if you
+ wish to delete a producer configuration, you need to delete the associated
information in the database
+ (this can be accomplished using the configuration portlet as we shall see
in
+ <xref linkend="#consumer-gui"/>)
<emphasis>AND</emphasis> remove the associated information in any
+ WSRP Producer descriptor (if such information exists) as the producer will
be re-created the next time
+ the WSRP is launched if that information is not removed.
+ </note>
+ </para>
+
+ <sect3>
<title>Required configuration information</title>
<para>Let's now look at which information needs to be provided to
configure access to a remote producer.</para>
@@ -304,9 +378,9 @@
<emphasis
role="bold"><endpoint-wsdl-url></emphasis> elements
are required for a functional remote producer configuration.
</para>
- </sect2>
+ </sect3>
- <sect2>
+ <sect3>
<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.
@@ -326,7 +400,7 @@
<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 Portal consumer can register
with the remote
+ information in the producer configuration so that the Portal consumer can register
with the remote
producer when required.
<note>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.</note>
@@ -335,23 +409,56 @@
<para>Registration configuration is done via the <emphasis
role="bold"><registration-data></emphasis>
element. Since JBoss Portal can generate the mandatory information for you,
if the remote producer does not
require any registration properties, you only need to provide an empty
- <emphasis
role="bold"><registration-datat></emphasis> element.
Values for the registration properties
+ <emphasis
role="bold"><registration-data></emphasis> element.
Values for the registration properties
required by the remote producer can be provided via <emphasis
role="bold"><property></emphasis>
elements. See the example below for more details. Additionally, you can
override the default consumer name
automatically provided by JBoss Portal via the <emphasis
role="bold"><consumer-name></emphasis>
element. If you choose to provide a consumer name, please remember that this
should uniquely identify your
consumer.
</para>
+ </sect3>
</sect2>
-
<sect2>
<title>Examples</title>
+
+ <para>
+ Here is the configuration of the "self" producer as found in
<emphasis>default-wsrp.xml</emphasis> with a
+ cache expiring every five minutes:
+ </para>
+
+ <para>
+ <programlisting><![CDATA[
+<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer
Configuration 2.6//EN"
+ "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">
+<?xml version="1.0" encoding="UTF-8"?>
+<deployments>
+ <deployment>
+ <wsrp-producer id="self" expiration-cache="300">
+ <!--
+ we need to use the individual endpoint configuration because the configuration
via wsdl forces an
+ immediate attempt to access the web service description which is not available
yet at this point of deployment
+ -->
+ <endpoint-config>
+
<service-description-url>http://localhost:8080/portal-wsrp/ServiceDescriptionService</service-description-url>
+
<markup-url>http://localhost:8080/portal-wsrp/MarkupService</markup-url>
+
<registration-url>http://localhost:8080/portal-wsrp/RegistrationService</registration-url>
+
<portlet-management-url>http://localhost:8080/portal-wsrp/PortletManagementService</portlet-management-url>
+ </endpoint-config>
+ <registration-data/>
+ </wsrp-producer>
+ </deployment>
+</deployments>]]>
+ </programlisting>
+ </para>
+
<para>Here is an example of a WSRP descriptor with a 2 minute caching time
and manual definition of the endpoint
URLs:</para>
<para>
<programlisting><![CDATA[
+<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer
Configuration 2.6//EN"
+ "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">
<?xml version="1.0" encoding="UTF-8"?>
<deployments>
<deployment>
@@ -380,6 +487,8 @@
<para>
<programlisting><![CDATA[
+<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer
Configuration 2.6//EN"
+ "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">
<?xml version="1.0" encoding="UTF-8"?>
<deployments>
<deployment>
@@ -463,9 +572,9 @@
<para>
Registration handling behavior can be customized by users to suit their
Producer needs. This is
accomplished by providing an implementation of the <emphasis
role="bold">RegistrationPolicy</emphasis>
- interface. This interface defines behaviors that are called by
Portal's Registration service so that
+ 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
- behaviors is provided and should be enough for most user needs.
+ 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,
@@ -538,4 +647,4 @@
</para>
</sect2>
</sect1>
-</chapter>
+ </chapter>