JBoss.orgCommunity Documentation
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.
Scenarios that motivate WSRP functionality include:
More information on WSRP can be found on the official website for WSRP. We suggest reading the primer for a good, albeit technical, overview of WSRP.
The WSRP Technical Committee defined WSRP Use Profiles to help with WSRP interoperability. We will refer to terms defined in that document in this section.
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).
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.
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.
While we provide a complete implementation of WSRP 1.0, we do need to go through the Conformance statements and perform more interoperability testing (an area that needs to be better supported by the WSRP Technical Committee and Community at large).
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 portal-wsrp.sar
service archive, included in
the main jboss-portal.sar
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 portal-wspr.sar
from the main jboss-portal.sar
service archive.
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
JBoss
Portal from the sources. Once this is done, navigate to
JBOSS_PORTAL_HOME_DIRECTORY/wsrp
and type: build deploy
At the end of the build process, portal-wsrp.sar
is copied to
JBOSS_HOME/server/default/deploy
.
If you have modified the port number on which Portal runs or bound your Application Server to a specific host name, you will also need update the port and/or hostname information for WSRP as found on JBoss Portal's wiki.
It is possible to use WSRP over SSL for secure exchange of data. Please refer to the instructions on how to do so from JBoss Portal's wiki.
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
remotable
element to the jboss-portlet.xml
deployment descriptor for
that portlet. If a jboss-portlet.xml
file does not exist, one must be added to the
WEB-INF
folder of the web application containing the portlet.
In the following example, the "BasicPortlet" portlet is specified as being remotable. The
remotable
element is optional.
Example 15.1.
<?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"> <portlet-app> <portlet> <portlet-name>BasicPortlet</portlet-name> <remotable>true</remotable> </portlet> </portlet-app>
It is also possible to specify that all the portlets declared within a given jboss-portlet.xml
file have a specific "remotable" status by default. This is done by adding a single remotable
element to the root portlet-app
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:
Example 15.2.
<?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"> <portlet-app> <remotable>true</remotable> <portlet> <portlet-name>RemotelyExposedPortlet</portlet-name> ... </portlet> <portlet> <portlet-name>NotRemotelyExposedPortlet</portlet-name> <remotable>false</remotable> ... </portlet> </portlet-app>
In the example above, we defined two portlets with a default "remotable" status set to true. This means that
all portlets defined in this descriptor are, by default, exposed remotely by JBoss Portal's WSRP producer.
Note, however, that it is possible to override the default behavior by adding a remotable
element to a portlet description. In that case, the "remotable" status defined by the portlet takes precedence
over the default. In the example above, the RemotelyExposedPortlet
inherits the "remotable"
status defined by default since it does not specify a remotable
element in its description.
The NotRemotelyExposedPortlet
, however, overrides the default behavior and is not remotely
exposed. Note that in the absence of a top-level remotable
element, portlets are NOT
remotely exposed.
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. For instructions on how to do so in JBoss Portal, please refer to Section 15.6, “Consuming remote WSRP portlets in JBoss Portal”.
JBoss Portal's Producer is automatically set up when you deploy a portal instance with the WSRP service.
You can access the WSDL file at
http://{hostname}:{port}/portal-wsrp/MarkupService?wsdl
. You can access the endpoint URLs
at:
http://{hostname}:{port}/portal-wsrp/ServiceDescriptionService
http://{hostname}:{port}/portal-wsrp/MarkupService
http://{hostname}:{port}/portal-wsrp/RegistrationService
http://{hostname}:{port}/portal-wsrp/PortletManagementService
The default hostname is localhost
and the default port is 8080.
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 using WSRP Producer descriptors. Alternatively, a portlet is provided to configure remote producers.
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.
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, check that there is a portlet provider with the
self
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
self
portlet
provider so that you can check that they work as expected with WSRP. The
portal-wsrp.sar
file contains a WSRP Producer descriptor (default-wsrp.xml
) that configures this
default producer. This file can be edited or removed if needed.
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. We will first examine how to do so using the configuration portlet. We will then show how the same result can be accomplish with a producer descriptor.
As of Portal 2.6, a configuration portlet is provided to configure access to remote WSRP Producers
grahically. You can access it at
http://{hostname}:{port}/portal/auth/portal/admin/WSRP
or by logging in as a Portal administrator and clicking on the WSRP tab in the Admin portal. If all went
well, you should see something similar to this:
This screen presents all the configured producers 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. Deactivating it will remove it from the list of available portlet providers. 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.
Next, we create a new Consumer which we will callbea
. Type "bea
" in
the
"Create a consumer named:" field then click on "Create consumer":
You should now see a form allowing you to enter/modify the information about the Consumer. Set the cache expiration value to 300 seconds and enter the WSDL URL for the producer in the text field and press the "Refresh & Save" button:
This will retrieve the service description associated with the Producer which WSRP 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 and that it expects a value for the registration
property named registration/consumerRole
:
Enter "public
" as the value for the registration property and press "Save &
Refresh" once more. You should now
see something similar to:
The Consumer for the bea
Producer should now be available as a portlet provider and
is ready to be used.
A producer is configured, by default, by retrieving the producer's information via a WSDL URL. There are
rare cases, however, where URLs need to be provided for each of the producer's end points. You can do
exactly that by unchecking the "Use WSDL?" checkbox, as is the case for the self
producer:
We will create a public-bea-wsrp.xml
descriptor. Note that the actual name does not
matter as long as it ends with -wsrp.xml
:
<?xml version='1.0' encoding='UTF-8' ?>
<!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">
<deployments>
<deployment>
<wsrp-producer id="bea" expiration-cache="300">
<endpoint-wsdl-url>http://wsrp.bea.com:7001/producer/producer?WSDL</endpoint-wsdl-url>
<registration-data>
<property>
<name>registration/consumerRole</name>
<lang>en</lang>
<value>public</value>
</property>
</registration-data>
</wsrp-producer>
</deployment>
</deployments>
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 producer-id
element with a "bea
" value. Put this file in the deploy directory and start the server (with JBoss Portal and its WSRP service deployed).
jboss-portal.sar/portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd
and
jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-consumer_2_6.xsd
Let's now look at the Admin page and the Management portlet. Click on the "Portlet definitions" tab at the top. Once this is done, look at the list of available portlet providers. If all went well, you should see something similar to this:
We have 3 available portlet providers:
local, self
andbea
. The
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 "View portlets". You should now see something similar to:
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:
A WSRP Producer descriptor is an XML file which name ends in -wsrp.xml
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. An XML Schema for the WSRP Producer descriptor format can be found at
jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-consumer_2_6.xsd
, while a (legacy) DTD
can be found at jboss-portal.sar/portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd
.
Let's now look at which information needs to be provided to configure access to a remote producer.
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
id
attribute of the
<wsrp-producer>
element.
JBoss Portal also needs to learn about the remote producer's endpoints to be able to connect to the remote web services and perform WSRP invocations. Two options are currently supported to provide this information:
<endpoint-config>
element and its
<service-description-url>
,
<markup-url>
,
<registration-url>
and
<portlet-management-url>
children. These URLs are
producer-specific so you will need to refer to your producer documentation or WSDL file to
determine
the appropriate values.
<endpoint-wsdl-url>
element. JBoss Portal will then
heuristically determine, from the information contained in the WSDL file, how to connect
appropriately
to the remote WSRP services.
Both the
id
attribute and either
<endpoint-config>
or
<endpoint-wsdl-url>
elements
are required for a functional remote producer configuration.
It is also possible to provide addtional configuration, which, in some cases, might be important to establish a proper connection to the remote producer.
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
expiration-cache
attribute of the
<wsrp-producer>
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 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.
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 producer when required.
Registration configuration is done via the
<registration-data>
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
<registration-data>
element. Values for the registration properties
required by the remote producer can be provided via
<property>
elements. See the example below for more details. Additionally, you can override the default consumer
name
automatically provided by JBoss Portal via the
<consumer-name>
element. If you choose to provide a consumer name, please remember that this should uniquely identify
your
consumer.
Here is the configuration of the self
producer as found in
default-wsrp.xml
with a cache expiring every five minutes:
Example 15.3.
<?xml version="1.0" encoding="UTF-8"?> <!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"> <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>
Here is an example of a WSRP descriptor with a 2 minute caching time and manual definition of the endpoint URLs:
Example 15.4.
<?xml version="1.0" encoding="UTF-8"?> <!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"> <deployments> <deployment> <wsrp-producer id="MyProducer" expiration-cache="120"> <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>
Here is an example of a WSRP descriptor with endpoint definition via remote WSDL file, registration data and cache expiring every minute:
Example 15.5.
<?xml version="1.0" encoding="UTF-8"?> <!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"> <deployments> <deployment> <wsrp-producer id="AnotherProducer" expiration-cache="60"> <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>
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 assert which level of service to provide to consumers based on the values of given registration properties.
It is therefore sometimes necessary to modify the registration that concretizes the service agreement
between a consumer and a producer. An example of easily available producer offering different level of
services is BEA's public producer. We configured access to that producer in
Section 15.6.2.1, “Using the configuration portlet”.
If you recall, the producer was requiring registration and required a value to be provided for the
registration/consumerRole
property. The description of that property indicated that
three values were possible: public
, partner
or
insider
each corresponding to a different service level. We registered using the
public
service level. This gave us access to three portlets as shown here:
Suppose now that we would like to upgrade our service level to the "insider" level. We will need to
tell BEA's producer that our registration data has been modified. Let's see how to do this. Assuming you
have configured access to the producer as previously described, please go to the configuration screen for
the bea
producer and modify the value of the registration/consumerRole
to insider
instead of public
:
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:
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:
You can now check the list of available portlets from the bea
provider and verify that
new portlets are now available:
It can also happen that a producer administrator decided to require more information from registered
consumers. In this case, invoking operations on the producer will fail with an
OperationFailedFault
. JBoss Portal will attempt to help you in this
situation. Let's walk through an example using the self
producer. Let's assume that
registration is required without any registration properties (as is the case by default). If you go to
the configuration screen for this producer, you should see:
Now suppose that the administrator of the producer now requires a value to be provided for an
email
registration property. We will actually see how to do perform this operation
in JBoss Portal when we examine how to configure Portal's producer in Section 15.8, “Configuring JBoss Portal's WSRP Producer”.
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":
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 email
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:
OperationFailedFault
as it is the generic exception returned by
producers if something didn't quite happen as expected during a method invocation. This means that
OperationFailedFault
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 currently exists.
Several operations are available from the consumer list view of the WSRP configuration portlet:
The available operations are:
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:
Warning: 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:
You can configure the behavior of Portal's WSRP Producer by using the WSRP administration interface, which
is the preferred way, or by editing the conf/config.xml
file found in
portal-wsrp.sar
. Several aspects can be modified with respects to whether
registration is required for consumers to access the Producer's services. An XML Schema for the configuration
format is available at jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-producer_2_6.xsd
,
while a (legacy) DTD is available at
jboss-portal.sar/portal-wsrp.sar/dtd/jboss-wsrp-producer_2_6.dtd
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
RegistrationPolicy
paired with the default
RegistrationPropertyValidator
. We will look into property
validators in greater detail later in Section 15.8.3, “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.
JBoss Portal 2.6.3 introduces 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:
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 RegistrationPolicy
to
use (and, if needed, which RegistrationPropertyValidator
), along with required
registration property description for which consumers must provide acceptable values to successfully
register.
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:
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:
You can specify the fully-qualified name for your RegistrationPolicy
and
RegistrationPropertyValidator
there. We will keep the default value. See
Section 15.8.3.1, “Customization of Registration handling behavior” for more details. Let's add, however, a registration property called
email
. 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:
Press "Save" to record your modifications.
Registration handling behavior can be customized by users to suit their Producer needs. This is
accomplished by providing an implementation of the
RegistrationPolicy
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.
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
RegistrationPropertyValidator
in the default registration policy. This allows users to define their own validation mechanism.
Please refer to the Javadoc™ for org.jboss.portal.registration.RegistrationPolicy
and org.jboss.portal.Registration.policies.RegistrationPropertyValidator
for more
details on what is expected of each method.
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.
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.
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.