Web service support for the example application

Edit online

The Web service support extends the example application, providing a Web client front end and two versions of a Web service endpoint for the order dispatcher component.

The Web client front end and one version of the Web service endpoint are supplied as enterprise archives (EARs) that will run in the following environments:
  • WebSphere® Application Server Version 5 Release 1 or later
  • WebSphere Studio Application Developer Version 5 Release 1 or later with a WebSphere unit test environment
  • WebSphere Studio Enterprise Developer Version 5 Release 1 or later with a WebSphere unit test environment

The second version of the Web service endpoint is supplied as a CICS® service provider application program (DFH0XODE).

Configuring code page support

Edit online

As supplied, the example application uses two coded character sets. You must configure your system to enable data conversion between the two character sets.

About this task

The coded character sets used in the example application are:
CCSID
Description
037
EBCDIC Group 1: USA, Canada (z/OS®), Netherlands, Portugal, Brazil, Australia, New Zealand)
1208
UTF-8 Level 3

Procedure

Add the following statements to the conversion image for your z/OS system:
CONVERSION 037,1208;
CONVERSION 1208,037;

Installing Web service support

Edit online

Before you can run the Web service support for the example application, you must create two HFS directories, and create and install a number of CICS resource definitions.

Example

Creating the HFS directories

Edit online

Web service support for the example application requires a shelf directory and a pickup directory in the Hierarchical File System (HFS).

About this task

The shelf directory is used to store the Web service binding files that are associated with WEBSERVICE resources. Each WEBSERVICE resource is, in turn, associated with a PIPELINE. The shelf directory is managed by the PIPELINE resource and you should not modify its contents directly. Several PIPELINES can use the same shelf directory, as CICS ensures a unique directory structure beneath the shelf directory for each PIPELINE.

The pickup directory is the directory that contains the Web service binding files associated with a PIPELINE. When a PIPELINE is installed, or in response to a PERFORM PIPELINE SCAN command, information in the binding files is used to dynamically create the WEBSERVICE and URIMAP definitions associated with the PIPELINE.

The example application uses /var/cicsts for the shelf directory.

A pipeline will read in an XML pipeline configuration file at install time. It is therefore also useful to define a directory in which to store these.

Creating the PIPELINE definition

Edit online

The complete definition of a pipeline consists of a PIPELINE resource and a pipeline configuration file. The file contains the details of the message handlers that will act on Web service requests and responses as they pass through the pipeline.

About this task

The example application uses the CICS-supplied SOAP 1.1 handler to deal with the SOAP envelopes of inbound and outbound requests. CICS provides sample pipeline configuration files which you can use in your service provider and service requester.

More than one WEBSERVICE can share a single PIPELINE, therefore you need define only one pipeline for the inbound requests of the example application. You must, however, define a second PIPELINE for the outbound requests as a single PIPELINE cannot be configured to be both a provider and requester pipeline at the same time.

Procedure

  1. Use the CEDA transaction to create a PIPELINE definition for the service provider.
    1. Enter the following: CEDA DEF PIPE(EXPIPE01) G(EXAMPLE).
      Alternatively, you can copy the PIPELINE definition from CICS supplied group DFH$EXWS.
    2. Enter the following additional attributes:
      STATUS(Enabled)
      CONFIGFILE(/usr/lpp/cicsts
                 /samples/pipelines/basicsoap11provider.xml)
      SHELF(var/cicsts)
      WSDIR(/usr/lpp/cicsts/samples/webservices/wsbind/provider/)
      Note: The HFS entries are case sensitive and assume a default CICS HFS install root of /usr/lpp/cicsts.
  2. Use the CEDA transaction to create a PIPELINE definition for the service requester.
    1. Enter the following: CEDA DEF PIPE(EXPIPE02) G(EXAMPLE).
      Alternatively, you can copy the PIPELINE definition from CICS supplied group DFH$EXWS.
    2. Enter the following additional attributes:
      STATUS(Enabled)
      CONFIGFILE(/usr/lpp/cicsts
                 /samples/pipelines/basicsoap11requester.xml)
      SHELF(var/cicsts)
      WSDIR(/usr/lpp/cicsts/samples/webservices/wsbind/requester/)
      Note: The HFS entries are case sensitive and assume a default CICS HFS install root of /usr/lpp/cicsts.

