Java-based SOAP pipelines

CICS® supports using the Axis2 Java™-based SOAP engine to process web service requests in provider and requester pipelines. Because Axis2 uses Java, the SOAP processing is eligible for offloading to the zEnterprise® Application Assist Processor (zAAP).

Axis2 is an open source web services engine from the Apache foundation and is provided with CICS to process SOAP messages in a Java environment. You can opt to use Axis2 by adding a Java SOAP handler to your pipeline configuration file and creating a JVM server to handle the Axis2 processing.

Enabling Axis2 does not require regenerating the binding files for any existing web services that use the pipeline. The response times might be slower when using Axis2, but you can offload the SOAP processing to zAAP. For more information about offloading to zAAP, see Java support in CICS.

When CICS is a service provider, the Java-based terminal handler uses Axis2 to parse the SOAP envelope for a request message. You can use header processing programs to process any SOAP headers associated with the SOAP message. Axis2 also constructs the SOAP response message. This process is shown in the following diagram:

Request comes into a pipeline that contains a transport handler, service handler, and a Java SOAP handler. The Java SOAP handler runs in Axis2, which in turn runs in a JVM server. The Java SOAP handler also has a header processing program. The request goes to the service provider application and then the response goes back through the pipeline.

When CICS is a service requester, the Java-based initial handler in the pipeline uses Axis2 to generate the SOAP envelope for a request message. You can use header processing programs to process any SOAP headers associated with the SOAP message. Axis2 also parses the SOAP response message.

Web service applications and Java

For provider-mode SOAP pipelines, request and response messages are passed between the terminal handler of the pipeline and the web service application by using an application handler. The application handler processes the body of a SOAP request so that the request can be used by the application. The application handler also generates a response by using the returned data from the application. If the terminal handler of your pipeline is a Java-based message handler, you can specify the supplied Axis2 application handler in the pipeline configuration file, as opposed to specifying the supplied DFHPITP application handler. The application handler processing can then be offloaded to zAAP. For more information about application handlers, see Application handlers.

For requester-mode SOAP pipelines, the web service application invokes the pipeline by using the EXEC CICS INVOKE SERVICE command. The request and response messages are then passed between the web service application and the initial handler in the pipeline. If you specify a Java-based handler as the initial handler in the pipeline, then the EXEC CICS INVOKE SERVICE command is processed by Axis2, making it possible to offload this process to zAAP. If the first handler is not a Java-based handler, then the EXEC CICS INVOKE SERVICE command is processed by CICS.

Axis2 processing in a JVM server

Axis2 requires a JVM server, which is represented by a JVMSERVER resource in CICS. The JVM server is a runtime environment that can handle multiple concurrent requests from different Java programs in a single JVM. The class path for the JVM server must include the Axis2 Java archive files. You can automatically add all of the required JAR files to the class path by specifying the JAVA_PIPELINE option in the JVM profile. The pipeline configuration file must also point to the JVMSERVER resource that is configured to support Axis2.

For more information about JVM servers, see Java support in CICS.

Axis2 header handlers

Although you can use existing header processing programs, it is more efficient to write Axis2 handlers in Java to process the SOAP headers. These handlers can also run in the JVM server and are therefore eligible for offloading. For more information about creating Axis2 handlers, see Writing Your Own Axis2 Module.

A header handler program can use Axis2 APIs to modify or interact with the Axis2 environment, SOAP messages, and individual web services. Do not use these APIs to customize Axis2, as you might change Axis2 in a way that means CICS cannot run the engine correctly. Axis2 handlers are supported only if they interact with the Axis2 environment in a way that is compatible with how CICS uses Axis2.

Axis2 repository

Axis2 uses a repository to store all of its configuration files, services, and modules. CICS provides a default repository in the usshome/lib/pipeline/repository directory on z/OS® UNIX, where usshome is the value of the USSHOME system initialization parameter.

The default repository contains the configuration file, axis2.xml, which is required by CICS to use Axis2. This file is in the /conf subdirectory in the repository. If you create your own repository, you must copy this file to your repository for CICS to work with Axis2.

Do not edit the axis2.xml file, unless you are registering handler programs. This file is managed as an internal part of CICS, so you must not make any other changes to this file unless requested to do so by IBM® support.