Introduction

IBM WebSphere Studio Application Developer Integration Edition, V4.1 (hereafter called Application Developer Integration Edition) provides tools that are based on open standards such as Simple Object Access Protocol (SOAP), Web Services Description Language (WSDL), and Web Service Invocation Framework (WSIF). These tools also have extensive support for J2EE Connector Architecture (JCA), which is vital for access to existing non-relational EIS systems.

In this article, we describe how you can use Application Developer Integration Edition components to create Web services. Using an example that describes how two businesses need to integrate their processes, we demonstrate one approach to Web-service-based business-to-business (B2B) integration, and show how to access existing CICS programs.

Back to top

WebSphere Studio Application Developer Integration Edition

WebSphere Studio Application Developer comes in two flavors: basic, which has tools for essential development work, and Integration Edition, which provides additional support to create larger, enterprise applications.

Basic

Includes everything you need to build standard J2EE applications, such as tools for:

• Writing, debugging and testing Java code
• Developing Web applications, including HTML, JavaServer Pages (JSP) technology, and servlets
• Developing Enterprise JavaBeans (EJB)
• Authoring and working with XML documents

Application Developer Integration Edition

Includes all the basic functions and adds tools specifically designed for enterprise-strength Web services based on B2B integration. The Enterprise Services Toolkit provides innovative tools to maximize productivity of developers, such as:

• A high-level, services-centered programming model (built on top of EJB components) that frees developers from the complexities of EJB programming.
• Tools for service discovery and transaction metadata capture.
• A special editor to work with WSDL files.
• A tool for creating a Java implementation skeleton from a Java enterprise service.
• JCA-compliant resource adapters for transaction-based access to EIS systems.
• A set of extensions you can add to your own resource adapter to make it compatible with Application Developer Integration Edition tools.
• A special perspective in the IDE, the Enterprise Services perspective, to support enterprise application developer activities. The services generated by this perspective are reusable components.
• An editor that lets you work with multiple services and create business logic amongst them.
• A wizard for automated service packaging and deployment.
• A tool for creating a Java proxy to invoke a Java enterprise service.

Application Developer Integration Edition ships with the following JCA-compliant resource adapters:

• CICS ECI resource adapter for access to programs on CICS servers
• CICS EPI resource adapter for access to 3270 programs on CICS servers
• HOD 3270 resource adapter for access to host systems with 3270 screens
• IMS resource adapter for access to IMS programs on IMS servers

You can use these development resource adapters to develop and test an enterprise service, but when you deploy to a production environment you'll need to license run-time resource adapters.

Suppose you have a resource adapter that is not listed above. Application Developer Integration Edition also has some extensions collectively called the JCA plug-in. The extensions can be added to any existing resource adapter that is compliant to the JCA. Once added, your resource adapter becomes compatible with the Application Developer Integration Edition development tools. The article "Enabling a J2EE Resource Adapter" in Resources provides more information on these extensions.

Figure 1 shows the relationship between Application Developer (basic) and Application Developer Integration Edition components.

Integrating EIS systems in a service