Creating a TCPIPSERVICE

Edit online

As the client connects to your Web services over an HTTP transport you must define a TCPIPSERVICE to receive the inbound HTTP traffic.

Procedure

Use the CEDA transaction to create a TCPIPSERVICE definition to handle inbound HTTP requests.
  1. Enter the following: CEDA DEF TCPIPSERVICE(EXMPPPORT) G(EXAMPLE).

    Alternatively, you can copy the TCPIPSERVICE definition from CICS supplied group DFH$EXWS.
  2. Enter the following additional attributes:
    • URM(NONE)
    • PORTNUMBER(port) where port is an unused port number in your CICS system.
    • PROTOCOL(HTTP)
    • TRANSACTION(CWXN)
  3. Use the default values for all other attributes.

Dynamically installing the WEBSERVICE and URIMAP resources

Edit online

Each function exposed as a Web service requires a WEBSERVICE resource to map between the incoming XML of the SOAP BODY and the COMMAREA interface of the program, and a URIMAP resource that routes incoming requests to the correct PIPELINE and WEBSERVICE. Although you can use RDO to define and install your WEBSERVICE and URIMAP resources, you can also have CICS create them dynamically when you install a PIPELINE resource.

Procedure

Install the PIPELINE resources.

Use the following commands:
  • CEDA INSTALL PIPELINE(EXPIPE01) G(EXAMPLE)
  • CEDA INSTALL PIPELINE(EXPIPE02) G(EXAMPLE)
When you install each PIPELINE resource, CICS scans the directory specified in the PIPELINE's WSDIR attribute (the pickup directory). For each Web service binding file in the directory, that is for each file with the .wsbind suffix, CICS installs a WEBSERVICE and a URIMAP if one does not already exist. Existing resources are replaced if the information in the binding file is newer than the existing resources.

When the PIPELINE is later disabled and discarded all associated WEBSERVICE and URIMAP resources will also be discarded.

If you have already installed the PIPELINE, use the PERFORM PIPELINE SCAN command to initiate the scan of the PIPELINE's pickup directory.

When you have installed the PIPELINEs, the following WEBSERVICEs and their associated URIMAPs will be installed in your system:
  • dispatchOrder
  • dispatchOrderEndpoint
  • inquireCatalog
  • inquireSingle
  • placeOrder
The names of the WEBSERVICEs are derived from the names of the Web service binding files; the names of the URIMAPs are generated dynamically. You can view the resources with a CEMT INQUIRE WEBSERVICE command.
The following display shows the names of the PIPELINE, the URIMAP, and the target program that is associated with each WEBSERVICE.
Note: In this example, there is no URIMAP or target program displayed for WEBSERVICE(dispatchOrder) because the WEBSERVICE is for an outbound request.
I WEBS                                                                        
STATUS:  RESULTS - OVERTYPE TO MODIFY                                         
 Webs(dispatchOrder                   ) Pip(EXPIPE02)                         
    Ins                                                       Dat(20041203)   
 Webs(dispatchOrderEndpoint           ) Pip(EXPIPE01)                         
    Ins Uri(£539140 ) Pro(DFH0XODE) Com                       Dat(20041203)   
 Webs(inquireCatalog                  ) Pip(EXPIPE01)                         
    Ins Uri(£539141 ) Pro(DFH0XCMN) Com                       Dat(20041203)   
 Webs(inquireSingle                   ) Pip(EXPIPE01)                         
    Ins Uri(£539142 ) Pro(DFH0XCMN) Com                       Dat(20041203)   
 Webs(placeOrder                      ) Pip(EXPIPE01)                         
    Ins Uri(£539150 ) Pro(DFH0XCMN) Com                       Dat(20041203)

