Develop a CICS Java-based Axis2 web service

A meet-in-the-middle approach to services development

IBM CICS Version 4.2 introduced support for Java-based Axis2 web services, which enables services to be developed in Java and supported through an Axis2 pipeline to interface with CICS COBOL applications. Amy Silberbauer provides an alternative for web services development when starting with complex service definitions in WSDL, using Rational tools. She focuses on a meet-in-the-middle approach, whereby services interfaces are generated from the WSDL, and services implementation remains in the CICS COBOL business applications. This provides a complete, multiplatform solution to services development.


Amy M. Silberbauer (, Executive IT Specialist, IBM

Photo of SilberbauerAmy is currently the Functional Design Lead on the Rational Design Factory team. In this role, she focuses on the design of complex, multiplatform IT scenarios and solutions supported by Rational. She specializes in enterprise modernization, service-oriented architecture (SOA), and industry-focused solutions. She has been with IBM for 25 years.

18 December 2012


Many organizations are looking for ways to improve or modernize software application architectures to reduce costs, improve efficiencies, and respond more flexibly to changing requirements and gain a competitive business advantage. At the same time, there is a desire to preserve existing, often significant investment in existing business-critical applications. One common way to achieve these goals involves service enablement, a software development activity whereby you expose the capabilities of the existing applications so that they can be used through modern interfaces, yet keep the current functionality.

Service enablement of existing business applications often involves mixing traditional and modern software application technologies, such as structured and object-oriented programming languages and environments. This is not easy, and sometimes is not technically possible. Tools exist that simplify the development of web services, focused on three basic approaches: bottom-up, top-down, and meet-in-the-middle. This article describes the basic steps in developing a web service, supported by modern tools, following the meet-in-the-middle approach. The result is a web service implemented as an IBM® CICS® Java-based Apache Axis2 application developed from a service interface described in WSDL (Web Services Definition Language). The service provider is an existing CICS COBOL business application. Access to the business application is through the COMMAREA, although this framework also supports access through channels or containers.

The tool used to develop the service components is IBM® Rational® Developer for zEnterprise®, Version 8.5. The Java support is provided by capabilities in IBM® Rational® Application Developer, used within Rational Developer for zEnterprise. This combination provides multiplatform development capabilities, including the ability to develop CICS applications.

IBM® CICS Transaction Server for z/OS®, Version 4.2, is the run time environment that provides the Axis2 service pipeline infrastructure. This article is based on the assumption that you have a basic understanding of web services, the means of articulating them through WSDL, as well as a working knowledge of CICS, COBOL, and Java technologies.

A closer look at the tools

The IBM tools provide excellent support for the development of traditional CICS web services, but there are several reasons that you might want to consider the less traditional Java Axis2 approach:

  • You have skills in your organization that can be leveraged to develop Java-based web services
  • You have experience with Axis2 web services on other platforms and want to create web services in CICS
  • You have complex WSDL documents that would be difficult to handle by using the CICS web services assistants that are provided by the software
  • You want to offload the handling of the web service application to the IBM zAAP (Application Assist Processor)

IBM CICS Transaction Server V4.2 introduced support for Java-based Axis2 web services. This support enables services to be developed in Java and supported through an Axis2 pipeline to interface with CICS COBOL applications. Axis2 is an open source web services engine from the Apache foundation and is included with CICS.

CICS web service reference architectures

Figure 1 shows a traditional CICS web services reference architecture, taken directly from CICS documentation.

Figure 1. Traditional CICS Web Service Architecture
CICS service architecture for COBOL application

This architecture relies on CICS to provide the web services infrastructure through resources for WEBSERVICE, PIPELINE, and URIMAP. As such, the web service can take advantage of all support that the CICS web services infrastructure offers. The downside of this architecture is that it does not support complex service interfaces that must map to existing, more structured COBOL applications.

In contrast, Figure 2 shows the Java-based Axis2 service reference architecture.

Figure 2. Java-based Axis2 web service architecture
CICS Axis2 service architcture with Java and COBOL

The illustration in Figure 2 highlights the differences between the traditional CICS web services architecture and the Axis2 architecture, showing new Java-based application components that are communicating with COBOL business logic. This architecture supports both HTTP and IBM® WebSphere® MQ for transporting the SOAP-based request and the response. It relies on the CICS PIPELINE and URIMAP resources, but it does not include the CICS WEBSERVICE resource. Instead, Axis2-style applications interact with CICS by using the Axis2 programming model. As a result, Axis2 services cannot take advantage of some of the native CICS web services support capabilities, but they provide the following benefits:

  • A simplified overall service provider/requestor architecture
  • Platform independence for the Java-based service provider and service requester applications
  • The ability to generate much of the application source through standard tooling available in IBM Rational Developer for zEnterprise
  • The use of standard APIs provided by CICS to support Java and COBOL modules

As with the traditional web services architecture provided by CICS, the one based on Axis2 still provides the ability to extend existing COBOL business logic through a services interface. In this case, though, the supporting components are developed in Java. Each architecture has a place in an organization's software application infrastructure. Therefore, weigh the benefits of each when you are choosing one over the other for any specific web services development activity.

Developing Web Services

Rational Developer for zEnterprise is recognized as a mainframe development tool for COBOL and PL/I, but it can be invaluable in supporting multiplatform development activities, such as those related to the development exercise described here. There are three web services development approaches supported by Rational Developer for zEnterprise:

  • Bottom-Up: Create a new service interface in WSDL from a high-level language data structure, thus exposing an application program as a service provider.
  • Top-Down: Create a new service implementation from an existing service description in WSDL to establish a new service provider, to expose an existing application program as a service provider, or to construct a new service requester.
  • Meet-in-the-Middle: A combination of bottom-up and top-down that defines mappings between high -level language data structures and web services definitions WSDL, XSD, or XML files.

Java-based Axis2 web services can be developed by using any of these approaches. This article focuses on the meet-in-the-middle approach to develop a service provider application for a service interface that is described in a WSDL file. This approach assumes the following conditions:

  • You have an existing service interface that is described in WSDL.
  • You have existing business logic that you want to expose as the service provider (or service implementation) for the service interface.

Meet-in-the-middle approach

As depicted in Figure 2, Java-based Axis2 web service architecture, the meet-in-the-middle approach is used to develop a Java-based Axis2 application with two programs to provide the service implementation through an existing COBOL program:

CICS Java data binding
This is a Java J2C (J2EE Connector architecture) mapping component that is generated from the COBOL business logic. It has two purposes:

  • To map Java objects that are passed through the service request to CICS COBOL COMMAREA data structures used to communicate with the existing COBOL program
  • To pass the service response back from the COBOL program to the Java objects. Alternatively, you can create a mapping that interfaces with the existing COBOL through a Channel or Container.

The basic steps are essentially the same, although some customized programming might be required. The means of generating this program is provided in Rational Developer for zEnterprise through the J2C > CICS/IMS Java Data Binding.

Java-based Axis2 web service
This is a Java JAX-WS program that is generated from WSDL to process a service request that is based on the service interface described in the WSDL. The means of generating this program is provided in Rational Developer for zEnterprise through the Service Component Architecture 1.0 > JAX-WS Interface wizard.

A summary of the steps required to develop a Java-based Axis2 web service follows. The service interface component is generated from an existing WSDL that describes the service interface (top-down), and the data binding component is generated from an existing COBOL program (bottom-up).

Create a Java project to develop your Java Axis2 service

In the Rational Developer for zEnterprise client, create a new Java project that includes the libraries that are required to build a CICS Java Axis2 service:

  • Java class library for CICS (JCICS) APIs
  • javax.j2ee.connector.jar: J2C support classes
  • marshall.jar: J2C support classes

The J2C support classes are included with many products. In our test environment, they were part of IBM® WebSphere® Application Server. The JCICS API classes come with CICS. All of these JAR files must also be available in the class path on the host system for the Java virtual machine (JVM).

Generate the CICS Java data-binding component

Generate the CICS Java data-binding application from your existing COBOL program by using the J2C > CICS/IMS Java Data Binding wizard.

The COBOL program provides the service implementation on the host system. In this step, you use the COMMAREA definition in that program to create a CICS Java data binding. This CICS Java data binding provides a simple bridge between the get or set method in the object-oriented world of Java and the series of bytes-oriented world of COBOL and other non-object-oriented languages or environments.

The get and set methods in the generated Java classes correspond to fields in the COBOL data structures. You will use those methods from your Java web service to set and access various fields in the COMMAREA. When you want the EBCDIC series of bytes that equates to the COBOL data definition, you can use the getBytes() method. If you are starting with data in the COBOL data definition layout, you can use the setBytes() method to place the data into this generated data object. Then you can use the get or set methods from your Java program to access the data.

Generate the JAX-WS Java Axis2 web service implementation

Generate the Java Axis2 web service from your existing WSDL by using the Service Component Architecture 1.0 > JAX-WS Interface wizard.

The Java classes will be used in an Axis2 environment to provide data parsing and other Axis2 support for your web service. From these generated classes, you also develop a service implementation class that provides these abilities:

  • Process a service request.
  • Translate the request input into the format that is required by the COBOL program that is providing the service implementation.
  • Process the request output from the COBOL program into Java objects.
  • Return the response to the service requester.

Create a JAR file that represents your Java Axis2 web service application

Create a JAR file containing your Java application that includes both the CICS Java data binding classes and the Java web service implementation. This JAR file resides on the host system in a CICS Axis2 infrastructure so that CICS can process the service request.

Define the z/OS CICS environment for Java Axis2

CICS provides Axis2 support through a combination of CICS resources that are defined to process service requests, as well as an Axis2 "repository." The repository is nothing more than a directory on the z/OS UNIX System Services file system on z/OS, where CICS can find the Java service implementation application and other Axis2 configuration information. The CICS documentation that is cited in the Resources section includes details about setting up the CICS Resources and the Axis2 repository. The basic steps are summarized here.

  1. Create an Axis2 repository on the hierarchical file system under z/OS UNIX System Services on your host system. CICS provides a sample Axis2 repository directory structure that can be copied to create your own. Figure 3 provides an example.
    Figure 3. Example of an Axis2 repository
    a z/OS UNIX System Services directory
    The /servicejars directory contains your uploaded JAR file. You tell CICS where to find this through the configuration information that is specified in the /conf /axis2.xml file. The remaining directories can be left as-is, assuming that you have created this structure by copying the sample that is provided by CICS.

    In addition to the Axis2 repository directory structure, you might also need to provide a directory that contains the J2C JAR files that are required to run your Java application:
    • marshall.jar
    • javax.j2ee.connector.jar
    You might need to consult a CICS administrator to determine where CICS loads application JAR files, but the directory must be specified in the CLASSPATH_SUFFIX in your CICS JVM server profile.
  2. Create a JVM profile and a pipeline configuration file in your environment. Information about how to do this is described in the CICS documentation.
  3. Define and install the CICS resources:
    • A CICS JVMSERVER resource to run your Java services
    • A CICS Axis2 PIPELINE resource to manage your Axis2-based Java services
    • A CICS URIMAP to define your Java service URI
    • A CICS PROGRAM resource for the CICS COBOL business application
    You will have one Axis2 repository for each CICS JVMSERVER resource and one JVMSERVER resource for each PIPELINE resource. This means that, in support of your CICS Java Axis2-based services infrastructure, you will have a JVMSERVER and a PIPELINE. For each service you define that has a unique URI, you will have a URIMAP resource defined with the URI for that service. You can define and install these resources through Rational Developer for zEnterprise through the CICS Explorer feature.

Test your new Java Axis2 service

You are now ready to run a test to execute your new service. In the Rational Developer for zEnterprise client, you can use the Generic Service Client to test the service. You launch the test from the WSDL file that defines the service interface. Make sure that you have correctly specified the port information to enable your client to communicate with the host system where you installed the service implementation application. Figure 4 shows an example of how to do that.

Figure 4. Specify the URL for the service request
Specify the service URL on the Transport page


You have now exposed a CICS-based COBOL program as a web service by using a meet-in-the-middle approach and implemented a Java Axis2-based application that is derived from the WSDL.


Many thanks to my teammates Mitch Johnson and Dennis Weiand for their technical contributons to the content of this article. Their guidance and reviews were invaluable in developing the content and ensuring the accuracy of the solution. Many thanks also to the editorial staff on the developerWorks team for their great work in preparing the article for publication.


Lab instructionsCICSJavaAxis2Meet-in-the-MiddleLab1626KB
Lab filesCICSAxis2Lab50KB



Get products and technologies



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 Rational software on developerWorks

Zone=Rational, DevOps
ArticleTitle=Develop a CICS Java-based Axis2 web service