webMethods Integration Server
WmServiceUserHandler Package Readme
Description
This document describes how to use the service handler samples. The service handler samples
illustrate the functionality available with the new service handler feature in webMethods
Integration Server 7.1.2.
Use the package WmServiceUserHandler to work with the service handler samples. You can
examine the samples to gain familiarity with the service handler feature before using it for your
specific needs.
This document, and the use of the samples, assumes familiarity with the creation and execution
of Integration Server-based Web service providers, Web service consumers, and Web service
connectors. For more information, refer to the webMethods Developer Documentation
Supplement for 7.1.2, the webMethods Web Services Developer’s Guide, the webMethods
Integration Server Administrator’s Guide, and the webMethods Built-in Services Guide.
Before you Begin
The following products and package must be installed. You can download the package
WmServiceUserHandler from the webMethods Advantage Web site.



webMethods Integration Server 7.1.2
webMethods Developer
WmServiceUserHandler package
Overview of Samples
The WmServiceUserHandler sample package covers the service handler functionality under the
four samples described in this document, samples 1 through 4.
Each of the sample folders is organized as follows.




The consumer folder contains the related artifacts for the Web services consumer/client.
The provider folder contains the related artifacts for the Web services provider/server.
The consumerHandler folder contains the services for registering consumer handlers and
their constituent services.
The providerHandler folder contains the services for registering provider handlers and their
constituent services.

The wsd folder contains the appropriate Web services descriptor or WSD (provider or
consumer).
Note: All samples are written for SOAP version 1.1 and the Document-Literal Web services style.
Handler Registration and Unregistration
For each of the samples, the handlers are registered as start-up services and unregistered as
shut-down services. The services for registering and unregistering the handlers follow the same
naming conventions.




registerConsumerHandler is used to register the consumer handler.
unregisterConsumerHandler is used to unregister the consumer handler.
registerProviderHandler is used to register the provider handler.
unregisterProviderHandler is used to unregister the provider handler.
Note: The input parameters descriptiveName, QNameList, handleRequestService,
handleResponseService, and handleFaultService differ for each sample, and for providers and
consumers.
Sample1
This sample shows how to use a consumer handler to calculate the time required to execute a
Web service.
Description of the Handler





The service sample1.consumer.consumerHandler:handleRequest gets the current time
and, using the public service pub.soap.handler:setProperty, stores the value in the
message context.
The service sample1.consumer.consumerHandler:handleResponse uses the public
service pub.soap.handler:getProperty to recover the time stamp that was stored when the
Web service request left the consumer side.
The service gets the current time.
A calculation of the difference between the two values approximates the time required to
execute the Web service.
That time is printed in the server log.
Sample2
Employing an order processing example, this sample describes how to do the following:




Add a new header document, using the consumer handler’s request service.
Process the header document sent by the consumer, using the provider handler’s
request service.
Add another header document indicating the processing status, using the provider
handler’s response service.
Retrieve the status sent by the provider as a header document, using the consumer
handler’s response service.
The following panel fragment shows a simple request document that can be sent as a header
document for provider processing.
The following panel fragment shows a response document that indicates whether or not the order
is executed.
Description of the Handler
In the commentary below, the provider contains logic to check for vendor information, with the
order processed only when the value for “vendor” is set to the string “SAG”.




