|
|
XMLAbstract.XMLServiceHandler
Please note that this function is found in the WSYAPIWS model.
XMLServiceHandlers are the functions that are custom developed to handle the data for a specific type of request.
It is in your implementations of the abstract XMLServiceHandler function you will code your own business logic to handle specific types of request where the request and response are XML documents and where the handling of the XML data are performed using TransacXML.
The function is called by a service processor. This is done as a dynamic call. To keep this as simple as possible, all parameters are transferred using a memory store, the XMLServiceHandler contains code that reads this memory store, and populates local variables with the data.
The abstract XMLServiceHandler reads TransacXML object-references for the input and output documents from the memory store. These references are stored in the local variable InputDocument and OutputDocument.
This abstract function is normally used together with either an XMLServiceProcessor or SoapServiceProcessor function. The ServiceProcessor function has received the data from the request and loaded an XML document with the data.
At this point the XMLServiceHandler is called.
After the call to the XMLServiceHandler function, the ServiceProcessor writes the output document to a file and returns the data to the client.
You should create one function that inherits from the XMLServiceHandler for each document you want to be able to receive as a file.
In the XMLServiceHandler, you find the edit point Handle Request. When this edit point is reached, the InputDocument and OutputDocument local variables have been populated.
In the InputDocument variable, you will find the ObjectStoreReference and the ObjectDocument specifying the input document.
In the OutputDocument variable, you will find the ObjectStoreReference and the ObjectDocument specifying the output document.
Place your handling of the request data and the creation of the response document in this edit point.
To retrieve the data from the input document, you must define the structure of the input XML document in the Plex model using the standard TransacXML definitions.
You can either use the GetFirstOccurrence/SingleFetch/ProcessGroup functions or the TraverseAndFetch functions scoped by the XMLElement entities to retrieve the data from the input document.
To populate the output document with data, you must define the structure of the output XML document in the Plex model using the standard TransacXML definitions. Use the InsertRow functions scoped by the XMLElement entities to insert the data in the document.
You must always write the output data to the XML document specified by the references in the OutputDocument local variable.
Changing the values of the fields in the OutputDocument variables will not have any effect. The calling ServiceProcessor function will still use the values it has written to the memory store.
If the handling of the data results in an error that must be reported to the client, you should set the Environment.*Returning status field to *Error. You can still write data to the output file - e.g. error information for the client. Setting the *Returning status to error will make the service processor return HTTP Status 500 to the client. If you want to override this, you can use the API SetHttpStatus to specify the HTTP status you want to report to the client.
Apart from the information about the input and output files, you can find other information from the request in the local variable RequestInformation.
In the local variables Keys, you can find the keys for the records that have been used to determine that this specific ServiceHandler has been called.
An XMLServiceHandler function can be used to handle XML documents that have been received as part of a SOAP request in exactly the same way it can be used to handle requests where the XML documents that are received and returned are the complete data content of the request/response.
The SoapServiceProcessor extracts the request document from the SOAP-envelope and transfers the content to the XMLServiceHandler, where the references to this request will be available in the InputDocument variable. In the same way, the service processor will wrap the document specified in the OutputDocument variable in a SOAP-envelope before returning the data to the user.
Because of this, you can let the exact same function handle request documents that have been received as part of a SOAP request and request documents that have been received as non-SOAP requests.
However, SOAP requests can contain relevant data in other parts of the SOAP-Envelope. The SoapServiceProcessor makes this information available in the memory. The data can be retrieved using the GetXMLDoc API. Specify "Header" for the WSType parameter to get object references to the Header element of the SOAP-envelope. Specify "Envelope" to retrieve the entire request document (Envelope including headers, body and request document).
The SOAP-standard provides a standard format for reporting errors. This consists of a Structure containing a fault code and a fault string. If you set *Returning Status to *Error, the SoapServiceProcessor will report a default fault to the client. You can provide more specific error information by calling the API SetSoapFault.
An example implementation of an XMLServiceHandler can be found in the WSYAPIWS model:
_Examples.Greet.GreetHandler
Please note that all ServiceHandlers are called dynamically based on the entries specified in the service structure tree. This means that you may not change the interface of the implemented function.
You should either use the XMLServiceHandler functions together with the XMLServiceProcessor/SoapServiceProcessor functions or, if you create your own service processor that does not inherit from either XMLServiceProcessor or SoapServiceProcessor, ensure that the SetXMLDoc API has been called for both input and output before the XMLServiceHandler function is called.
As the function uses the TransacXML patterns, it is placed in the WSYAPIWS model instead of the WSYAPI model.
The function can only be used in the Java, WinC, and WinC/iSeries versions - not in the iSeries version.
Background: Handling web service requests
Abstract function: XMLServiceProcessor
Abstract Function: SoapServiceProcessor
Online documentation - WebsydianExpress v3.0