You can use extension generators and handlers to add content to the remote
message for servlet and portlets calls. The servlet extension can also modify
existing behavior by leveraging the filter concept. The Remote Request Dispatcher
(RRD) extension framework relies on extension generators, which attach arbitrary
data to an outbound RRD request, and extension handlers, which consume the
data and perform actions based on the data received.
For more information on the
com.ibm.wsspi.rrd.extension package,
see
Additional Application Programming Interfaces for administrators.
Extension generators
Extension
generators, which are part of an extension generator chain, are invoked prior
to initiating an RRD request. This extension generator chain is defined in
the com.ibm.wsspi.rrd.generators extension point of the
plugin.xml file,
which can reside in one of the following locations:
- Another OSGI Bundle.
- Any shared library. For example, a shared library bound to a server class
loader.
- In the WEB-INF directory of an RRD-enabled local Web application.
Each extension generator is defined by a generator element, which
contains an id attribute, which is used to assign a unique identifier to the
extension generator such that any extension generator can be targeted by extensions
added to RRD response data. The class attribute is used to specify the class
name of the extension generator, which must implement the com.ibm.wsspi.rrd.extension.generator.ExtensionGenerator interface.
Each extension generator can also have an execution order associated with
it via the order attribute, which is useful for enforcing extension generator
execution order in an environment where multiple extension generator descriptor
files are present. Additionally, a generator has a mandatory attribute called
type that defines the type of the generator. For servlet RRD, the value is
“servlet” and the class must implement the com.ibm.wsspi.rrd.extension.generator.ExtensionGenerator interface.
Additionally,
each extension generator may be provided with an arbitrary number of initialization
parameters, which are specified by including zero or more
init-param elements
as children of the generator element. An example extension generator declaration
follows:
<extension point="com.ibm.wsspi.rrd.generators">
<generator id="int1"
class="com.ibm.ws.rrd.example.extension.IntExtensionGenerator"
order="1"
type=”servlet”>
<init-param>
<param-name>intValue</param-name>
<param-value>100</param-value>
</init-param>
</generator>
<generator id="string1"
class="com.ibm.ws.rrd.example.extension.StringExtensionGenerator"
order="2"
type=”servlet”>
<init-param>
<param-name>stringValue</param-name>
<param-value>This is an example string</param-value>
</init-param>
</generator>
<generator id="int2"
class="com.ibm.ws.rrd.example.extension.IntExtensionGenerator"
order="3"
type=”servlet”>
<init-param>
<param-name>intValue</param-name>
<param-value>200</param-value>
</init-param>
</generator>
</extension>
For more information on the
com.ibm.wsspi.rrd.extension.generator package,
see
Additional Application Programming Interfaces for administrators.
Extension handlers
Extension handlers,
which are part of an extension handler chain, are invoked after an RRD request
has been received. This extension handler chain is defined in the
com.ibm.wsspi.rrd.handlers extension
point of the
plugin.xml file, which can reside in one of the following
locations:
- Another OSGI Bundle.
- Any shared library. For example, a shared library bound to a server class
loader.
- In the WEB-INF directory of an RRD-enabled local Web application.
Each extension handler is defined by a handler element, which
contains namespaceURI and localName attributes, the combination of which defines
the qualified name of the extension data that the extension handler can process.
Each extension handler additionally requires a unique identifier, specified
by the id attribute. The value specified by this attribute must correspond
to an extension generator, which generates extension data of a matching qualified
name and identifier. The class attribute is used to specify the class name
of the extension handler, which must implement the com.ibm.wsspi.extension.handler.ExtensionHandler
interface. Additionally a handler has a mandatory attribute called type that
defines the type of the handler. The value is “servlet” and the class must
implement the com.ibm.wsspi.rrd.extension.handler.ExtensionHandler interface.
Additionally,
each extension handler may be provided with an arbitrary number of initialization
parameters, which are specified by including zero or more
init-param elements
as children of the handler element. An example extension handler declaration
follows:
<extension point="com.ibm.wsspi.rrd.handlers">
<handler id="int1"
class="com.ibm.ws.rrd.example.extension.IntExtensionHandler"
namespaceURI="http://www.ibm.com/ws/rrd/ext/types"
localName="SimpleType" order="1"
type=”servlet”/>
<handler id="string1"
class="com.ibm.ws.rrd.example.extension.StringExtensionHandler"
namespaceURI="http://www.ibm.com/ws/rrd/ext/types"
localName="SimpleType" order="2"
type=”servlet”/>
<handler id="int2"
class="com.ibm.ws.rrd.example.extension.IntExtensionHandler"
namespaceURI="http://www.ibm.com/ws/rrd/ext/types"
localName="SimpleType" order="3"
type=”servlet”/>
</extension>
For more information on the
com.ibm.wsspi.rrd.extension.handler package,
see the API documentation.
Extension delegators
An extension
delegator enables RRD to handle arbitrary servlet containers by allowing users
to specify the specific extension generator and handler chain instances that
are to be used during an RRD call. RRD maintains a user-extendable list of
extension delegators and selects an appropriate delegator at runtime based
on the type of servlet request being issued.
Custom extension delegators
may be defined in the
com.ibm.wsspi.rrd.rrd-extension-delegator extension
point of the
plugin.xml file, which can reside in one of the following
locations:
- Another OSGI Bundle.
- Any shared library. For example, a shared library bound to a server class
loader.
- In the WEB-INF directory of an RRD-enabled local Web application.
Each extension delegator is defined by an
ExtensionDelegator element,
which contains a priority attribute for defining the relative order in which
an extension delegator is initiated, and a classname attribute that defines
the implementing class for a particular extension delegator, which must implement
the
com.ibm.wsspi.rrd.extension.factory.ExtensionDelegator interface.
Note that the execution order of two or more extension delegators with the
same priority is not predictable. An example extension delegator declaration
follows:
<extension point="com.ibm.wsspi.rrd.rrd-extension-delegator">
<ExtensionDelegatorRegistration>
<ExtensionDelegator priority="1" classname="com.ibm.ws.rrd.extension.PortletExtensionDelegator"/>
<ExtensionDelegator priority="2" classname="com.ibm.ws.rrd.extension.ServletExtensionDelegator"/>
</ExtensionDelegatorRegistration>
</extension>
Custom EMF packages
Extension data produced
by an extension generator and consumed by an extension handler is serialized
using the Eclipse Modeling Framework (EMF). Users intending to use custom
extension data should utilize the
com.ibm.wsspi.rrd.rrd-emf-packages extension
point in order to ensure that the proper EMF packages are initialized prior
to use by RRD. This extension point is part of the
plugin.xml file,
which can reside in one of the following locations:
- Another OSGI Bundle.
- Any shared library. For example, a shared library bound to a server class
loader.
- In the WEB-INF directory of an RRD-enabled local Web application.
Each EMF package is defined by an
emfPackage element,
which contains a className element that must point to the generated EMF factory
implementation class for a particular EMF package (the generated model class
which implements
org.eclipse.emf.ecore.impl.EFactoryImpl). An example
EMF package declaration follows:
<extension point="com.ibm.wsspi.rrd.rrd-emf-packages">
<emfPackages>
<emfPackage className="com.ibm.ws.rrd.webservices.types.emf.impl.TypesFactoryImpl" />
</emfPackages>
</extension>
Note: If the same generated EMF model code is shared
among multiple Web applications that the EMF model code must be part of a
shared server library, but only in the case that all Web applications are
running in the same application server. In production, this is usually not
the case, and common EMF model code may exist at the Web application level.