Writing a filter for the Web services gateway

Before you begin

The filters that you create as described in this topic use the gateway WorkArea to maintain context. Specifically, they extend FilterImpl which implements this for you:

       public int getContextVersion() {
              return Filter.CONTEXT_VERSION_WORKAREA;
       }
The gateway WorkArea is only available on WebSphere Application Server Enterprise Version 5 or WebSphere Business Integration Server Foundation Version 5.1.

To use this information you should be familiar with using a Java 2 platform, Enterprise Edition (J2EE) session bean development environment such as IBM WebSphere Studio Application Developer.

Why and when to perform this task

A Web services gateway filter is essentially a J2EE session bean implementing specific Home and Remote interfaces.

To write a filter using IBM WebSphere Studio Application Developer, for deployment on WebSphere Application Server Enterprise Version 5 or WebSphere Business Integration Foundation Version 5.1, complete the following steps. For more detailed information on writing session beans, see the WebSphere Studio documentation topic Developing enterprise beans - overview.

Steps for this task

  1. Open the J2EE perspective.
  2. To create a new EJB application project, complete the following steps:
    1. Select File > New > Enterprise Application Project.
      The Project Creation wizard opens.
    2. In the Project Creation wizard, complete the following steps:
      1. Select the version of the J2EE specification that you want to use, then click Next.
      2. Type your project name.
      3. Create a new module project for the EJB project only. Clear the other Application Client Project, Web Project and Connector Project check boxes as necessary.
      4. Clear the Web module check box.
      5. Click Finish.
      Your new EJB application project and associated EAR project are created.
  3. To add the extra JAR files that your EJB module needs that are not already in the enterprise application server /lib directory, complete the following steps:
    1. Select File > Import.
    2. In Select an import source, select File system then click Next.
    3. In the Import window, complete the following steps:
      1. Select wsgw_root/client as the source directory.

        where wsgw_root is the root directory for your installation of the gateway.

      2. Select the wsgwejb.jar file.
      3. Select the root directory of your new EAR project as the destination for imported resources.
      4. Click Finish.

      Note: You might see one or more instances of the following WebSphere Studio warning message. You should ignore these messages.

        IWAE0024W The Manifest Class-Path for archive wsgwejb.jar contains
        an entry, name.jar, that is not resolveable to a file or module in
        the EAR earName.

    4. Repeat the previous File > Import process to add any other extra JAR files that your EJB module needs.
    5. In the J2EE Hierarchy view, from the pop-up menu for your EJB module, select Open With > JAR Dependency Editor.
    6. In the JAR Dependencies window, select all the JAR files listed.
    7. Close the JAR Dependencies window, then click Yes in the Save Resource window to save your changes.
  4. To add extra JAR files to the Java build path for your EJB module, complete the following steps:
    1. In the J2EE Hierarchy view, select your EJB module Properties.
    2. In the Properties window, verify that the following JAR files are included on the Java Build Path:
      • install_root/lib/jrom.jar
      • install_root/lib/qname.jar
      • install_root/lib/wsdl4j.jar
      • install_root/lib/wsif.jar
      • wsgw_root/client/wsgwejb.jar
      where install_root is the root directory for your installation of IBM WebSphere Application Server Enterprise Version 5 or IBM WebSphere Business Integration Server Foundation Version 5.1, and wsgw_root is the root directory for your installation of the gateway.
    3. Add any other JAR files or projects that you need for compiling your filter.
    4. Click OK.
  5. To create the session bean, complete the following steps:
    1. Select File > New > Enterprise Bean.
      The Enterprise Bean Creation wizard opens.
    2. In the Enterprise Bean Creation wizard, complete the following steps:
      1. Select your EJB project, then click Next.
      2. Verify that Session Bean is selected.
      3. Enter a name for the bean.
      4. Enter a suitable package name for the bean.
      5. Click Next.
    3. In the Enterprise Bean Details window, complete the following steps:
      1. Accept the defaults offered for Session type (Stateless) and Transaction type (Container).
      2. Accept the defaults offered for Bean supertype (<none>), Bean class and EJB binding name.
      3. [5.0 only][Version 5.0.1][Version 5.0.2]Confirm that Local client view is not enabled.
      4. For the Remote client view: Remote Home Interface, click Class... then select the com.ibm.wsgw.beans.FilterHome interface.
      5. For the Remote client view: Remote Interface, click Class... then select the com.ibm.wsgw.beans.FilterRemote interface.
      6. Click Next.
    4. In the EJB Java Class window, specify the Bean superclass as com.ibm.wsgw.beans.FilterImpl, then click Finish.
    Your new session bean is created.
  6. The generated Java code for your session bean does not implement the filter. To update the code, complete the following steps:
    1. In the J2EE Hierarchy view, expand your session bean to show Java code entries for the Home interface, the Remote interface and for the session bean.
    2. In the J2EE Hierarchy view, double-click the entry for the session bean code. In the editor view, the generated code opens for editing.
    3. In the editor view, add the following import statements:
      import com.ibm.wsgw.*;
      import com.ibm.wsgw.beans.*;
      import org.apache.wsif.*;
      import java.rmi.RemoteException;
      If you selected J2EE version 1.3 or later for your enterprise application project, then omit the import java.rmi.RemoteException statement from the set of import statements added here.
    4. Select File > Save to save the file. Ignore any errors.
    If you selected J2EE version 1.3 or later for your enterprise application project, then your filter methods must not throw a java.rmi.RemoteException exception. For J2EE version 1.3 or later:
    • Omit the statement import java.rmi.RemoteException from the set of import statements added in the previous step.
    • Remove all instances of throws RemoteException from your filter methods.
    • Code your filter to override the getContextVersion() method from FilterImpl (to eliminate the RemoteException from this method). Specifically, implement a getContextVersion() method in your filter to return Filter.CONTEXT_VERSION_WORKAREA as shown in the following example:
      public int getContextVersion()
         {
           return Filter.CONTEXT_VERSION_WORKAREA;
         }
  7. To add the unimplemented methods of the Filter interface to your session bean, complete the following steps:
    1. Open the Outline view (select Window > Show View > Outline).
    2. In the Outline view, from the pop-up menu for your session bean, select Override Methods.
    3. In the Override Methods window, select all the Filter methods to override then click OK.
    The methods of the Filter interface are added to your session bean.
  8. Select File > Save to save the file. Any errors from the previous File > Save are resolved.
  9. Develop your filter.

    The exact steps that you take to develop your filter depend upon what you want it to do. However, to develop any filter, you use the following resources:

    Note: You must observe the J2EE programming model, and ensure that any non-gateway services you use are available on all platforms on which the filter might be expected to run. For example, do not use static variables to store state information because on certain platforms, or in certain configurations, a filter might be invoked in a different Java Virtual Machine (JVM) for each request.