WEBSERVICE(dispatchOrderEndpoint) represents the local CICS implementation of the dispatch order service.

Creating the WEBSERVICE resources with RDO

Edit online

As an alternative to using the PIPELINE scanning mechanism to install WEBSERVICE resources, you can create and install them using Resource Definition Online (RDO).

Before you begin

Important: If you use RDO to define the WEBSERVICE and URIMAP resources, you must ensure that their Web service binding files are not in the PIPELINE's pickup directory.

Procedure

  1. Use the CEDA transaction to create a WEBSERVICE definition for the inquire catalog function of the example application.
    1. Enter the following: CEDA DEF WEBSERVICE(EXINQCWS) G(EXAMPLE).
    2. Enter the following additional attributes:
      PIPELINE(EXPIPE01)
      WSBIND(/usr/lpp/cicsts/samples
             /webservices/wsbind/inquireCatalog.wsbind)
  2. Repeat the preceding step for each of the following functions of the example application.
    Function WEBSERVICE name PIPELINE attribute WSBIND attribute
    INQUIRE SINGLE ITEM EXINQSWS EXPIPE01 
    /usr/lpp/cicsts/samples
/webservices/wsbind
/provider/inquireSingle.wsbind
    PLACE ORDER EXORDRWS EXPIPE01 
    /usr/lpp/cicsts/samples
/webservices/wsbind
/provider/placeOrder.wsbind
    DISPATCH STOCK EXODRQWS EXPIPE02 
    /usr/lpp/cicsts/samples
/webservices/wsbind
/requester/dispatchOrder.wsbind
    DISPATCH STOCK endpoint (optional) EXODEPWS EXPIPE01 
    /usr/lpp/cicsts/samples
/webservices/wsbind
/provider/dispatchOrderEndpoint.wsbind

Creating the URIMAP resources with RDO

Edit online

As an alternative to using the PIPELINE scanning mechanism to install URIMAP resources, you can create and install them using Resource Definition Online (RDO).

Before you begin

Important: If you use RDO to define the WEBSERVICE and URIMAP resources, you must ensure that their Web service binding files are not in the PIPELINE's pickup directory.

Procedure

  1. Use the CEDA transaction to create a URIMAP definition for the inquire catalog function of the example application.
    1. Enter the following: CEDA DEF URIMAP(INQCURI) G(EXAMPLE).
    2. Enter the following additional attributes:
      USAGE(PIPELINE)
      HOST(*)
      PATH(/exampleApp/inquireCatalog)
      TCPIPSERVICE(SOAPPORT)
      PIPELINE(EXPIPE01)
      WEBSERVICE(EXINQCWS)
  2. Repeat the preceding step for each of the remaining functions of the example application.
    Use the following names for your URIMAPs:
    Function URIMAP name
    INQUIRE SINGLE ITEM INQSURI
    PLACE ORDER ORDRURI
    DISPATCH STOCK Not required
    DISPATCH STOCK endpoint (optional) ODEPURI
    1. Specify the following distinct attributes for each URIMAP:
      Function URIMAP name PATH WEBSERVICE
      INQUIRE SINGLE ITEM INQSURI /exampleApp/inquireSingle EXINQSWS
      PLACE ORDER ORDRURI /exampleApp/placeOrder EXORDRWS
      DISPATCH STOCK endpoint (optional) ODEPURI /exampleApp/dispatchOrder EXODEPWS
    2. Enter the following additional attributes, which are the same for all the URIMAPs:
      • USAGE(PIPELINE)
      • HOST(*)
      • TCPIPSERVICE(SOAPPORT)
      • PIPELINE(EXPIPE01)

Completing the installation

Edit online

To complete the installation, install the RDO group that contains your resource definitions.

Procedure

Enter the following command at a CICS terminal: CEDA I G(EXAMPLE).

Results

The application is now ready for use.