Developing an Axis2 Java handler for the CICS web service client pipeline

This article uses sample code to show you how to develop an Axis2 Java™ handler to use in the IBM CICS® web service client pipeline. The Java handler makes SOAP processing eligible for offloading to an IBM® System z® Application Assist Processor (zAAP).

Giovanni Creato (giovanni.creato@it.ibm.com), IT Specialist, IBM

Photo of Giovanni CreatoGiovanni Creato is an IT Specialist on the IBM System z team in Milan, Italy. He has been working as a System z IT Specialist for three years, and his focus areas include CICS TS, Java on System z, z/OS systems programming, plus system iteroperability and system integration. You can contact Giovanni at giovanni.creato@it.ibm.com.



14 May 2014

Introduction

This article assumes that you have already set up CICS to act as a service requester using the Java pipeline. See below for a list of the required resources that you should have in place. For detailed instructions on how to set up CICS as a service requester, see Creating the web services infrastructure in the CICS TS V4.2 information center.

Axis2 web service infrastructure

After you set up the CICS web service infrastructure, you should have the following resources in place:

  • Axis2 JVM server -- Required to execute the Axis2 framework in CICS. To use this resource you should have in place:
    • JVMSERVER -- Definition in CICS CSD that points to a valid JVM server profile
    • JVM server profile for Axis2 web service
  • Axis2 client pipeline -- Required to enable a CICS program to act as a service requester using the Axis2 framework. To use this resource, you must have a PIPELINE definition in CICS CSD that points to:
    • Configuration file -- XML file that describes how the pipeline will process web services. See Listing 1 below for a sample configuration file for Axis2 Java web service client pipeline.
    • WS directory (pickup directory) -- Directory is used to automatically deploy web services that you have generated with CICS Assistant utilities.
    • Shelf directory -- Placeholder for web services installed within CICS.
  • (Optional) A valid CICS service requestor to use for testing
Listing 1. Sample configuration file for Axis2 Java web service client pipeline
<?xml version="1.0" encoding="EBCDIC-CP-US"?>
<requester_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline">
    <service>
        <service_handler_list>
            <cics_soap_1.1_handler_java>
                <jvmserver>DFHJVMAX</jvmserver>
            </cics_soap_1.1_handler_java>
        </service_handler_list>
    </service>
</requester_pipeline>

Developing an Axis2 Java handler

This section shows you how to develop a simple Axis2 Java handler using Rational Developer for System z. You can use another IDE if you wish.

Configuring your IDE

Create a new Java project:

  1. At bottom right, click File => New => Project.
  2. For Project Type, select Java project and then click Next.
  3. Specify a Project Name, such as CustomAxis2Handler.

You can now customize the Java build path of your project to include any required library.

  1. In the Project Explorer view, right-click on the newly created project name and click on Properties.
  2. Select Java Build Path.
  3. Add any required JAR files. At a minimum, you must add:
    • axis2-kernel.jar -- Contains core Axis2 classes
    • axiom-api.jar -- Contains core axiom Axis2 classes
    • commons-logging.jar -- Required to develop the example code
    You can find these JAR files in the CICS TS installation directory, which is usually /usr/lpp/cicsts/cicsts.v4r2/lib/pipeline.
  4. Make sure the Java level you are using is compatible with the supported CICS level. For CICS TS V4.2, use Java 1.6. For CICS TS V5.1, use Java 1.7.

Your IDE is now configured, and you can start to develop your Axis2 Java handler.

Developing the handler using the sample code provided

This section shows you how to write two simple handlers: LogHandler and CustomHeaderHandler. You can use the first handler to log the SOAP envelop content, and the second one to add a custom header in the SOAP envelope.

  1. Create a new Java class called LogHandler inside a package (such as com.ibm.it.gcre.handler).
  2. The newly created class has to extend AbstractHandler and implement Handler.
  3. Implement the required method InvocationResponse.
LogHandler.java
package com.ibm.it.gcre.handler;

