Developing Web services

Web services are self-contained applications, based on open standards, that can be invoked over the Web. Web services provide a way for applications to connect and interact easily and efficiently. They can be building blocks of applications used within your enterprise or provide a point of interaction with other enterprises. Because their interfaces are defined according to standards, Web services can interact with other applications that are not Java-based.

You can use HATS Web service support to create service-oriented architecture (SOA) assets that provide standard programming interfaces to business logic and transactions contained within your host applications. These core business tasks can be reused as standard Web services that participate as an integral part of your business process integration plan. Use your core business services as building blocks to develop new internal applications or to integrate with applications outside your enterprise. Your host-based business tasks can then be included in your SOA solutions with IBM® SOA Foundation products, such as IBM WebSphere® Process Server, IBM WebSphere Enterprise Service Bus, and others.

Using a combination of tools from HATS Toolkit and Rational® SDP, you can create Web services from Integration Objects or from EJB Access Beans. .

Note:
You cannot use an Integration Object that is configured to use Web Express Logon in a Web service.

Web services use several standard ways to formulate information: Simple Object Access Protocol (SOAP), Web Service Description Language (WSDL), Universal Description, Discovery, and Integration (UDDI). This book refers to but does not explain these protocols. You can find information about them by opening the Rational SDP documentation (click Help > Help Contents from any Rational SDP perspective) and searching for Web service.

Usually you create HATS Web services from Integration Objects that you have already built, tested, and deployed. This chapter assumes that you have one or more successfully tested Integration Objects that you want to include in a Web service. However, you can start from the very beginning by opening your host terminal, recording one or more macros, creating Integration Objects from the macros, and testing the Integration Objects. Refer to HATS User's and Administrator's Guide for information about creating an Integration Object from a macro.

You must decide whether you want your Web service to comply with the Web Services Interoperability (WSI) standard. This will govern which Web service runtime you use for the creation of your Web services. If you accept the default, IBM WebSphere runtime, the resulting Web service will be WSI-compliant.

You must follow certain naming conventions when creating Web services using IBM WebSphere runtime. These include:

Keep these naming restrictions in mind when creating macro names, prompt names, and extract names during macro creation. For more information on naming restrictions, refer to the Rational SDP documentation.

Creating Web services

Creating a Bottom-up Web service from Integration Objects

The instructions in this section assume that you want to create a Web service that has input and output properties and methods similar to all of the properties and methods in an Integration Object. Or, in other words, you want the signature of the Web service that you create to be similar to that of an Integration Object contained in the Web service. This scenario is called a Bottom-up Web service.

Note:
You can now create a Web service and generate a Web service client from the HATS Project view instead of having to switch to the Navigator view.

To create a Web service, begin from the HATS Projects view and follow these steps:

  1. Expand the project that contains the Integration Objects you wish to use, then expand the Source folder and the IntegrationObject folder.
  2. Right-click any Integration Object in your project and select Create Web Service Support Files.
  3. The Create Web Service Support Files wizard enables you to select any project as the source of the Integration Objects you will include in a Web service. The project in which you clicked will be the default. Provide a class name for the HATS Web service support files. The class name must begin with an uppercase letter. This class is referred to as your wrapper class for this Web service. This wrapper class enables you to select a logical group of Integration Objects or EJB Access Beans to include in one Web service. For example, you might select to include all the Integration Objects in a chain in the wrapper class. To see a list of Integration Objects and select the ones to include, click Next.
  4. Select the resources (Integration Objects and EJB access beans) that you want to include in your Web service. If you want to change the input and output properties that are exposed by the Web service for a given resource, select the resource and click Properties.
  5. On the Choose Properties page, select the input and output properties that you want exposed in the Web service. If you wish, you can provide an alias name for the property in the Alias Name field. Use the Select All, Deselect All, and Select Default buttons to help in selecting the properties. Click OK.
    Notes:
    1. Defaults for single Integration Objects and EJB access beans are all macro prompts for input properties and all macro extracts for output properties.
    2. Defaults for chained Integration Objects are all macro prompts plus hPubLinkKey (which is required) for input properties and all macro extracts plus hPubLinkKey (which is required) for output properties.
    3. Defaults for chained EJB access beans are all macro prompts plus hPubLinkKey and hPubAccessHandle (both of which are required) for input properties and all macro extracts plus hPubLinkKey and hPubAccessHandle (both of which are required) for output properties.
    4. The following input and output properties are also selected as defaults and are required for Integration Objects and EJB access beans using bidirectional sessions:
      • hExtractRTLTextOrientation
      • hExtractReordering
      • hPreventBidiRoundTrip
      • hPromptRTLTextOrientation
      • hPromptReordering
    5. To specify that Integration Object connection overrides be exposed to the Web service, you must select the appropriate properties, for example the hPubConnectionOverrides or hPubStartPoolName properties, which are not selected by default. For more information, see Specifying Connection Overrides.
    6. For more information about the use of other Integration Object methods, see Programming with Integration Objects.
  6. Click Finish. HATS creates a set of classes to be used in creating the Web service. The following classes appear in the HATS Projects view in the Source\webserviceclasses folder:
  7. At this point, you are ready to create a Web service using the tools provided in the IBM Rational SDP. Familiarize yourself with the procedure and the options available to you by reviewing the Bottom-up Web services development chapter. At a minimum, you should start the server that you are going to deploy the Web service to before continuing to create the Web service. These instructions assume that you are going to use separate steps to create your Web service, test your Web service, and create your Web service client.
  8. Expand the webserviceclasses package. Right-click the wrapper class that you created, and select Web Services > Create Web service. The Web service type defaults to Bottom up Java™ bean Web service. Make sure that you keep this default. You can click Finish here or select other options that best meet your requirements, as described in the Rational SDP documentation. If you select the option, Generate WSDL file into the project, Rational SDP creates a Web Services Description Language (WSDL) file that describes the interfaces to your Web service. You can use this WSDL file to test your Web service using the Web services explorer in the HATS project view. If you do not select this option, you can use a dynamically generated WSDL file to test your Web service from Services view of the Java EE perspective. When you have made all your choices, click Finish.
  9. Go to Testing your Web service with Web Services Explorer for information about testing your Web service before you create a client.

