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
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
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.
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:
- com.ibm.cics.server.jar: 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.
- 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
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:
- Create a JVM profile and a pipeline configuration file in your environment. Information about how to do this is described in the CICS documentation.
- 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
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
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.
- For more about developing Java-based web services applications, read the IBM Redpaper titled Developing Web Services Applications.
- Find more information about web services development in CICS 4.2:
- Explore the Rational Developer for System z overview and the Rational Developer for zEnterprise page.
- The developerWorks page, which is a great starting place to find articles and other technical information.
- Read through the Information Center, and explore the Rational Developer for System z plug-in for the IBM Education assistant, which includes multimedia modules to watch.
- Other software mentioned in this article:
- Find out more about Rational Application Developer:
- See the Rational Application Developer for WebSphere overview for features, system requirements, ratings and reviews.
- Browse the Rational Application Developer for WebSphere Software page on developerWorks for links to technical articles and many related resources.
- Explore the Information Center.
- Browse the compilers and programming languages pages.
- Explore the Rational software area on developerWorks for technical resources, best practices, and information about Rational collaborative and integrated solutions for software and systems delivery.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, anytime, and many of the Getting Started ones are free.
Get products and technologies
- Download a free trial of Rational Developer for System z.
- Try Rational Application Developer for WebSphere Software, free.
- Evaluate Rational Developer for zEnterprise.
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
- Ask and answer technical questions and exchange information with your peers in the Rational Developer for System z forum and the community hub at the IBM Rational COBOL Café.
- Get connected with your peers and keep up on the latest information in the Rational community.
- Rate or review Rational software. It's quick and easy.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.
Dig deeper into Rational software on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.