import org.apache.axis2.AxisFault;
import org.apache.axis2.context.MessageContext;
import org.apache.axis2.engine.Handler;
import org.apache.axis2.handlers.AbstractHandler;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class LogHandler extends AbstractHandler implements Handler{

    private static final Log log = LogFactory.getLog(LogHandler.class);
    private String name;

    public InvocationResponse invoke(MessageContext msgContext) throws AxisFault {

        log.info(msgContext.getEnvelope().toString());
        return InvocationResponse.CONTINUE;        
    }

    public void revoke(MessageContext msgContext) {
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}
  1. Repeat steps 1 and 2 above for the Java class CustomHeaderHandler.
CustomHeaderHandler.java
package com.ibm.it.gcre.handler;

import org.apache.axiom.om.OMElement;
import org.apache.axiom.om.OMNamespace;
import org.apache.axiom.soap.SOAPEnvelope;
import org.apache.axiom.soap.SOAPFactory;
import org.apache.axiom.soap.SOAPHeader;
import org.apache.axiom.soap.SOAPHeaderBlock;
import org.apache.axis2.AxisFault;
import org.apache.axis2.context.MessageContext;
import org.apache.axis2.engine.Handler;
import org.apache.axis2.handlers.AbstractHandler;

public class CustomHeaderHandler  extends AbstractHandler implements Handler {

    private String name;
    private SOAPEnvelope envelope;
    private SOAPFactory factory;
    private OMNamespace namespace;
    private SOAPHeader header;
    private SOAPHeaderBlock headerBlock;
    private OMElement headerTag;

    private String headerTagValue;
     
    public InvocationResponse invoke(MessageContext msgContext) throws AxisFault {
    
        envelope = msgContext.getEnvelope();        
        factory = (SOAPFactory) envelope.getOMFactory();
        namespace = factory.createOMNamespace(
             "http://my.company.org/my.custom.namespace.xsd", 
             "custns");
        header = factory.createSOAPHeader(envelope);
        headerBlock = header.addHeaderBlock("HeaderBlockName", namespace);
        headerTag = factory.createOMElement("HeaderTagName",namespace) ;
        headerTagValue = "This is the value of the header tag";
        headerTag.addChild(factory.createOMText(headerTagValue));
        headerBlock.addChild(headerTag);
        return InvocationResponse.CONTINUE;        
    }

    public void revoke(MessageContext msgContext) {
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

The code in the sample will generate the following header structure in the SOAP envelope:

Custom header generated by the handler
<SOAP-ENV:Header>
    ...
    <custns:HeaderBlockName 
    xmlns:custns="http://my.company.org/my.custom.namespace.xsd">
        <custns:HeaderTagName>
            This is the value of the header tag
        </custns:HeaderTagName>
    </custns:HeaderBlockName>
    ...
</SOAP-ENV:Header>

You have now finished developing the Java handler. For more information on how to develop an Axis2 Java handler, see Apache Axis2/Java documentation.

Exporting the JAR file

You can now export the artifacts to your remote system, for example, into the directory /myDir/ using the name /MyHandler.jar.

  • If you are using Rational Developer for System z, right-click on the project name, click Export, select Remote JAR file, and select the directory where you want to place your JAR file.
  • If you are using any other IDE, you need to Export as a JAR file and then FTP (binary mode) to the host system.

Configuring Axis2 in CICS

This section gives an overview of the Axis2 framework and then shows you how to set up CICS to use a custom Axis2 Java handler.

Apache Axis2 is a web services, SOAP, and WSDL engine that uses a repository to store all of its configuration files, services, and modules. On z/OS™, CICS provides a default repository in the usshome/lib/pipeline/repository directory. On UNIX™, usshome is the value of the USSHOME system initialization parameter.

The main configuration file is axis2.xml, which controls how the application deals with inbound and outbound messages. It defines message receivers, transport receivers, and transport senders. It also defines the order of phases, and the handlers to be executed within each phase. This file is the extension point you will use to configure Axis2 to use your handler.

Creating a customized repository

Customize the axis2.xml configuration file to include references to your new handler. Before customizing this file, create a new Axis2 repository by designating a directory to contain the new repository. For example, use /etc/cicsts/axis2/pipeline/repository/ and then copy the contents of the default repository into this directory using the following command:

Command to copy the content of the repository
cp -R /usr/lpp/cicsts/cicsts.v4r2/lib/pipeline/repository/* 
    /etc/cicsts/axis2/pipeline/repository/

This command creates the directory structure shown below:

Axis2 repository
The Axis2 repository must have the same directory structure as the one provided with the product

Pointing to the newly created repository

You now need to point the CICS Java pipeline to the new configuration structure by inserting the following XML into the CICS pipeline configuration file:

Pointing to the newly created repository
<?xml version="1.0" encoding="EBCDIC-CP-US"?>
<requester_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline">
        <service>
        <service_handler_list>
            <cics_soap_1.1_handler_java>
                <jvmserver>DFHJVMAX</jvmserver>
                <repository>
                /etc/cicsts/axis2/pipeline/repository/
                </repository>
            </cics_soap_1.1_handler_java>
        </service_handler_list>
    </service>
</requester_pipeline>

Configuring the Axis2 JVM to include the Java handler

In order for the Axis2 JVM to execute the Java handler that you developed, you must insert the JAR file into the JVM class path. To do so, modify the Axis2 JVM profile by adding your JAR and using the CLASSPATH_PREFIX option. /myDir is the directory where you uploaded your JAR file:

Adding your JAR file to the JVM class path
CLASSPATH_PREFIX=/myDir/MyHandler.jar

Invoking the custom handler during pipeline processing

This section describes the pipeline processing for Axis2 handlers, and shows you how to modify the axis2.xml configuration file to instruct the framework to use the custom handler program that you developed.

Axis2 has four different phase orders that indicate what the SOAP message is doing in the Axis2 framework:

  • InFlow -- Inbound SOAP messages
  • OutFlow -- Outbound SOAP messages
  • InFaultFlow -- Inbound SOAP messages with faults
  • OutFaultFlow -- Outbound SOAP messages with faults

Within each phase order, you may have different phases that perform all of the required functions for web service interoperability, ranging from transport-related processing to XML/Java type conversion. The extension point you will use to insert your handler is to define a new phase inside a phase order, as shown below, to invoke the handler that you developed:

Syntax to define a new phase
        <phase name="SymbolicPhaseName">
               <handler name="SymbolicHandlerName"
                     class="your.package.your.class" />
        </phase>

You need to place the configuration described above into a phase order. Pay attention on the position where you declare your phase, because they are executed sequentially. For example, a good fit for a Logger phase for SOAP messages is just after the Dispatch phase, so that you log the exact contents of the envelope that you sent. Similarly, a good fit for adding a custom header is after standard pipeline. See the sample Axis2 configuration below:

Sample configuration of OutFlow phase in axis2.xml
    <phaseOrder type="OutFlow">
        <phase name="soapmonitorPhase"/>
        <phase name="OperationOutPhase"/>
        <phase name="CustomHeaderPhase">
                <handler name="CustomHeaderHandler"
                     class="com.ibm.it.gcre.handler.CustomHeaderHandler" />
        </phase>
        <phase name="LoggingPhase">
                <handler name="LogHandler"
                     class="com.ibm.it.gcre.handler.LogHandler" />
        </phase>
        <phase name="RMPhase"/>
        <phase name="PolicyDetermination"/>
        <phase name="MessageOut"/>
        <phase name="CICSHandlerPhase"/>
        <phase name="Security">
        </phase>
    </phaseOrder>

Conclusion

This article showed you how to develop an Axis2 Java handler for use in the CICS Java web service client pipeline, and provided sample code to develop two handlers.

Acknowledgments

The author would like to thank Tommy Joergensen, IBM Client Technical Specialist in Lyngby, Denmark, for his help in reviewing this article.

Resources

  • Product resources
  • WebSphere resources
    • developerWorks WebSphere
      Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and product manuals.
    • Most popular WebSphere trial downloads
      No-charge trial downloads for key WebSphere products.
    • WebSphere forums
      Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
    • WebSphere demos
      Download and watch these self-running demos, and learn how WebSphere products can provide business advantage for your company.
    • WebSphere-related articles on developerWorks
      Over 3000 edited and categorized articles on WebSphere and related technologies by top practitioners and consultants inside and outside IBM. Search for what you need.
    • WebSphere-related books from IBM Press
      Convenient online ordering through Barnes & Noble.
    • WebSphere-related events
      Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
  • developerWorks resources
    • Trial downloads for IBM software products
      No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
    • developerWorks business process management developer resources
      BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
    • developerWorks blogs
      Join a conversation with developerWorks users and authors, and IBM editors and developers.
    • developerWorks tech briefings
      Free technical sessions by IBM experts to accelerate your learning curve and help you succeed in your most challenging software projects. Sessions range from one-hour virtual briefings to half-day and full-day live sessions in cities worldwide.
    • developerWorks podcasts
      Listen to interesting and offbeat interviews and discussions with software innovators.
    • developerWorks on Twitter
      Check out recent Twitter messages and URLs.
    • IBM Education Assistant
      A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=971190
ArticleTitle=Developing an Axis2 Java handler for the CICS web service client pipeline
publish-date=05142014