Servlet extension interfaces

Servlet extension interfaces

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, refer to the Additional Application Programming Interfaces (APIs) article 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 any extension generator can be targeted by extensions added to RRD response data. The class attribute specifies 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, refer to the Additional Application Programming Interfaces (APIs) article 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 specifies 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, refer to the Additional Application Programming Interfaces (APIs) article for administrators.

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>
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.

Related:

Additional Application Programming Interfaces (APIs)
Deploy web applications with remote web or portlet applications using RRD