Creating a Web service from EJB Access Beans

If you have created a HATS EJB project, as described in Creating and using a HATS EJB application, you can create a Web service to use the services of the Integration Objects in the HATS EJB project. To create a Web service, you must have another HATS project, within the same enterprise archive (EAR file) as your HATS EJB project. This project is referred to as your target project, in which a Web service will be created from the EJB Access Beans you select. Follow these steps to create the Web service:

  1. In the HATS EJB Project view, right-click on one of your Integration Objects and select Export EJB Access Bean to HATS Project. In the Export EJB Access Bean window, select the Integration Objects for which you want to export EJB Access Beans. Select the target project from the drop-down list of available projects. Click Finish.
  2. In the HATS Projects view, expand the target project, the Source directory, and the IntegrationObject directory. You will see items in this directory with the name io_name_Access, where io_name is the name of the Integration Object from which the access bean was created.
  3. Right click on any of these access beans and select Create HATS Web Services Support Files.
  4. Follow the steps beginning with step 3 in the list under Creating a Bottom-up Web service from Integration Objects.

Testing your Web service with Web Services Explorer

You can test your Web service in Rational SDP before you create a client application.

Before you start this process, ensure that the HATS runtime is started. You can do this by starting your server, and then, in the Servers view, choose the EAR file in which your Web service is contained, right-click, and choose Restart.

If you selected the option to Generate WSDL file into the project, see step 8 in the list under Creating a Bottom-up Web service from Integration Objects, the WSDL file that you created is located within your HATS project:

This folder contains a file called wrapper.wsdl, where wrapper is the name you gave to your wrapper class. Right-click this file and select Web Services > Test with Web Services Explorer.

In the right pane of the Web Services Explorer, you will see the io_nameProcessWS() methods for each Integration Object or EJB Access Bean included in the Web service. Click any method name to test that Integration Object. You will see a list of the input properties that you can specify for the Integration Object. This list is based on the Integration Object's io_name_Input_Properties class. The only properties that must be set are the prompts that you defined when you recorded your macro. The other properties can be left blank. Refer to the Rational SDP documentation for information about using the WSDL view of Web Services Explorer to explore and test your Web service definition.

If you did not select the option to Generate WSDL file into the project, see step 8 in the list under Creating a Bottom-up Web service from Integration Objects, you can use a dynamically generated WSDL file to test your Web service from Services view of the Java EE perspective.

Creating a Web service client

Next you can create a client application to use the Web service. Do the following:

  1. Expand your project, then expand the folder appropriate for the Web service runtime you selected when you created the Web service. The WSDL file that you created is located within your HATS project: This folder contains a file called wrapper.wsdl, where wrapper is the name you gave to your wrapper class.
  2. Right-click this file and select Web Services > Generate Client to start the Web Service Client Proxy wizard. On the first page of the wizard, you can choose all defaults except for the client project. You should choose a project other than the project that contains the Web service.
    Note:
    The specified Client project and the Ear project need to have the same server target as the chosen Server.
    You can click Finish at this point, or continue through the wizard. Refer to the Rational SDP documentation for information about the options in this wizard.
  3. If you chose to Test the Web service, the wizard creates sample JSP pages, and runs the sample on the server. The output of the sample JSP pages will be displayed in the web browser. To run the sample, in the Methods frame, click the io_nameProcessWS link to test a particular Integration Object or EJB Access Bean. In the Inputs frame, set the required inputs, as described in Testing your Web service with Web Services Explorer. The Result frame will display the outputs.

    The sample pages are created in your client project. In the Navigator view, expand your client project, and expand Web Content and samplewrapperProxy. In the samplewrapperProxy folder are the sample JSP pages. You can run the sample by running the TestClient.jsp file on the server. Double click Result.jsp to open it in the JSP editor. You can examine the code and copy code from the sample into a HATS business logic class, which can be run from a screen customization to invoke your Web service and use the output in a transformation or in some other way.

