|
|
The service handlers are the programs that perform the actual handling of a service request. It is the service handler that will perform the business logic that handles the request and creates the response for the client.
When a service request is received, the runtime uses the service structure to identify the service handler that should handle the request. The service handler receives the data contained in the request, either as the location of a file containing the data or as TransacXML object-references to an XML parser document containing data in the XML format.
The handler can choose to either handle the data right away or choose to just save the data for later processing.
The handler will often generate a response document, typically in the same format as the received data.
It is important to note that the handlers are called dynamically - this means that you must always ensure that the handler has the correct interface. The way to do this is to inherit from one of the abstract handler functions.
The service handlers are common for all sites (as they are programs that can be called by the runtime - just like business processes).
This means that when you have created a service handler in one site, it can also be added to the service structure in all the sites that are provided by the WebsydianExpress installation.
A service handler is made publicly available by adding it to a selection criterion in the service structure.
There are currently three different abstract service handler functions:
Follow the links to find detailed information about each abstract function
The abstract function XMLServiceHandler is placed in the WSYAPIWS model.
To use this model and the functions defined in it, you must have access to the TransacXML libraries.
Functions inheriting from XMLServiceHandler can only be used in the Java, WinC, WinC/iSeries variants.
In general, you should inherit from either FileServiceHandler or XMLWebServiceHandler.
If you are receiving XML data that you want to process using TransacXML, you must inherit from XMLServiceHandler.
If you are receiving non-XML data, or don't want to process the data using TransacXML, you should inherit from FileServiceHandler.
The service handlers retrieve the basic request information and make it available in the local variable RequestInformation.
Apart from this, the handlers also make the keys of the records in the service structure that has been used to identify the service handler in the local variable Keys. In addition to the keys of the records in the service structure, the local variable also contains the criterion name and the criterion value that has been used to determine which service handler to call.
You can use the GetOfferedService and GetControlProgram to retrieve information about the service handler and the service processor records from the service structure.
The above is populated for all service handlers. In addition to this, the specialized handlers also have a local variable containing information about the request data and one containing information about the response data:
The variable InputFile contains the location of a file containing the input data.
The variable OutputFile contains a proposed location of the file containing the output data.
You can change the OutputFile location by calling the SetFileNameAPI specifying "Output" for the WSType parameter.
The variable InputDocument contains the TransacXML references to the XML document containing the input data.
The variable OutputDocument contains the TransacXML references to the XML document where you must add the response XML data.
In the handlers, you have the option to either influence or override the functionality of the runtime in different ways.
The most common will be that you want to report an error to the client. You can do this in two different ways:
The runtime will return http-status 500 to the client (unless SetHttpStatus has been called, see below). If the SoapServiceProcessor is used, a SOAP-fault document will also be returned, otherwise no data will be returned to the client.
Calling this API allows you to take full control of the http-status that will be returned to the client.
If you set Environment<*Returning Status> to *Successful, and call the SetHttpStatus API, the runtime will return the Http-status you have specified and at the same time, it will return any response data the handler has generated.
Another thing you can influence is the content type of the response data. The default behavior of the runtime is to respond with the content type that was specified for the request.
You can override this by calling the SetContentType API.
Please note that the charset attribute specified for the content-type must correspond to the character set of the data you return to the client.
A general explanation of how to implement an XMLServiceHandler
Background: Handling web service requests
Background: Understanding the service structure
Abstract function: Abstract.ServiceHandler
Abstract function: Abstract.FileServiceHandler
Online
documentation - WebsydianExpress v3.0