Author: chris.laprun(a)jboss.com Date: 2007-02-09 18:32:40 -0500 (Fri, 09 Feb 2007) New Revision: 6201 Modified: docs/trunk/referenceGuide/en/modules/wsrp.xml Log: - Updated for 2.6 (still needs more work). - Added section on Producer configuration. - Added section on using SSL. - Fixed an issue with one of the given examples (xml was invalid). - General improvements. Modified: docs/trunk/referenceGuide/en/modules/wsrp.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/wsrp.xml 2007-02-09 23:10:31 UTC (rev 6200) +++ docs/trunk/referenceGuide/en/modules/wsrp.xml 2007-02-09 23:32:40 UTC (rev 6201) @@ -32,34 +32,51 @@ <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/tc_home.php?wg_abbrev=wsrp... + We suggest reading the <ulink + url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... for a good, albeit technical, overview of WSRP. </para> </sect1> <sect1> <title>Deploying JBoss Portal's WSRP services</title> - <para>JBoss Portal provides a base level support of the WSRP 1.0 standard and offers + <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> - service archive, included in the main <emphasis>jboss-portal.sar</emphasis> service archive.</para> + service archive, included in the main <emphasis>jboss-portal.sar</emphasis> service archive, if + you've obtained JBoss Portal from a binary distribution. If you don't intend on using WSRP, we + recommend that you remove the <emphasis>portal-wspr.sar</emphasis> from the main + <emphasis>jboss-portal.sar</emphasis> service archive.</para> <para>If you've obtained the source distribution of JBoss Portal, you need to build and deploy the WSRP service separately. Please follow the instructions on how to install - <ulink url="http://docs.jboss.com/jbportal/v2.4/reference-guide/en/html_sin... Portal + <ulink url="http://docs.jboss.com/jbportal/v2.6/reference-guide/en/html_sin... Portal from the sources</ulink>. Once this is done, navigate to <emphasis>JBOSS_PORTAL_HOME_DIRECTORY/wsrp</emphasis> and type: <programlisting>build deploy</programlisting> At the end of the build process, <emphasis>portal-wsrp.sar</emphasis> is copied to <emphasis>JBOSS_HOME/server/default/deploy</emphasis>. + </para> - <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) 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&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>. - </note> - </para> + <sect2> + <title>Considerations to use WSRP behind firewall</title> + <para>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) 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). + 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>. + </para> + </sect2> + + <sect2> + <title>Considerations to use WSRP with SSL</title> + <para>It is possible to use WSRP over SSL for secure exchanges of data. Please refer to the + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WSRPUseSSL">in...;. on + how to do so as found on + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossPortal">J... Portal's wiki</ulink>. + </para> + </sect2> </sect1> <sect1> @@ -76,11 +93,12 @@ <para> <programlisting> <![CDATA[ -<?xml version="1.0" encoding="UTF-8"?> -<portlet> - <portlet-name>BasicPortlet</portlet-name> - <remotable>true</remotable> -</portlet>]]> +<portlet-app> + <portlet> + <portlet-name>BasicPortlet</portlet-name> + <remotable>true</remotable> + </portlet> +</portlet-app>]]> </programlisting> </para> <para> @@ -125,16 +143,17 @@ the URL for the Producer's WSDL definition or the URLs for the individual endpoints. </para> <para> - JBoss Portal's Producer is automatically set up when you deploy a portal instance. Assuming you're running a + JBoss Portal's Producer is automatically set up when you deploy a portal instance with the WSRP service. + Assuming you're running a default configuration (i.e. you haven't changed the server's port number), you can access the WSDL file at - <literal>http://localhost:8080/portal-wsrp/MarkupService?wsdl</literal>. You can acces the endpoint URLs are: + <literal>http://localhost:8080/portal-wsrp/MarkupService?wsdl</literal>. You can access the endpoint URLs at: <itemizedlist> <listitem>http://localhost:8080/portal-wsrp/ServiceDescriptionService</listitem> <listitem>http://localhost:8080/portal-wsrp/MarkupService</listitem> <listitem>http://localhost:8080/portal-wsrp/RegistrationService</listitem> <listitem>http://localhost:8080/portal-wsrp/PortletManagementService</listitem> </itemizedlist> - </para> + </para> </sect1> <sect1> @@ -153,24 +172,19 @@ 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 would for local portlets. - <note> - As of 2.4, the optional Portlet Management interface of WSRP is <emphasis role="bold">NOT</emphasis> - supported. It is therefore not possible to clone and configure portlets on the consumer side. This will - be supported in 2.6. - </note> </para> <para> 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> + the service indeed works, check 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 + 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. </para> <para> - Let's see work through the steps of defining access to a remote producer so that its portlets can be + 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 @@ -223,9 +237,9 @@ </mediaobject> </para> <para> - 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 + 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: <mediaobject> @@ -245,7 +259,7 @@ afterwards. This is accomplished via the <emphasis role="bold">&lt;producer-id&gt;</emphasis> element.</para> <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 + remote web services and perform WSRP invocations. Two options are currently supported to provide this information: </para> @@ -290,15 +304,19 @@ 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">&lt;expiration-cache&gt;</emphasis> element which specifies the - refreshing period in seconds. + 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 Portal 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>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 - and it is thus possible to provide required registration information in the producer configuration so that - the Portal consumer can register with the remote producer when required. + 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 + producer when required. <note>At this time, though, only simple String properties are supported and it is not possible to configure - complex registration data.</note> + complex registration data. This should however be sufficient for most cases.</note> </para> <para>Registration configuration is done via the <emphasis role="bold">&lt;registration-data&gt;</emphasis> @@ -316,7 +334,7 @@ <sect2> <title>Examples</title> - <para>Here is an example of a WSRP descriptor with a 2 minutes caching time and manual definition of the endpoint + <para>Here is an example of a WSRP descriptor with a 2 minute caching time and manual definition of the endpoint URLs:</para> <para> @@ -367,4 +385,146 @@ </para> </sect2> </sect1> + + <sect1> + <title>Configuring JBoss Portal's WSRP Producer</title> + <sect2> + <title>Overview</title> + <para> + You can configure the behavior of Portal's WSRP Producer by editing the <emphasis>conf/config.xml</emphasis> + file found in <emphasis>portal-wsrp.sar</emphasis>. Several aspects can be modified with respects to whether + registration is required for consumers to access the Producer's services. + </para> + </sect2> + <sect2> + <title>Default configuration</title> + <para> + Let's look at the default configuration: + <programlisting> + <![CDATA[ +<producer-configuration> + <registration-configuration fullServiceDescriptionRequiresRegistration="true"> + <registration-property-validator>org.jboss.portal.registration.policies.DefaultRegistrationPropertyValidator</registration-property-validator> + </registration-configuration> +</producer-configuration>]]> + </programlisting> + The top element <emphasis role="bold">&lt;producer-configuration&gt;</emphasis> contains a single + <emphasis role="bold">&lt;registration-configuration&gt;</emphasis> element that defines a + <emphasis>fullServiceDescritpionRequiresRegistration</emphasis> attribute with the value "true". This + configuration specifies that the WSRP producer requires registration to 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 <emphasis role="bold">&lt;registration-configuration&gt;</emphasis> element contains a + <emphasis role="bold">&lt;registration-property-validator&gt;</emphasis> element. 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> + </sect2> + <sect2> + <title>Minimal producer configuration</title> + <para> + Requiring registration is optional: if you don't need your producer to require consumer registration, the + only thing you need to do is to provide an empty <emphasis + role="bold">&lt;producer-configuration&gt;</emphasis> + element in <emphasis>portal-wsrp.sar/conf/config.xml</emphasis>. + </para> + </sect2> + <sect2 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. This is done via the + <emphasis role="bold">&lt;registration-configuration&gt;</emphasis> element. This element is optional as + previously noted. It can be empty if you don't require registration properties. You can also specify + whether or not registration is required in order for consumers to access the Producer's full service + description, as noted in our discussion of the default configuration, above. This is done via the + <emphasis>fullServiceDescriptionRequiresRegistration</emphasis> attribute, which is optional. Acceptable + values for this attribute are "true" or "false", defaulting to "false" in which case the Producer will always + return the full service description, whether the consumer asking for it is registered or not. + </para> + + <sect3> + <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 <emphasis role="bold">RegistrationPolicy</emphasis> + interface. This interface defines behaviors 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. + </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 + <emphasis role="bold">RegistrationPropertyValidator</emphasis> in the default registration policy. This + allows users to define their own validation mechanism. + </para> + <para>Please refer to the Javadoc for <literal>org.jboss.portal.registration.RegistrationPolicy</literal> + and <literal>org.jboss.portal.Registration.policies.RegistrationPropertyValidator</literal> for more details + on what is expected of each method. + </para> + <para>As far as configuration of the Producer goes, a registration policy is required. This is accomplished + by specifying the qualified class name of the registration policy via the + <emphasis role="bold">&lt;registration-policy&gt;</emphasis> element. Since we anticipate that most users + will use the default registration policy, it is possible to use + <emphasis role="bold">&lt;registration-property-validator&gt;</emphasis> element and provide the class + name of your custom property validator instead. Since specifying a property validator only makes sense in + the context of the default registration policy, both elements are mutually exclusive. + + <note>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.</note> + </para> + </sect3> + + <sect3> + <title>Registration properties</title> + <para>You can also specify that consumers wishing to register with your producer provide acceptable values + for one or several registration properties. This is accomplished by providing a + <emphasis role="bold">&lt;registration-property-description&gt;</emphasis> element per required registration + property. This element lets provide information about a given registration property such as its name, its type, + the hint and label that will be sent to remote consumers. + <note> + At this time, only String (xsd:string) properties are supported. If your application requires more complex + properties, please let us know. + </note> + </para> + </sect3> + + </sect2> + <sect2> + <title>Example</title> + <para> + Here is an example of a producer configurations requiring registration, barring consumers from accessing its + complete service description until they are correctly registered and requires consumers to provide acceptable + values for two String registration properties named "name1" and "name2" respectively. The registration + service will use the <literal>com.example.portal.SomeCustomRegistrationPolicy</literal> class for its + registration policy. + <programlisting> + <![CDATA[ +<producer-configuration> + <registration-configuration fullServiceDescriptionRequiresRegistration="true"> + <registration-policy>com.example.portal.SomeCustomRegistrationPolicy</registration-policy> + <registration-property-description> + <name>name1</name> + <type>xsd:string</type> + <hint xml:lang="en" resourceName="resource.hint1">hint1</hint> + <label xml:lang="en" resourceName="resource.label1">label1</label> + </registration-property-description> + <registration-property-description> + <name>name2</name> + <type>xsd:string</type> + <hint xml:lang="en" resourceName="resource.hint2">hint2</hint> + <label xml:lang="en" resourceName="resource.label2">label2</label> + </registration-property-description> + </registration-configuration> +</producer-configuration>]]> + </programlisting> + </para> + </sect2> + </sect1> </chapter>