The sample2.consumer.consumerHandler:handleRequest service adds the sample2Doc
as header information, using the public service pub.soap.handler:addHeaderElement.
The value of the “vendor” is set to “SAG” and the “orderNum” is set to 1.
The sample2.provider.providerHandler:handleRequest service retrieves the request
header information using the public service pub.soap.handler:getHeaderElement. The
outputHeaderDocument contents are mapped to sample2Doc. The vendor field in the
retrieved header information is validated for the string “SAG”. If the result is true, the
handler returns true by setting the statusCode to 0. If it is not true, the handler returns a
fault with the message “Illegal vendor name”.
The sample2.provider.providerHandler:handleResponse service adds the
sample2ResponseDoc as header information using the public service
pub.soap.handler:addHeaderElement, with the isOrderExecuted parameter set to “true”.
The sample2.consumer.consumerHandler:handleResponse service retrieves the
response header information using the public service
pub.soap.handler:getHeaderElement. The contents of the outputHeaderDocument are
mapped to the sample2ResponseDoc. The field isOrderExecuted is validated for true. If it
is true, the message “order Executed” is printed in the server log. If it is not true, the
message “order NOT Executed” will be printed.
Sample3
This sample demonstrates usage of the service pub.soap.handler:removeHeaderElement, taking
the same order processing approach as the previous sample. However, in this sample, the
request header information is made available as a part of the WSDL contract.
The service pub.math:addInts is exposed as a Web service, and the sample3Doc is added to the
request header of the provider WSD. The consumer WSD and the Web service connectors are
generated by making use of the provider WSDL. When executing the Web service connector, you
need to provide the request header information.
Noncompliance will result in the server throwing an error, indicating that one or more required
headers are absent from the SOAP request.
The consumer handler will remove the header sent by the Web service connector.
Description of the Handler



The service sample3.consumer.consumerHandler:handleRequest gets the current time
and uses the public service pub.soap.handler:setProperty to store the current time in the
message context.
o Use the public service pub.soap.handler:removeProperty to remove the stored
current time.
o Use the public service pub.soap.handler:removeHeaderElement to remove the
header information added by the Web service connector.
Since the required header is removed by the consumer handler, the server will throw an
error indicating that one or more required headers are not present in the SOAP request.
The service sample3.consumer.consumerHandler:handleResponse uses the public
service pub.soap.handler:getProperty to query for the stored time. This service will return
null, since the time value was previously removed. The message “Unable to calculate the
Time Taken - Start Time is not valid” is printed in the server log.
Note: To make the sample work normally, disable these flow invoke steps in the service
sample3.consumer.consumerHandler:handleRequest:


pub.soap.handler:removeProperty
pub.soap.handler:removeHeaderElement
Sample4
This sample illustrates how to modify the SOAPMessage with the public services
pub.soap.handler:getSOAPMessage and pub.soap.handler:setSOAPMessage. The sample
shows how to modify the SOAPMessage so that the concatenated output is always “SOAP
BodyReplaced”.
The service pub.string:concat takes two strings as input and returns a concatenated string as
output. This service is exposed as the Web service. It creates a provider WSD, consumer WSD,
and the Web service connector. If you provide the value of parameter String1 as “myString1” and
the value of parameter String2 as “myString2”, the output value should be “myString1myString2”.
Description of the Handler
The service sample4.consumer.consumerHandler:handleRequest does the following
 Gets the existing SOAPMessage by calling the public service
pub.soap.handler:getSOAPMessage.
 Calls the public service pub.soap.utils:removeBodyEntry to remove the existing
SOAPBody. This call removes whatever input was provided for concatenating the strings.
 Converts the following hard-coded XML string to an XML node, using the public service
pub.xml:xmlStringToXMLNode. This node is input to the public service
pub.soap.utils:addBodyEntry, to add as a SOAPBody.
<tns:concat xmlns:tns="http://rramaiahd620.eur.ad.sag/sample4/provider/wsd/provider">
<inString1>SOAP Body</inString1>
<inString2>Replaced</inString2>
</tns:concat>

Calls the public service pub.soap.handler:setSOAPMessage to set the new
SOAPMessage.
Note: You need to call the service pub.soap.handler:setSOAPMessage to set the
SOAPMessage. The output of pub.soap.handler:getSOAPMessage returns a cloned copy of the
SOAPMessage available in the Integration Server. Any modifications to the SOAPMessage
returned as a result of the call to pub.soap.handler:getSOAPMessage can be made effective in
the Integration Server by calling pub.soap.handler:setSOAPMessage.