Creating 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. Using a combination of tools from HATS Studio and Rational Studio, you can create Web services from Integration Objects or from EJB Access Beans. You can also create Web service clients that access the Web services.

Note:
You cannot include 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), and 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 Studio documentation (click Help > Help Contents from any Rational Studio perspective) and searching for Web service.

Usually you build Web services based on 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:

  • Method names must begin with a lower case letter.

  • Class names must begin with an upper case letter.

  • If a method or class name contains an underscore followed by a letter, the letter must be an upper case letter.

  • If a method or class name contains a number followed by a letter, the letter must be an upper case letter.

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 Studio documentation.

Creating a Web service from Integration Objects

To create a Web service, begin from the HATS Project 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 on any Integration Object in your project and select Create HATS Web Services Support Files.
  3. The Create HATS Web Services Support Files wizard enables you to choose 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 choose a logical group of Integration Objects or EJB Access Beans to include in one Web service. For example, you might choose to include all the Integration Objects in a chain in the wrapper class. To see a list of Integration Objects and choose 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, then click Finish. HATS creates a set of classes to be used in creating the Web service. The following classes appear in the HATS Project view in the webServiceClasses folder, under the Source folder:

    • The wrapper class that you specified. This wrapper class contains an io_nameProcessWS()method for each Integration Object that you chose to include in the wrapper class. When you create the Web service using Rational Studio wizards, you are creating a Web service that contains all of the io_nameProcessWS() methods that are contained in the wrapper class.

    • Input properties classes (io_name_Input_Properties) for each Integration Object that you included in the wrapper class. The input properties class is used to set all the necessary inputs for the Integration Object.

    • Output properties classes (io_name_Output_Properties) for each Integration Object that you included in the wrapper class. All of the the Integration Object output properties can be retrieved fom the output properties class.

  5. Click the Navigator tab to open the Navigator view of your resources. Expand your project, then expand Java Source and webServiceClasses. Right click the wrapper class that you created, and select Web Services > Create Web service. Use IBM WebSphere Web service runtime; it provides the most standard-compliant code and supports the most clients. You can click Finish or click Next to view and choose different options, which are described in the Rational Studio documentation. When you have made all your choices, click Finish. Rational Studio creates a Web Services Description Language (WSDL) file that describes the interfaces to your Web service.
    Note:
    If you choose IBM WebSphere runtime, one WDSL file is created, named wrapper.wsdl, where wrapper is the name you gave to your wrapper class. If you choose the IBM SOAP runtime, four WSDL files are created. When you create your Web service client, you will use the file named wrapperService.wsdl.

  6. 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, 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 choose. 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 Project 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 Web service from Integration Objects.

Testing your Web service with Web Services Explorer

You can test your Web service in Rational Studio before you create a client application. In the Navigator view, expand your project, expand Web Content, wsdl, and webServiceClasses. If you created your Web service using IBM WebSphere runtime, this folder contains a file called wrapper.wsdl, where wrapper is the name you gave to your wrapper class. If you created your Web service using the IBM SOAP runtime, this folder contains several wsdl files; use the one named wrapperService.wsdl. 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 Studio documentation for information about using the WSDL view of Web Services Explorer to explore and test your Web service definition.

Creating a Web service client

Next you can create a client application to use the Web service. Follow these steps:

  1. In the Navigator view, expand your project, expand Web Content, wsdl, and webServiceClasses. This folder contains a file called wrapper.wsdl, where wrapper is the name you gave to your wrapper class, or wrapperService.wsdl if you created your Web service with the IBM SOAP runtime.

  2. Right click this file and select Web Services > Generate Client to start the WSDL to JavaBean Proxy wizard. On the first page of the wizard, select the Overwrite files without warning check box. Click Test the Web service if you want the wizard to create sample JSP pages. On the Web Services Selection page, accept the default URL. On the Client Environment Configuration panel, you can accept the default values for the Web service runtime, the Server, the J2EE version, and the Client type. This will create a Web Client project with the same server and runtime as the Web service. For the Client project, either type in the name of a new project in which you want the client to be created, or choose an existing project. You should not create the Web service client in the same project as 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 Studio 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 run 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 executed from a screen customization to invoke your Web service and use the output in a transformation or in some other way.

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.