Creating a Top-down Web service that includes Integration Objects

Your development task may involve creating a top-down Web service, where you have been given a WSDL that has the specified signature of the Web service. Your task is to create the Web service implementation, part of which involves interacting with an existing terminal application.

If the input parameters in the WSDL either contain the required input properties for an Integration Object, or based on the input parameters, you can write code that will set the required Integration Object input properties, you can use Integration Objects directly in your Web service implementation.

The Rational SDP contains tools to create a skeleton Java bean from an existing WSDL. You can then interact with Integration Objects directly from this skeleton Java bean. Refer to Programming with Integration Objects to learn more. The one caveat is that you should use the processRequest () method to invoke the Integration Object in a Web services run time environment.

Refer to Introduction

Programming with Web Services Integration Objects and EJB Access Beans

Integration Object chaining with Web Services

If your application requires chaining, your client code must retrieve the hPubLinkKey property from the first Integration Object in the chain, and set it for all subsequent Integration Objects in the chain.

EJB Access Bean chaining with Web Services

If your application requires chaining, your client code must retrieve both the hPubLinkKey and the hPubAccessHandle properties from the first EJB Access Bean in the chain, and set them for all subsequent EJB Access Beans in the chain.

Special considerations with chaining Web Services

If you use chained Integration Objects within a HATS Web service, you are creating a stateful Web service. HATS runtime does not store data between invocations of chained Integration Objects in the same Web service. However, HATS runtime does require that the next in chain Web service invocation is routed back to the same instance of the HATS runtime so that the next in chain IO will use the same Telnet connection.

If you deploy a stateful HATS Web service using JAX-RPC support to a cluster, to enable all Integration Objects in the chain to use the same Telnet connection, do one of the following:

If you deploy a stateful HATS Web service using JAX-WS support to a cluster, to enable all Integration Objects in the chain to use the same Telnet connection, do one of the following:

Updating Web services

The Update wizard is only enabled for Web service classes that have been created with HATS 7.0.0.2 or later. If you are using an earlier version, then you must update manually.

To update the HATS Web service support classes, do the following:

  1. Select an existing Web service wrapper class to update.
  2. The Update Web service wizard is invoked with the Web service class preselected.
  3. If you do not need to change the selection of Integration Objects or EJB Access Beans included in the Web service, you can select Finish to regenerate the Web service support classes, otherwise select Next to continue to the next page of the wizard.
  4. Modify the list of resources (Integration Objects and EJB access beans) included in the Web service wrapper class . If you want to change the input and output properties that are exposed by the Web service for a given resource, select the resource and click Properties.
  5. On the Choose Properties page, select the input and output properties that you want exposed in the Web service. If you wish, you can provide an alias name for the property in the Alias Name field. Use the Select All, Deselect All, and Select Default buttons to help in selecting the properties. Click OK.
    Notes:
    1. Defaults for single Integration Objects and EJB access beans are all macro prompts for input properties and all macro extracts for output properties.
    2. Defaults for chained Integration Objects are all macro prompts plus hPubLinkKey (which is required) for input properties and all macro extracts plus hPubLinkKey (which is required) for output properties.
    3. Defaults for chained EJB access beans are all macro prompts plus hPubLinkKey and hPubAccessHandle (both of which are required) for input properties and all macro extracts plus hPubLinkKey and hPubAccessHandle (both of which are required) for output properties.
    4. The following input and output properties are also selected as defaults and are required for Integration Objects and EJB access beans using bidirectional sessions:
      • hExtractRTLTextOrientation
      • hExtractReordering
      • hPreventBidiRoundTrip
      • hPromptRTLTextOrientation
      • hPromptReordering
    5. To specify that Integration Object connection overrides be exposed to the Web service, you must select the appropriate properties, for example the hPubConnectionOverrides or hPubStartPoolName properties, which are not selected by default. For more information, see Specifying Connection Overrides.
    6. For more information about the use of other Integration Object methods, see Programming with Integration Objects.
  6. Click Finish.

The HATS Web service support files are regenerated and compiled. Note that you still must use the Rational SDP wizards to update your Web services once you have updated the HATS Web services support files.

Web services for JAX-WS runtime considerations and limitations

If you install the WebSphere Application Server Version 6.1 Feature Pack for Web Services, you can create HATS Web services for the IBM WebSphere Java API for XML-Based Web Services (JAX-WS) runtime. If you plan to create HATS Web services for the JAX-WS runtime, be aware of the following: