Chapter 33. Working with WSRP Extensions

⁠Chapter 33. Working with WSRP Extensions

The WSRP specifications allows for implementations to extend the protocol using Extensions . The portal provides a way for client code (for example, portlets) to interact with such extensions in the form of several classes and interfaces gathered within the org.gatein.wsrp.api.extensions package , the most important ones being InvocationHandlerDelegate , ConsumerExtensionAccessor and ProducerExtensionAccessor .

To be able to use this API, include the wsrp-integration-api-2.2.2.Final.jar (or higher) file to your project, where $WSRP_VERSION is the version of the portal WSRP implementation to use. This can be done by adding the following dependency to your maven project:

<dependency>
  <groupId>org.gatein.wsrp</groupId>
  <artifactId>wsrp-integration-api</artifactId>
  <version>$WSRP_VERSION</version>
</dependency>

Report a bug

⁠33.1. Using WSRP Extensions

⁠33.1.1. Infrastructure for InvocationHandlerDelegate

Using the InvocationHandlerDelegate infrastructure, custom behavior can be inserted on either consumer or producer sides to enrich WSRP applications before and after portlet requests and responses. For more information on the interface, see the Javadoc for org.gatein.wsrp.api.extensions.InvocationHandlerDelegate, which is available from https://github.com/gatein/gatein-wsrp/blob/master/api/src/main/java/org/gatein/wsrp/api/extensions/InvocationHandlerDelegate.java.

Warning

Because InvocationHandlerDelegate is a very generic interface, it could potentially be used for more than working with WSRP extensions alone. Because this interface has access to internal portal classes, it is important to treat access to these internal classes as read-only to prevent any unintentional side effects.

Report a bug

⁠33.1.2. Injecting InvocationHandlerDelegate implementations

Implementations of InvocationHandlerDelegatemust follow the same constraints as RegistrationPolicy implementations as detailed in Customization of Registration handling behavior section of the Configuring GateIn's WSRP Producer chapter, in essence, they must follow the Java ServiceLoader architectural pattern and be deployed in the appropriate JPP_HOME/gatein/extensions directory.

You can specify only one InvocationHandlerDelegate implementation per side: one implementation for the consumer and another one for the producer. This is accomplished by passing the fully classified class name to the appropriate system property when the portal is started:

⁠

Table 33.1. System Property Classname

WSRP Side	System property
consumer	org.gatein.wsrp.consumer.handlers.delegate
producer	org.gatein.wsrp.producer.handlers.delegate

⁠

Example 33.1. Example

./standalone.sh -Dorg.gatein.wsrp.consumer.handlers.delegate=com.example.FooInvocationHandlerDelegate

will inject the com.example.FooInvocationHandlerDelegate class on the consumer side, assuming that class implements the org.gatein.wsrp.api.extensions.InvocationHandlerDelegate interface and is packaged and deployed appropriately as explained above.

Report a bug

⁠33.1.3. Accessing extensions from client code

You can access extensions from client code using ConsumerExtensionAccessor and ProducerExtensionAccessor on the consumer and producer, respectively. Each interface provides several methods but you should only have to ever call two of them on each, as shown in the following table:

⁠

Table 33.2. Table Title

Interface	Relevant methods
`ConsumerExtensionAccessor`	`public void addRequestExtension(Class targetClass, Object extension)` `public List<UnmarshalledExtension> getResponseExtensionsFrom(Class responseClass)`
`ProducerExtensionAccessor`	`List<UnmarshalledExtension> getRequestExtensionsFor(Class targetClass)` `void addResponseExtension(Class wsrpResponseClass, Object extension)`

See the Javadoc for these classes for more details.

Adding and accessing extensions is supported from a core subset of WSRP classes pertaining to markup, interaction, resource or event requests and responses.

Important

Use org.w3c.dom.Element values as extensions to ensure interoperability.

⁠

Table 33.3. Supported Request and Response WSRP Classes

Request classes	Response classes
`org.oasis.wsrp.v2.InteractionParams`	`org.oasis.wsrp.v2.MarkupResponse`
`org.oasis.wsrp.v2.EventParams`	`org.oasis.wsrp.v2.BlockingInteractionResponse`
`org.oasis.wsrp.v2.MarkupParams`	`org.oasis.wsrp.v2.HandleEventsResponse`
`org.oasis.wsrp.v2.ResourceParams`	`org.oasis.wsrp.v2.ResourceResponse`

Report a bug

⁠33.2. WSRP Implementation Example

We also provide a complete, end-to-end example to get you started, which you can find at https://github.com/gatein/gatein-wsrp/tree/master/examples/invocation-handler-delegate . This example shows how ExampleConsumerInvocationHandlerDelegate , a consumer-side InvocationHandlerDelegate implementation, can add information extracted from the consumer and pass it along to the producer, working in conjunction with ExampleProducerInvocationHandlerDelegate , the associated producer-side InvocationHandlerDelegate , to establish a round-trip communication channel outside of the standard WSRP protocol, implementing the following scenario:

ExampleConsumerInvocationHandlerDelegate attaches to the consumer to add the current session id as an extension to render requests sent to the producer.
ExampleProducerInvocationHandlerDelegate provides the counterpart of ExampleConsumerInvocationHandlerDelegate on the producer. It checks incoming render requests for potential extensions matching what ExampleConsumerInvocationHandlerDelegate sends and adds an extension of its own to the render response so that the consumer-side delegate can know that the information it passed was properly processed.

To activate the InvocationHandlerDelegates on both the consumer and producer, start the portal instance as described in Chapter 34, Configuring the WSRP Producer.

Report a bug