[portal-commits] JBoss Portal SVN: r7333 - docs/trunk/referenceGuide/en/modules.

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">&lt;endpoint-wsdl-url&gt;</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">&lt;registration-data&gt;</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">&lt;registration-datat&gt;</emphasis> element. Values for the registration properties + <emphasis role="bold">&lt;registration-data&gt;</emphasis> element. Values for the registration properties required by the remote producer can be provided via <emphasis role="bold">&lt;property&gt;</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">&lt;consumer-name&gt;</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>