To integrate programs on EIS systems (often, you'll find these in legacy applications), you typically have to follow these steps:

1. Import the program source (for example, a COBOL copybook) and generate metadata describing the input and output of the program. The generated WSDL code is serialized.
2. Generate EJB-based deployed code for the service, including code that acts as a proxy for the legacy program.
3. Create WSDL service definitions describing the service that will invoke the transaction. The service definition will let you invoke the deployed service, either from the unit test or the production environment.
4. Unit test the service, and deploy it to the production environment.

In the next section we'll expand on these points by using a case study involving both B2B and enterprise integration.

Back to top

Case study: Travel Simplified

Travel Simplified is a fictitious travel agency that wants to develop a Web site for its customers. The Web site can be accessed by any Internet user using a browser. The site must support the following use cases:

• A user logs on and browses available services on the site.
• The site generates travel options based on starting and destination points and times provided by the user.
• The user makes airplane, bus, and train reservations.
• The user completes the transaction by supplying a credit card number.

Figure 2 shows the collection of services (provided by other organizations) and EIS systems that Travel Simplified needs to access and integrate to support the required use cases.

The primary goal, and challenge, for developers of the Travel Simplified Web site is to create a seamless view from a customer perspective. Customers using the Web site should not be aware that a service is getting data from other organizations operating different EIS systems. Web services provide the ideal and uniform B2B integration story.

Figure 3 shows the Travel Simplified Web site architecture.

Back to top

Building the provider: Simplified Airlines

Before Travel Simplified can offer an airline reservation service to customers, someone has to provide this service. One of the providers is Simplified Airlines, a fictitious airline that decided to make its reservation system available to business partners over the Internet. Figure 4 shows the Simplified Airlines Web site architecture. Applications written by this company's business partners can access Simplified Airlines services over SOAP and HTTP protocols.

The Simplified Airlines IT infrastructure is built around a mainframe running COBOL programs under CICS. These programs provide functions that the company needs to expose to its business partners, such as:

• Looking up reservation information by reservation number
• Booking a reservation
• Cancelling a reservation
• Changing reservation information (date, time, flight number)

These functions form the basis for the Simplified Airlines service interface. In the following sections we'll focus on how to integrate a single function -- one that allows reservation look-up by reservation ID. Steps for incorporating other functions are identical. The transaction name is RESBYID. We'll access this function using the CICS ECI protocol. We'll also make sure that our new service is accessible over the Internet using the SOAP protocol.

The following are steps we took to build and test our service using Application Developer Integration Edition. Each step is explained in more depth as we go through the example:

• Create a CICS ECI service
1. Create a service project
2. Import a COBOL or C file
3. Create a CICS ECI service definition
4. Generate an inbound channel for the service and deployed code
• Testing your service using a SOAP proxy
1. Create the SOAP proxy for the service
2. Test the service with client code

Back to top

Creating a CICS ECI service

The first series of tasks in an enterprise service involves defining the service. Defining your service means creating a project for it and creating a WSDL file specifying details, such as the namespace and port type (interface) name. You also need to specify connection factory information, because it is used to establish the connection between the WSDL service and the CICS server. Then you populate operations in the WSDL file by importing CICS COBOL or C programs that contain the structure for input and output at the CICS server.

Creating a service project

Starting Application Developer Integration Edition launches an Enterprise Services perspective by default. A perspective is like a frame of reference. In the services navigation, three folders are displayed:

• Service Projects -- the list of enterprise services you have created.
• Deployed Services -- the list of services you have deployed.
• Resource Adapters -- the list of resource adapters that can be used to access different EISs.

To begin creating a service, launch the Service Project wizard and supply a project name. Once this wizard finishes, the Service Providers Browser tool is launched (as shown in Figure 5 below). This tool is the starting point for service creation tasks. For example, selecting the CICS ECI link would guide you to the tools to create a service accessing CICS ECI programs.

Importing a COBOL or C file

When defining an operation for a CICS ECI program you import the COBOL or C files to define the input or output message in WSDL. The COBOL or C files must be imported from the local file system into your workbench before you try to define the operation.

Application Developer Integration Edition makes importing easy. Select your newly created project and click the Create a Java package icon on the Application Developer Integration Edition toolbar. Once the package is created, use the import function to bring in your COBOL or C files. After you've imported your COBOL file to the workbench, you can develop your service definition.

Creating a CICS ECI service definition

Creating a CICS ECI service definition is the heart of the work in developing an enterprise service, and Application Developer Integration Edition has tools to make it as simple as possible.

You begin by selecting CICS ECI from the list of service providers, as shown in Figure 5 above. A service definition is described by a WSDL file generated by Application Developer Integration Edition. (See the WSDL specification in Resources for details on WSDL.) In a nutshell, it uses XML to define services. A service definition created in WSDL describes the format of system requests regardless of the run-time implementation. The service definition describes where the service is deployed and the operations available to an application consuming the service.

Selecting CICS ECI as the service provider opens a connection properties page. You fill in the connection values for your specific CICS server, as shown in Figure 6.

Selecting Add Service directs you to fill in names necessary for WSDL, such as a namespace, which is a unique, logical namespace for your service and a port type, which groups related operations. The namespace is used to generate the Java package. For example, if the namespace you specify is http://sample.ibm.com/, the Java package for generated code will be the inverse com.ibm.sample.

You are given some flexibility in using the tool. For example, you may choose to put your generated XSD schema inline -- within the WSDL file created or separate from it. When working with the COBOL or C importing tools, the XSD schema for the types are always inline. Figure 7 shows the page with the folders and names of your service.

After completing the Add Service function, a WSDL implementation (service) and interface file is created. The implementation WSDL file is opened on the Binding page of the WSDL editor. Normally you would group related operations in a port type (for example, group all operations for performing queries and updates on a bank account). From the Binding page, you can define the operations for each CICS ECI program you want to access. You can do this by creating a new operation, which will populate the interface WSDL with an operation in its port type, messages, and XSD types, and the implementation WSDL in the appropriate binding with a matching operation, typeMap, and marshalling information for each type.

When creating the operation, the first step is to specify ECI operation binding properties. These properties map to the properties of the ECI interaction specification (ECIInteractionSpec), and contain the details your service will need to know to exchange input and output information with the CICS server (stating the function name that identifies the CICS program to invoke at the CICS server). Then you need to create input and output messages in WSDL that will map to input and output operations to the CICS program. The combination of these steps will create the means whereby a CICS transaction can be invoked.

Within the service definition, Application Developer Integration Edition has a tool that lets you associate a WSDL operation with the COBOL structure you imported earlier. Begin by using the tool to identify the function name, as shown in Figure 8.

Proceed to create a service operation, specifying a name for the operation. The name usually reflects the action of the function. We used getReservationInfo because we were looking up reservation data. You can define input and output messages by using the Import function and selecting the file you imported to the workbench earlier; it contains the input and output types for the function. With the COBOL or C file identified, the tool then gives you the opportunity to specify any platform-specific properties such as code page, floating-point format, endian-ness and so forth, as shown in Figure 9.

Once you've specified platform properties, select the COBOL Level 1 or C structure commarea your service will use from the COBOL or C file. Your service definition is almost complete, but the tool gives you several options. For example, you can choose to use your input message as an output message too. In the case where the CICS program can return different output data, you can create multiple possible outputs for your operation.

As a final step, the tool populates the implementation and interface WSDL files with the operation, input and output messages, and types. Application Developer Integration Edition presents the code in a visual format as shown in Figure 10; you can also view it as WSDL source code. Note that Application Developer Integration Edition has obviously (under the covers) handled the marshalling code for you. The data from the CICS server at run time will be put into a stream suitable for transport over a network, and it can be unmarshalled when necessary.

Deploying the service to the test environment

Deployment has two aspects: packaging your service files into an enterprise archive (EAR) file, and placing that EAR file onto an application server. Often both aspects are called deploying to an application server. Application Developer Integration Edition has tools to make deployment simple. You begin deployment by creating an Enterprise Application Project, which defines the structure of an EAR file. You can put some of your deployed code into an EJB section, some into a Web section, and some into a client code section. In large EAR files, this division helps you manage your files.

Once you have the structure of your EAR file defined, select the binding file created previously and click on a deployment wizard from the toolbar. While packaging your files into the EAR, Application Developer Integration Edition supplies most of the information you need in defaults, but lets you override them where necessary. For example, because we also want to expose the CICS service as a SOAP service, we selected SOAP as the inbound binding type (as shown in Figure 11).

At this point you also need to specify the Java Naming and Directory Interface (JNDI) name, which the application server needs to know at run time when making a connection to the CICS server. Also, you might want to adjust SOAP-specific binding properties. Usually, you'll use the default values.

Once all of the functions have been integrated in this manner, creating the Simplified Airlines site is essentially complete. All that remains is to deploy the service to the test or production environment. We say test environment because Application Developer Integration Edition offers a complete test environment that emulates an application server. It's a good idea to use the WebSphere Test Environment before deploying to the production environment. After testing, you put your EAR file into the production environment. Whether a test or production environment, you next need to create a proxy that the application uses to indirectly access the service.

Back to top

Integrating Simplified Airlines with the Travel Simplified site

We now have the airline reservation service and need to integrate it in the overall travel agency service; we are creating a service within a service. We created the proxy to represent the service at the server on the client.

Creating the SOAP proxy for a service

A proxy provides a remote procedure call interface to a service of interest. The application invokes the local method on the proxy. The proxy handles the communication with the server. As you may have guessed, Application Developer Integration Edition provides a tool that builds the proxy for you. To integrate the Simplified Airline service into the Travel Simplified site, you would need to get the WSDL files that define the interface and SOAP binding information for that service. You can do this with a Universal Description, Discovery and Integration (UDDI) registry, which makes these files available publicly. It can also be done by establishing direct contact with the organization of interest. The deployment step above generated the WSDL file in the Services_SOAP Web project of the Enterprise Application Project. The next step is to simply run the proxy wizard.

Similar to the deployment wizard, many of the fields are completed for you, as shown in Figure 12. One field you will likely change is Destination folder, because it determines where the proxy goes. In our case we chose the ClientSample folder because that folder contains the client code that invokes the service.

One key part of the proxy information is, of course, the operation you will invoke at the server. Your service might offer many operations; in the proxy you choose which operations will be exposed for an application to access. If you need to choose one or more, you need to use a "client stub" style proxy, which is the preferred style of generation. If you need access to the binding operation properties, such as the the interaction specification (interactionSpec), the style to choose is Command bean, as shown in Figure 13.

Testing the Simplified Airline service with client code

At this point you would write some client code to call the SOAP proxy and run it on the WebSphere Test Environment. Our code, shown below, retrieved a name from the CICS server and output it to the console (standard out). It's a good idea to write such a simple program initially, just to prove you can get some data from the server. If you can't get one transaction to work, your application will never get thousands of them.

package sample.cics;
public class TestCustomerSOAP {
   public static void main(String[] args){
      try { 
         Customer record = new Customer();
         record.setCustomernumber("44444");
         CustomerInfoSOAPProxy proxy = new CustomerInfoSOAPProxy();
         proxy.setCustomerPart(record);
         proxy.execute();
         record = proxy.getCustomerPart();
         System.out.println(record.getCustomernumber());
         System.out.println(record.getFirstname());
         System.out.println(record.getLastname());
     } catch (Exception e) {
          e.printStackTrace();
     }   
  }
}

Once you're satisfied that the proxy method call returns the correct data, you can readily integrate this bean into the rest of the application, which in our case is the overall Travel Simplified Web site.

Back to top

Conclusion

In this article we demonstrated how existing CICS programs can be rapidly integrated into complex B2B applications using Web services, SOAP, and XML. We looked at IBM WebSphere Studio Application Developer Integration Edition, a product designed specifically for creating Web service-based, enterprise, and B2B integration applications. We examined its components, then explored a case study showing how Application Developer Integration Edition tools can be applied to realistic B2B problems. The old folks and the young whippersnappers worked together in a grand fashion.

Resources

• Participate in the discussion forum.
  
  
• Read "Enabling a J2EE Resource Adapter using the JCA Tool Plugin - Part 1: Introducing the Architecture" (WebSphere Developer Domain, May 2002).
  
  
• Check out two good articles from the Web services zone: "Web services invocation sans SOAP" (developerWorks, September 2001) and "The architecture of Web Service Invocation Framework" (developerWorks, September, 2001).
  
  
• Refer to the Web Services Description Language (WSDL) specification.
  
  
• Check our references: Building Web Services with Java by Steve Graham, Simeon Simeonov, Toufic Boubez, Doug Davis, Glen Daniels, Yuichi Nakamura, and Ryo Neyama (Sams Publishing, 2002) and J2EE Connector Architecture and Enterprise Application Integration by Rahul Sharma, Beth Stearns, and Tony Ng (Addison-Wesley, 2001).
  
  
• Visit the WebSphere Studio Application Developer Integration Edition Web site.
  
  
• Download a trial version of the basic edition for Windows or for Linux
  
  
• You can get information, sample code, and trial downloads tailored for developers who use WebSphere products from WebSphere Developer Domain.
  
  
• You might be interested in this tutorial from WebSphere Developer Domain: "Integrating Web services applications with WebSphere Studio."
  
  

About the authors

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• The product
• Case study: Travel Simplified
• Building the provider
• Creating a service
• Integrating
• Conclusion
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community