CICS as a service provider for JSON requests using CICS Java pipelines

Deprecated feature: Support for the JVMSERVER-based configuration option for the web services data transformation service is deprecated. The deprecated options can be replaced with the use of a non-Java pipeline for CICS® web services, z/OS Connect Enterprise Edition, or by writing web applications in Java or Node.js. For more details, see Stabilization notices.

For CICS to provide a service to an external JSON client, it must receive the request and pass it through a pipeline to the target application program. The response from the application is returned to the JSON client through the same pipeline. The JSON transform is performed by using Java™ within the JVM server.

Figure 1 shows an example configuration of the architecture and resources that are required to process a request from an external JSON client when CICS is a service provider that uses a Java pipeline. The pipeline processing for a JSON request is similar to the way that CICS processes a SOAP request in a Java pipeline. For more information, see Java-based SOAP pipelines.

Figure 1. The architecture and resources for a JSON service provider that uses a CICS Java pipeline
The figure show a service requester that is external to the CICS region initiating a request to a CICS application program. The CICS region that the application program runs in also contains the TCPIPSERVICE, URIMAP, PIPELINE, and WEBSERVICE resources; the pipeline and its handlers and a JVM server.

How CICS processes a JSON request

To process a request, CICS completes the following operations:
  1. Receive the request from the service requester.

    The TCPIPSERVICE resource specifies a port for incoming requests. This port is monitored by the CICS-supplied sockets listener task (CSOL).

  2. Examine the request, and extract the contents that are relevant to the target application program.

    When the request message is received on the appropriate port, the URIMAP resource definitions are scanned for a URIMAP definition that has its USAGE attribute set to PIPELINE and its PATH attribute set to the URI found in the request. If an appropriate URIMAP definition is found, the PIPELINE and WEBSERVICE definitions from the PIPELINE and WEBSERVICE attributes of the URIMAP definition are used. The TRANSACTION attribute of the URIMAP definition determines the name of the transaction that should be attached to process the pipeline. By default the CPIH transaction is used. The URIMAP definition also identifies the PIPELINE and WEBSERVICE resources to use.

    These PIPELINE and WEBSERVICE resources control the processing that CICS performs. In particular, the WSBind file pointed to by the WEBSERVICE resource is used for data transformation between JSON and language structures. WSBind files for JSON web services are generated by using utilities DFHLS2JS and DFHJS2LS.

    Note: Runtime validation of JSON data against schema is not supported. The value of the VALIDATION attribute of a WEBSERVICE resource that is used with a JSON payload is ignored.
    For information about any restrictions that apply, see JSON web service restrictions.
  3. Pipeline processing begins and the request flows through any handlers that are defined. It is not expected that any of the handlers that are currently provided by CICS for SOAP web services will be relevant to JSON web services.
  4. At the end of the pipeline, the JSON terminal handler is called. This terminal handler is a Java program that interfaces with the Axis2 pipeline. The terminal handler performs the necessary setup of the Axis2 configuration and then starts the Axis2 engine with the HTTP request body. Within the Axis2 pipeline, the JSON body (if present) is parsed and a Java object model that represents the contents is constructed. CICS then calls the application handler. The main role of the application handler is to map the Java object model representation of the request into application data. This mapping is performed by using the description of the language structure in the WSBind file.
  5. Call the application program, passing data that is extracted from the request.

    Then the application handler links to the application program. The program processes this input and returns a response to the application handler.

  6. Construct a response by using data returned by the application program, and send a response to the service requester.

    The application handler and message handlers convert the response message received from the service provider application into a message in the format of the original request. This message is sent back to the service requester.

Some of the processing within the pipeline is eligible for offloading onto a IBM® z Systems® Application Assist Processor (zAAP).