Application handlers

An application handler is a CICS® program that the terminal handler of a SOAP service provider pipeline links to at run time.

Application handlers are used in provider mode pipelines in which the terminal handler is one of the supplied SOAP message handlers. This situation occurs when the <terminal_handler> element contains a <cics_soap_1.1_handler>, <cics_soap_1.2_handler>, <cics_soap_1.1_handler_java> or a <cics_soap_1.2_handler_java> element.

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

The application handler is responsible for processing the body of a SOAP request, and for generating a response using the returned data. The application handler can call other programs to complete this processing. Typically the application handler acts as a general-purpose presentation layer around one or more business applications. It is responsible for mapping XML into a form that an application can use, attaching that application, and then generating a response using the data returned.

An application handler can be attached by CICS in two ways. The typical mechanism involves a channel and control containers; the other method involves Java™ bindings for Axis2.

Channel-attached application handlers are specified in the <apphandler> element of the <provider_pipeline> element. At run time, the DFHWS-APPHANDLER container is populated by the contents of <apphandler>. However, the DFHWS-APPHANDLER container can be dynamically updated by any of the other message handlers. Therefore, the program that is linked to at run time can be different to the program specified in the <apphandler> element. The following application handlers can be specified in the <apphandler> element or the DFHWS-APPHANDLER container:
  • The supplied channel-attached SOAP application handler, DFHPITP. For more information about channel-attached application handlers, see Channel-attached application handlers
  • Your own channel-attached application handler. This application handler can be written in languages other than Java. For more information about the control containers that can be used in your channel-attached application handler, see Control containers.
  • Your own Java application handler for Java-based pipelines, which implements the ApplicationHandler Java interface and that is attached to the pipeline using Axis2 MessageContext. For more information about the ApplicationHandler Java interface, see Interface ApplicationHandler.

To use an application handler that uses Java bindings for Axis2, you must specify the <apphandler_class> element of the <provider_pipeline> element. Axis2 application handlers also require that a JVM server must exist for the web services pipeline and application handler to run on and that the terminal handler of your web services pipeline must be either the <cics_soap_1.1_handler_java> or the <cics_soap_1.2_handler_java> message handler. To use the supplied Axis2 application handler, you must specify com.ibm.cicsts.axis2.CICSAxis2ApplicationHandler in the <apphandler_class> element, however you can specify your own Axis2 application handler class. At run time, the DFHWS-APPHANCLAS container is populated by the contents of <apphandler_class>.

For web service applications that are deployed using the CICS web services assistant, you must specify either DFHPITP or your own application handler that uses DFHPITP in the <apphandler> element, or specify com.ibm.cicsts.axis2.CICSAxis2ApplicationHandler in the <apphandler_class> element. For more information about the CICS web services assistant, see The CICS web services assistant.

It is also possible to deploy Axis2 applications as provider mode web services in CICS using the Axis2 style of web service deployment. For more information, see Deploying a Java provider-mode web service in an Axis2 JVM server.