IBM® Rational® Application Developer V7.0 has offered a substantial improvement in user experience for many application development tools, including the Java™ 2 Platform, Enterprise Edition (J2EE™) Connector (J2C) suite of tools.This article will highlight some of these improvements, while demonstrating how, as a J2EE developer, you can utilize Rational Application Developer V7.0 to generate a J2C bean that allows access to functions provided by backend IBM® IMS™ (Information Management System).
In the current world of service-driven business applications, it is also very important to make sure that Enterprise Information System (EIS) functionality (surfaced through a J2C bean) is easily accessible by various components of the complicated business ecosystem. To demonstrate how such service-driven access to the EIS functionality can be implemented, this article will also show you how to create a Web service that accesses the IMS functionality through a J2C bean.
To follow this article in a "hands-on" fashion, you should have the following set up:
- Rational Application Developer V7.0 with J2C tools and IBM® WebSphere® Application Server V6.1 installed on the developer's machine
- The PhoneBook IMS transaction (IVTNO), which is one of the Installation Verification programs that comes with your IMS.
- The sample COBOL program saved on your file system--see the Download section.
This article assumes the following scenario: you have a Phonebook program that runs on IMS. You want to expose the functionality of this program through the Web service. However, you have a requirement that input parameters for your application should be not only the input data required by the back-end system operation, but also IMS interaction property
The article will show how this scenario can be implemented by following these steps:
- Generate Data Binding classes corresponding to COBOL input and output data structures.
- Generate a skeleton J2C bean capable of accessing IMS.
- Create a J2C bean method responsible for invoking PhoneBook operation on the backend IMS.
- Create a Web service to expose functionality provided by the generated J2C bean.
- Test the created Web service using the Web Service explorer.
Task 1: Generate Data Binding classes corresponding to COBOL input and output data structures
Data binding classes are one of the key artifacts required to access the functionality of an EIS system. In this case, you have IMS on the backend, where the PhoneBook application is running. This application expects certain input data, and produces certain output data. The tricky issue, though, is the fact that the PhoneBook application expects the data structures to be defined in COBOL language.
A J2C bean, however, operates in the Java universe and expects all the data to be specified as Java classes. Therefore, you need to generate a Java representation of COBOL data structures, which could be used for accessing the functionality of an IMS application. For the purposes of this article, you will generate Data Binding classes required to run the PhoneBook application on IMS.
To do so, you have to perform the following steps.
- Click New > Other > J2C > CICS/IMS Java Data Binding wizard, as shown in Figure 1.
Figure 1. Data Binding wizard launch
On the fist page of the Data Binding wizard, you have to select the backend system language for the data structure that you want to map to Java.
Currently available mappings are:
- COBOL to Java, which allows you to create a Java representation of the data structure defined in COBOL
- COBOL MPO to Java, which is similar to COBOL to Java, but allows usage of the COBOL data structure with multiple possible outputs
- PLI to Java, which allows you to create a Java representation of the data structure defined in PL1
- PLI MPO to Java, which is similar to PLI to Java, but allows usage of the PL1 data structure with multiple possible outputs
- C to Java, which allows you to create a Java representation of the data structure defined in C
- For the purposes of your scenario, you select the COBOL to Java mapping, as shown in Figure 2.
Also select the COBOL file on the file system provided with this article and click Next.
Figure 2. Mapping selection in the Data Binding wizard
- On the next page of the Data Binding wizard, you need to specify the parameters specific to the properties of the
back end system (in your case, IMS) on which the COBOL program is running. Since your IMS machine is running IBM® z/OS®, you select it as the target platform, as shown in Figure 3.
Figure 3. Setting backend system specific properties in Data Binding wizard
- Once the backend system-specific parameters are specified, you should select the data structure that will be
mapped into the Java representation. To do that, click Query, select INPUT-MSG
data structure, and click Next, as shown in Figure 4.
Figure 4. Select desired data structure
- On the last page of the Data Binding wizard, you have to specify the project and package where you want to generate
INPUTMSG java class, which represents the INPUT_MSG COBOL data structure in the Java universe. In this example, generate
that class in IMSJavaProject project, as shown in Figure 5.
Figure 5. Specifying code gen destination
At this point, you have a Java class that represents the input data structure for the IMS program. However, you also have to generate the class that represents output data structure of the IMS program. To do this, repeat the previous 5 steps with the exception that you specify OUTPUT-MSG as the desired COBOL data structure and generate OUTPUTMSG class into the same project and package into which you generated INPUTMSG class.
After you follow these steps you will have the following two files, shown in Figure 6, in IMSJavaProject.
Figure 6. IMS Java project structure
At this point you come to the end of Task 1. You now have Java classes in your workspace that provide Java representation
of the data structures required to run the PhoneBook operation on the backend IMS.
Now you need to produce some code that knows how to connect to the IMS. Task 2 shows you how.
Task 2: Generate a skeleton J2C bean capable of accessing IMS
One of the most important tasks that the J2C bean should be able to do is to know how to connect to the specific backend system.
- Bring up the J2C Java Bean wizard shown in Figure 7 and see what information you should provide to generate a skeleton J2C bean.
Figure 7. New J2C Wizard
On the first page of the wizard, you see a list of adapters that can be used to generate a J2C bean. Rational Application Developer V7.0 ships with 2 IMS and 2 CICS (for 1.0 and 1.5 versions of J2C Architecture specifications) adapters. For the purposes of this article, you will use the IMS adapter (for 1.5 version of the J2C specification), which is shipped with Rational Application Developer V7.0.
- When you select the IMS adapter, as shown in Figure 8, you see a graphical representation of the scenario for which the code will be generated.
The J2C wizard generates a J2C bean, which will have enough information to access IMS through the specific IMS adapter. Also, you can later use the generated J2C bean to generate such J2EE artifacts as Session Enterprise JavaBeans™ (EJB™), JavaServer Pages™ (JSP™), and Web services. Later in this article, you will create a Web service that uses the generated J2C bean.
Figure 8. Select IMS adapter
- If the selected resource adapter is not in the workspace already, it will be imported into the current workspace after you click the Next button. During the import you might see the progress indicator shown in Figure 9.
Figure 9. Importing the IMS adapter
The next page of the wizard gives you the ability to input the information that will be used to connect to the underlying EIS system using the chosen J2C resource adapter. This information is backend-system specific. There are three ways that this connection information can be specified:
- Providing managed connection information
- Providing non-managed connection information
- Providing a combination of both
What are the differences between these three?
- Managed connection means that the application server manages the lifecycle of the connection (3-tier model). Managed connection is specified by the Java™ Naming and Directory Interface (JNDI) name of the managed connection factory defined on the application server. The managed connection factory is EIS adapter-specific, and contains all of the required connection information. Managed connection implies that the resource adapter is installed directly on the server and, therefore, the JNDI name of the managed connection factory is visible to all EARs (enterprise application archive files) installed on the application server.
- Non-managed connection implies a two-tier model in which the application communicates directly to the EIS and manages all the connections itself. Therefore, all the connection information in this setup is encapsulated within the application. In the case of a J2C bean, this means that all of the connection information is specified with doclet tags in the generated J2C bean.
- A Combination of these approaches means that the client will first try to fetch a managed connection factory from the server using the provided JNDI name and, if this is not successful, it will use information defined for the non-managed case.
Best practices for J2C development include using a managed connection, because it allows you to leverage capabilities of the application server and to develop complex multi-tier systems. It also provides better resource re-use because connection factories defined on the server can also be used by other applications.
J2C tools allow for a convenient way to define a new (or select an existing) managed connection factory on the server.
- To do that, you specify the JNDI resource name for the managed connection factory that you want to create and
click New, as shown in Figures 10 and 11.
Figure 10. Create a new managed connection factory
As mentioned before, a managed connection implies that the corresponding resource adapter is installed on the server in stand-alone mode (in other words, it is visible to all EARs installed on this server). If the resource adapter is not installed on the server instance that you specified, the J2C tools will automatically install a resource adapter on the server in the process of creating the managed connection factory.
Figure 11. Select server instance
Once the server instance is specified, you have to specify the values for IMS specific properties that are required for successful connection to your IMS machine.
- After you click Finish button J2C Tools will try to create specified managed connection factory on the server instance, as shown in Figure 12.
If the selected WebSphere v6.1 instance is already started, the managed connection factory will be created right away. If the server is not started, the creation of the managed connection factory will be postponed until the next time that the server is started and its configuration information is republished. This is a significant usability improvement in comparison to prior versions of the J2C Tools in Rational Application Developer, when the startup of the server was mandated.
Figure 12. Creating managed connection factory
- Now you are ready to proceed to the next page of the J2C wizard, on which you need to specify the project and package where the code for the J2C bean will be generated, as well as the actual names for the J2C bean implementation and interface files.
For the purposes of this article, you will generate the J2C bean in the same project where you generated the Data Binding classes. It will be best if you use the names shown in Figure 13 to be consistent with the naming conventions used later in the article.
Figure 13. Java properties of J2C bean
- After you click Finish, the J2C wizard generates code that is able to connect to the IMS. Let's look at how this information is presented in the generated J2C bean. If you open the generated J2C bean, you will see that the JNDI name of the managed connection factory is specified in the doclet tag within the code.
Figure 14. JNDI name in the doclet tag
- Scroll down and you will also see that the doclet annotation builder used the information specified in the doclet tag
to create the snippet of code that will be responsible for connection to the IMS, as shown in Figure 15.
Figure 15. JNDI name in the generated code
Now, start the instance of the WebSphere v6.1 server which you specified while creating the managed connection factory,
and open the Administration Console for this server, you will see the proper managed connection factory defined there
Figure 16. JNDI name in server administration console
At this point, you have the J2C bean that knows how to connect to the IMS, and you have the Data Binding classes that represent the data required to run the PhoneBook IMS application. In the next Task, you will see how you can define the Java method in the J2C bean, that will be responsible for invoking the PhoneBook operation on IMS.
Task 3: Create the J2C bean method responsible for invoking the PhoneBook operation on the backend system
- To add a new method to the J2C bean, open the J2C bean implementation Java class, right click anywhere in the
source of the Java class, and select Source > Add Method to J2C bean, as shown in Figure 17.
The other way to add J2C method is using the corresponding J2C snippet from the Snippets view
Figure 17. Add a new J2C method from the context menu
- Once the New Java Method dialog comes up, click Add to add a new method, as shown in Figure 18.
Figure 18. New J2C method dialog
- There are number of things you need to specify to define a Java method that will correspond to the backend operation
of the EIS system. First, you have to specify the name of the method, as shown in Figure 19.
Figure 19. New J2C method name
- Second, you need to specify the input and output types for the method. These types are the Data Binding types that you created
in the Task 1. Therefore, you just need to use the Browse button to select these classes, as shown in Figure 20.
Figure 20. Browse for input and output types for the new J2C java method
- Once you specify the input and output types, click the Next button.
- On this page of the wizard, you can specify the interaction and connection specification properties, associated with the execution of the EIS function, that you want to expose as the input arguments of the business methods in the J2C bean. For the purpose of this article, select to expose the
executionTimeoutinteraction specification property, as shown in Figure 21.
Figure 21. New method
When you select the corresponding property, you can see the change in the method signature at the top of the page. The ability to specify this information through the UI is one of the many improvements in the J2C tooling of Rational Application Developer V7.0 in comparison to previous versions.
Note that the UI field corresponding to the
executionTimeoutproperty in the New Java Method dialog is shaded. This is because the hardcoded value for this interaction property cannot be provided now, since the value is provided through the argument of the Java method.
- For the purposes of this article, define only one business method for J2C bean. Therefore, you can click Finish in the
New Java Method dialog.
Figure 22. New method
- If you now open the J2C bean implementation file, you will see the new method shown in Figure 23 there. Note that the message signature is the same as it was outlined in the New Method Dialog.
Figure 23. New method
At this point you have a functional J2C bean that is able to access the IMS and retrieve the PhoneBook entries.
The next Task shows how you can expose this functionality through the Web service.
Task 4: Create a Web service to expose functionality provided by the generated J2C bean
Before going through the steps specified in this task, start the WebSphere v6.1 server if it is not already started.
J2C Tools provide an easy way to generate such deployable artifacts as WebServices, JSPs and Session beans, all of which can be used to test the functionality of the J2C bean. For the purposes of this article, you will generate a Web service that will be able to access the PhoneBook application through the use of a J2C bean.
- From the Select a wizard screen, select the Web Page, Web Service, or EJB from J2C bean wizard under the J2C category, as shown in figure 24.
Figure 24. Open J2C deployment wizard
- On the first page of this wizard, you need to specify for which J2C bean you want to generate the deployable artifacts, as shown in Figure 25.
Figure 25. Select J2C bean to generate the deployment artifacts
- On the next page, select to create a Web service, as shown in Figure 26.
Figure 26. Select to generate the Web service
On the next page you will need to specify (or create a new) Dynamic Web project where the Web service will be generated.
It is also advisable to use Resource References to access the resources defined on the server. By using the resource reference you will make sure that real JNDI name of your resource is not hard coded anywhere in your code. The resource reference is defined at the deployment descriptor of your application, and can be changed to point to different "real" resources, depending on to which server you are planning to deploy your application. If you specify the name of the resource reference in this page of the wizard, the J2C tools will create the resource reference and update the application descriptor for us automatically.
- By clicking Finish , you generate a Web service with default settings, as shown in Figure 27.
Note: If you want to create a Web Service with some non-default settings, use the Web Services wizard from Web Service Tools to generate a bottom-up Web service (Web Service from Java Bean) using that set of tools.
Figure 27. Generate the Web Service
- Look at the content of the Web project and you will see the Web service artifacts generated there, as shown in Figure 28.
Figure 28. Web Service artifacts in the Web project
Task 5 shows you how to test the Web service you created.
Task 5: Test the created Web service using the Web Services explorer
Now you can test the generated Web service on the WebSphere 6.1 server using the Web Services explorer.
- First, you have to deploy an EAR that contains your Web project to the WebSphere 6.1 Server, as shown in Figure 29.
Figure 29. Add EAR to the server
- Now, right-click the wsdl file corresponding to the created Web service, then select Web Services > Test with Web Services Explorer, as shown in Figure 30.
Figure 30. Test with Web Service explorer
- In the Web Service explorer, specify to run the
runPhoneBookmethod, as shown in Figure 31.
Figure 31. Test the runPhoneBook method
- Next, provide the inputs shown in Figure 32 to this method.
Note: specify 1000 milliseconds as the value for the
executionTimeoutproperty. This should give your system more than enough time to execute the PhoneBook operation.
Figure 32. Specify the proper parameters for method invocation
- You should should get a response that looks similar to that shown in Figure 33.
Figure 33. New method
This proves that your program is working correctly. you obtained the proper data from the PhoneBook application on the IMS.
You also can make sure that the value of
myExecutionTimeoutthat you specify on the input is actually used by backend system.
- To do this, set the value of
1. It is very likely that your transaction takes more time than 1 millisecond to run, so you should get an exception. Now run the Web Service explorer again and you should see something similar to Figure 34 in the result frame. This means that some exception has occurred.
Figure 34. New method
- If you choose to see the source, you will see an exception very similar to that in Listing 1 in the response section. This exception indicates that the system has not been able to finish the execution within 1 millisecond.
Listing 1. Exception
javax.resource.spi.EISSystemException: ICO0081E: com.ibm.connector2.ims.ico.IMSTCPIPManagedConnection@ 1b521b52.processOutputOTMAMsg(byte, IMSInteractionSpec, int) error. Execution timeout has occurred for this interaction. The executionTimeout value specified was  milliseconds. The value used by IMS Connect was  milliseconds.
This means that you have a fully functional Web service that can not only invoke functions on the backend IMS, but also pass values corresponding to different IMS interaction properties.
This article showed you how the J2C tools provided in Rational Application Developer V7.0 can be successfully used to rapidly create a J2C bean that is able to access the functionality of the backend IMS. It also demonstrated how this functionality can be quickly exposed to other application and business processes through the Web service mechanism.
- Visit the Rational Application Developer product page to expand your product skills.
- Stay current with developerWorks technical events and Webcasts.
Get products and technologies
- Build your next development project with IBM trial software, available for download directly from developerWorks.
- Download a free trial version of Rational Application Developer
- Rational Software Architect, Data Architect, Software Modeler, Application Developer and Web Developer forum: Ask questions about Rational Application Developer.
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.