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:
- 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 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:
- Expand the project that contains the Integration Objects you wish
to use, then expand the Source folder
and the IntegrationObject folder.
- Right-click any Integration Object
in your project and select Create
Web Service Support Files.
-
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.
- 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.
- 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:
- Defaults for single Integration Objects and EJB access beans are
all macro prompts for input properties and all macro extracts for
output properties.
- 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.
- 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.
- 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
- 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.
- For more information about the use of other Integration Object
methods, see Programming with Integration Objects.
- 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:
- 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 SDP
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 Integration Object output properties can be retrieved from
the output properties class.
- 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.
-
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.
- 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:
- 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.
- 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.
- Right click on any of these access beans and select Create HATS Web Services Support Files.
- 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:
- If you are creating a Web service for an IBM WebSphere JAX-RPC or JAX-WS runtime, it is located
in the Web Content/WEB-INF/Web Service Definitions folder.
- If you created a Web service for an Apache Axis runtime, it is
located in the Web Content/Web Service Definitions folder.
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:
- 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:
- If you created a Web service for an IBM WebSphere JAX-RPC or JAX-WS
runtime, it is located in the Web Content/WEB-INF/
Web Service Definitions folder.
- If you created a Web service for an Apache Axis runtime, it is
located in the Web Content/Web Service Definitions folder.
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 > 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.
- 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:
- Create the HATS Web services from EJB Access
Beans. The HATS EJB is a stateful session EJB, so the EJB client always interacts with the same HATS EJB instance.
- Configure the scope of the Web service to
be session (this can be done in the development environment or after
deployment), and use SESSION_MAINTAIN_PROPERTY
in the Web service client runtime to maintain the session across
invocations, therefore ensuring HTTP session affinity. For more information
about stateful Web services, see the following article: http://www-128.ibm.com/developerworks/webservices/library/ws-tip-stateful.html.
Note that WebSphere APAR
PK35259 may be required, as it fixes an issue with SESSION_MAINTAIN_PROPERTY.
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:
- Select an existing Web service wrapper class to update.
- The Update Web service wizard is invoked with the Web service
class preselected.
- 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.
- 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.
- 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:
- Defaults for single Integration Objects and EJB access beans are
all macro prompts for input properties and all macro extracts for
output properties.
- 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.
- 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.
- 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
- 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.
- For more information about the use of other Integration Object
methods, see Programming with Integration Objects.
- 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:
- When you generate a test client, the web_service_nameService.java
file is created with a hardcoded, absolute location of the WSDL file.
If you deploy the test client to a different machine, update the file
to contain the correct WSDL file location.
- The WSDL file that you elect to generate for your Web service
contains a URL location of the Web service. This URL points to the
local host and port. Update the local host and port in the URL when
you deploy the Web Service to another server.