[jboss-svn-commits] JBoss Portal SVN: r5556 - docs/branches/JBoss_Portal_Branch_2_4/referenceGuide/en/modules
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Nov 1 19:21:19 EST 2006
Author: chris.laprun at jboss.com
Date: 2006-11-01 19:21:18 -0500 (Wed, 01 Nov 2006)
New Revision: 5556
Modified:
docs/branches/JBoss_Portal_Branch_2_4/referenceGuide/en/modules/wsrp.xml
Log:
Updated documentation of consumer-name and registration data.
Modified: docs/branches/JBoss_Portal_Branch_2_4/referenceGuide/en/modules/wsrp.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_4/referenceGuide/en/modules/wsrp.xml 2006-11-02 00:21:01 UTC (rev 5555)
+++ docs/branches/JBoss_Portal_Branch_2_4/referenceGuide/en/modules/wsrp.xml 2006-11-02 00:21:18 UTC (rev 5556)
@@ -53,7 +53,7 @@
<note>
WSRP is built upon the JBoss WS web service stack. There is a known issue with the version 1.0.0.GA of JBoss
- WS bundled with JBoss Application Server 4.0.4.GA, issue which prevents the complete deployment of JBoss
+ 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. This has been addressed in
version 1.0.2.GA of JBoss WS. Please follow the instructions on
<ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WSRP_UpdateJBossWS">how to upgrade JBoss WS</ulink>
@@ -65,9 +65,14 @@
<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, a <emphasis>jboss-portlet.xml</emphasis> deployment descriptor
- for that portlet must be added to the <emphasis>WEB-INF</emphasis> folder of the web application containing
- the portlet and must be similar to the example below:</para>
+ 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
+ <emphasis>remotable</emphasis> element is optional.
+ </para>
<para>
<programlisting>
<![CDATA[
@@ -78,9 +83,6 @@
</portlet>]]>
</programlisting>
</para>
-
- <para>Here, the portlet named "BasicPortlet" is specified as being remotable. The "remotable" element is optional.</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
@@ -118,7 +120,7 @@
</sect1>
<sect1>
- <title>Accessing JBoss Portal's WSRP Producer from a remote Consumer</title>
+ <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.
</para>
@@ -137,25 +139,16 @@
<sect1>
<title>Consuming remote WSRP portlets in JBoss Portal</title>
-
<sect2>
<title>Overview</title>
<para>
- To be able to consume WSRP portlets from a remote producer, JBoss Portal's WSRP consumer needs to know
- how to access the remote producer. This is done via <emphasis>-wsrp.xml</emphasis> descriptors that
- provide JBoss Portal's consumer information about which remote producers to access and with which
- configuration. These files can be dropped in the deploy directory of the JBoss application server or nested
- in .sar files for examples. It is possible to configure access to several different producers within
- a single <emphasis>-wsrp.xml</emphasis> file or use one file per producer.
+ 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.
</para>
<para>
- JBoss Portal's producer exposes its information to the Portal itself as a default consumer with the
- identifier <emphasis>self</emphasis>. That means that all the remotable portlets
- are also exposed as remote portlets in the portal. The <emphasis>portal-wsrp.sar</emphasis> file contains the
- file <emphasis>default-wsrp.xml</emphasis> that contains this default producer. This file can be edited or
- removed if needed.
- </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
examine the list of portlets that are exposed by this producer and configure the portlets just like you
@@ -167,8 +160,21 @@
</note>
</para>
<para>
- Let's see how it works step by step. Let's create a <emphasis>public-bea-wsrp.xml</emphasis> file as
- follows:
+ JBoss Portal's default configuration exposes some of the sample portlets for remote consumption. As a way to
+ test the WSRP service, a default consumer has been configured to consume these portlets. To make sure that
+ the service indeed works, checks that there is a portlet provider with the <emphasis>self</emphasis>
+ identifier in the portlet providers list in the Management portlet of the Admin page. All local portlets
+ marked as remotable are therefore 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.
+ </para>
+ <para>
+ Let's see 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:
<programlisting>
<![CDATA[
<deployments>
@@ -178,7 +184,6 @@
<expiration-cache>120</expiration-cache>
<endpoint-wsdl-url>http://wsrp.bea.com:7001/producer/producer?WSDL</endpoint-wsdl-url>
<registration-data>
- <consumer-name>JBoss Portal 2.4 Test</consumer-name>
<property>
<name>registration/consumerRole</name>
<lang>en</lang>
@@ -194,7 +199,7 @@
this file in the deploy directory and start the server (with JBoss Portal and its WSRP service deployed).
</para>
<para>
- Let's now look at the Admin page and the management portlet. Click on the "Portlets" link at the top to
+ 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:
@@ -206,10 +211,10 @@
</para>
<para>
We have 3 available portlet providers: <emphasis>local, self</emphasis> and <emphasis>bea</emphasis>. The
- "local" portlet provider exposes all the portlets deployed in this particular instance of Portal. The
- "self" provider is the default WSRP consumer bundled with Portal that consumes 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:
+ "local" portlet provider exposes all the portlets deployed in this particular instance of Portal. As
+ explained above, the "self" provider refers to the default WSRP consumer bundled with Portal that consumes
+ 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:
<mediaobject>
<imageobject>
@@ -218,10 +223,10 @@
</mediaobject>
</para>
<para>
- From there on out, you should be able to configure the portlet just as any other, baring the restriction
- that the WSRP Portlet Management interface is not yet supported in 2.4. If everything went well, you
- created an instance of the portlet and assigned it to a window in a page. If you go to that page, you should
- see something similar to below for this portlet:
+ From there on out, you should be able to configure the portlet just as any other, barring the restriction
+ that the (optional) WSRP Portlet Management interface is not yet supported in 2.4. If everything went well,
+ you created an instance of the portlet and assigned it to a window in a page. If you go to that page, you
+ should see something similar to below for this portlet:
<mediaobject>
<imageobject>
@@ -234,19 +239,19 @@
<sect2>
<title>Required configuration information</title>
- <para>Let's look at which information needs to be provided to configure access to a remote producer.</para>
+ <para>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 via the <emphasis role="bold"><producer-id></emphasis> element.</para>
+ afterwards. This is accomplished via the <emphasis role="bold"><producer-id></emphasis> element.</para>
- <para>JBoss Portal also needs to learn about the remote producer's endpoints to be able to connect to the web services
- and perform the WSRP invocations. Two options are currently provided to inform JBoss Portal of how to connect
- to the remote web service, both by providing the required information via children elements:
+ <para>JBoss Portal also needs to learn about the remote producer's endpoints to be able to connect to the
+ remote web services and perform the WSRP invocations. Two options are currently supported to provide this
+ information:
</para>
<para>
<itemizedlist>
- <listitem>We can provide the URLs for each of the different WSRP interfaces offered by the remote
+ <listitem>You can provide the URLs for each of the different WSRP interfaces offered by the remote
producer via the <emphasis role="bold"><endpoint-config></emphasis> element and its
<emphasis role="bold"><service-description-url></emphasis>,
<emphasis role="bold"><markup-url></emphasis>, <emphasis
@@ -255,11 +260,11 @@
producer-specific so you will need to refer to your producer documentation or WSDL file to determine
the appropriate values.
</listitem>
- <listitem>Alternatively, and this is the easiest way to configure your producer, we can provide a URL pointing to the
- WSDL description of the WSRP web services offered by the producer via
- <emphasis role="bold"><endpoint-wsdl-url></emphasis>. JBoss Portal will then heuristically
- determine from the information contained in the WSDL file how to connect appropriately to the remote
- WSRP services.
+ <listitem>Alternatively, and this is the easiest way to configure your producer, you can provide a URL
+ pointing to the WSDL description of the producer's WSRP services. This is accomplished via the
+ <emphasis role="bold"><endpoint-wsdl-url></emphasis> element. JBoss Portal will then
+ heuristically determine, from the information contained in the WSDL file, how to connect appropriately
+ to the remote WSRP services.
<note>It is important to note that, when using this method, JBoss Portal will try to match a port
name to an interface based solely on the provided name. There are no standard names for these ports
so it is possible (though rare) that this matching process fails. In this case, you should look at
@@ -271,18 +276,22 @@
<para>Both <emphasis role="bold"><producer-id></emphasis> and either
<emphasis role="bold"><endpoint-config></emphasis> or
<emphasis role="bold"><endpoint-wsdl-url></emphasis>
- are required elements for a functional remote producer configuration.</para></sect2>
+ are required elements for a functional remote producer configuration.
+ </para>
+ </sect2>
<sect2>
<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>
+ establish a proper connection to the remote producer.
+ </para>
- <para>One such optional configuration is 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). Such information is refreshed periodically. The rate at which the information is refreshed
- is defined by the <emphasis role="bold"><expiration-cache></emphasis> element which specifies the
- refreshing period in seconds.</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 <emphasis role="bold"><expiration-cache></emphasis> element which specifies the
+ refreshing period in seconds.
+ </para>
<para>Additionally, some producers require consumers to register with them before authorizing them to access
their offered portlets. JBoss Portal currently only supports a very basic subset of in-band registration
@@ -293,10 +302,14 @@
</para>
<para>Registration configuration is done via the <emphasis role="bold"><registration-datat></emphasis>
- element. We need to provide a consumer name (via the <emphasis role="bold"><consumer-name></emphasis>
- element) for our consumer and then provide a list of values for the
- registration properties required by the remote producer via <emphasis role="bold"><property></emphasis>
- elements. See the example below for more details.
+ 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
+ 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>
</sect2>
@@ -309,21 +322,21 @@
<para>
<programlisting>
<![CDATA[
- <?xml version="1.0" encoding="UTF-8"?>
- <deployments>
- <deployment>
- <wsrp-producer>
- <producer-id>MyProducer</producer-id>
- <expiration-cache>120</expiration-cache>
- <endpoint-config>
- <service-description-url>http://www.someproducer.com/portal-wsrp/ServiceDescriptionService</service-description-url>
- <markup-url>http://www.someproducer.com/portal-wsrp/MarkupService</markup-url>
- <registration-url>http://www.someproducer.com/portal-wsrp/RegistrationService</registration-url>
- <portlet-management-url>http://www.someproducer.com/portal-wsrp/PortletManagementService</portlet-management-url>
- </endpoint-config>
- </wsrp-producer>
- <deployment>
- </deployments>]]>
+<?xml version="1.0" encoding="UTF-8"?>
+<deployments>
+ <deployment>
+ <wsrp-producer>
+ <producer-id>MyProducer</producer-id>
+ <expiration-cache>120</expiration-cache>
+ <endpoint-config>
+ <service-description-url>http://www.someproducer.com/portal-wsrp/ServiceDescriptionService</service-description-url>
+ <markup-url>http://www.someproducer.com/portal-wsrp/MarkupService</markup-url>
+ <registration-url>http://www.someproducer.com/portal-wsrp/RegistrationService</registration-url>
+ <portlet-management-url>http://www.someproducer.com/portal-wsrp/PortletManagementService</portlet-management-url>
+ </endpoint-config>
+ </wsrp-producer>
+ </deployment>
+</deployments>]]>
</programlisting>
</para>
@@ -333,25 +346,23 @@
<para>
<programlisting>
<![CDATA[
- <?xml version="1.0" encoding="UTF-8"?>
- <deployments>
- <deployment>
- <wsrp-producer>
- <producer-id>AnotherProducer</producer-id>
- <expiration-cache>60</expiration-cache>
- <endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoint-wsdl-url>
- <registration-data>
- <consumer-name>JBoss Portal 2.4 Test</consumer-name>
- <property>
- <name>property name</name>
- <lang>en</lang>
- <value>property value</value>
- </property>
- </registration-data>
- </wsrp-producer>
- <deployment>
- </deployments>
- ]]>
+<?xml version="1.0" encoding="UTF-8"?>
+<deployments>
+ <deployment>
+ <wsrp-producer>
+ <producer-id>AnotherProducer</producer-id>
+ <expiration-cache>60</expiration-cache>
+ <endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoint-wsdl-url>
+ <registration-data>
+ <property>
+ <name>property name</name>
+ <lang>en</lang>
+ <value>property value</value>
+ </property>
+ </registration-data>
+ </wsrp-producer>
+ </deployment>
+</deployments>]]>
</programlisting>
</para>
</sect2>
More information about the jboss-svn-commits
mailing list