Example

This example shows you how to access the context and get values in the filterRequest method of a filter.

import javax.naming.InitialContext;
import javax.naming.NamingException;

import com.ibm.websphere.workarea.UserWorkArea;
import com.ibm.websphere.workarea.WorkAreaException;

import com.ibm.wsgw.GatewayContextNames;

...

try
{
  // Lookup the WorkArea gateway context in JNDI
  InitialContext ctx = new InitialContext();
  UserWorkArea wsgwContext = 
    (UserWorkArea)ctx.lookup("services:websphere/WSGW/workarea");

  // Get the currently selected port name
  String  Ptype = 
    (wsgwContext.get(GatewayContextNames.TARGET_PORT_NAME)).getClass().getName();
  String ThePortname = 
    (String) wsgwContext.get(GatewayContextNames.TARGET_PORT_NAME);

  // Get the currently selected target service WSDL location
  String  Xtype = 
    (wsgwContext.get(GatewayContextNames.TARGET_SERVICE_LOCATION)).getClass().getName();
  TargetServiceLocation WSDLObject = 
    (TargetServiceLocation) wsgwContext.get(GatewayContextNames.TARGET_SERVICE_LOCATION);

  String ServiceLocation = WSDLObject.serviceLocation;
  int ServiceLocationType = WSDLObject.serviceLocationType;
  String ServiceName = WSDLObject.serviceName;
  String ServiceNamespace = WSDLObject.serviceNamespace;

}
catch ( NamingException e )
{
  // Handle any exceptions thrown by the InitialContext here
}
catch ( WorkAreaException e )
{
  // Handle exceptions thrown by UserWorkArea here
}

...

What to do next

After you have developed your filter, you need to generate deployment code and export the enterprise application. To do this using IBM WebSphere Studio Application Developer, complete the following steps:

  1. Open the J2EE perspective.
  2. In the J2EE Hierarchy view, from the pop-up menu for your EJB module, select Generate > Deploy and RMIC code.
  3. In the Generate Deploy and RMIC Code window, select the beans for which you want to generate code, then click Finish.
  4. To configure the deployment descriptor properties for your bean, complete the following steps:
    1. In the J2EE Hierarchy view, from the pop-up menu for your bean, select Open With > EJB Deployment Descriptor.
    2. On the Beans tab, set the Java Naming and Directory Interface (JNDI) name to the Filter class name. This name is used as the Home Location when the filter is deployed to the gateway.
    3. Close the EJB Deployment Descriptor window, then click Save to save the changes.
  5. To export the enterprise application, complete the following steps:
    1. In the J2EE Hierarchy view, from the pop-up menu for your project, select Export ....
    2. In the Select an export destination: box, select EAR file, then click Next.
    3. In the What resources do you want to export? box, type your project name.
    4. In the Where do you want to export resources to? box, type the destination directory.
    5. Select any other options that you require, then click Finish.
    .

You are now ready to install your filter into WebSphere Application Server Enterprise Version 5 or WebSphere Business Integration Server Foundation Version 5.1 (as described in the next to last step of Installing the gateway into a deployment manager cell and Installing the gateway into a stand-alone application server), then deploy your filter.


Related concepts
Filters - Service interceptors for the Web services gateway
Related tasks
Developing Web services gateway extensions
Using a filter to select a target service and port
Handling exceptions for the Web services gateway
Capturing Web service invocation information from the Web services gateway
Deploying filters to the Web services gateway
Removing filters from the Web services gateway
Related reference
Web services gateway - The Filter interface
Web services gateway - The gateway message context values



Searchable topic ID:   twsg_pme_wrifl
Last updated: Jun 21, 2007 8:07:48 PM CDT    WebSphere Business Integration Server Foundation, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.wasee.doc/info/ee/wsg/tasks/twsg_pme_wrifl.html

Library | Support | Terms of Use | Feedback