|
|
This guide shows how you can create a simple service handler that receives an XML document and returns another XML document to the client.
A prerequisite for using a XMLServiceHandler function is that the request and response data are valid XML-data that can be parsed by an XML parser.
As the XMLServiceHandler function receives the references to the request and response documents as TransacXML object references, you must use TransacXML to process the data.
The abstract XMLServiceHandler function is found in the WSYAPIWS model.
The XMLServiceHandler is not available in the iSeries variant.
To create the service handler in Plex, you define the following triples:
| Source Object | Verb | Target Object |
|---|---|---|
| MyServiceHandler | is a FNC | WSYAPIWS/Abstract.XMLServiceHandler |
| MyServiceHandler | implement SYS | Yes |
This defines the correct interface for the function, which ensures that it can be called by the service processor.
It also provides TransacXML object references to the input document the handler must read from and the output document the handler must write to.
In the action diagram, there is an edit point "Handle request". At this point, the information transferred from the service processor will be available in the local variables InputDocument, OutputDocument, and Keys and the local variable RequestInformation has been populated with basic information about the request.
The request document information is found in the local variable InputDocument.
You can use this information to access the data in the XML document by using the GetFirstOccurrence/SingleFetch/ProcessGroup or the TraverseAndFetch functions scoped by the XMLElement entities that model your request document.
When using these functions you must specify the fields InputDocument<WSObjectStoreReference> and InputDocument<ObjectDocument> to map to the ObjectStoreReference and ObjectDocument parameters.
The output document has been created by the service processor, the identification of the document is found in the local variable OutputDocument.
Use the InsertRow functions scoped under the XMLElement entities that model your response document.
When using these functions you must specify the fields OutputDocument<WSObjectStoreReference> and OutputDocument<ObjectDocument> to map to the ObjectStoreReference and ObjectDocument parameters.
Generate and build MyServiceHandler. Move the generated object to PlaceObjectsHere.
After having created the function you must declare it the administration interface. This section will describe all three possible steps. However, in most cases both the URL and the relevant criteria will already have been defined in the structure - so only the last step will be necessary.
The site settings specify a URL extension that identifies the request as being a service request. The default for this is "service". This means that if your sites entry URL is:
http://MyServer/express30/site/basicsite
Then the URL
http://MyServer/express30/site/basicsite/service
Will specify that request is a service request.
The URL specifies an extension to the service URL. This URL is used to identify the service processor that will process the request and identify the handler.
To specify this URL, go to the service structure in the administration interface, select the root element and press "Add".
This open a page where you enter the URL extension and some control parameters for the URL.
Specify the following:
Based on these values, and if you have defined the service URL described above, requests for the following URL will be handled by the XMLServiceProcessor:
http://MyServer/site/basicsite/service/xml
Apart from this, the most important entered value is the service processor. This specifies the program that extracts the information from the request and processes it before calling the service handler.
The selected program is one of the standard service processors, which is delivered as part of the runtime.
When the URL has been added to the service structure, you need to specify which rules the service processor that is specified by the URL (see above) should identify the service handler to call.
In this case, you will select a criteria of the type "Top element name", which means that the name of the top element of the request document will be used to identify the service handler to call.
In the service structure, select the URL "xml", press "Add".
Specify the following:
Criteria: Select Top element name
Comment: Leave the field blank.
The previous two steps will often have been performed by an administrator. They will normally only have to be done once for each type of service you want to provide.
This last step is the one you will have to perform for each single service handler program you create. This is the step where you make the service handler publicly available.
Select the criterion you specified previously, press "Add". You will be shown a list of all existing service handlers. As you have just created the program, the handler will not exist in the list.
Press "Insert" to create the service handler.
Specify the following:
Status: Select "Active".
Program: Write the implementation name of the service handler program.
Name: Write "XML handling".
Save files: Check the checkbox.
WSDL operation: Leave the field blank.
Comment: Leave the field blank.
Keep the two checkboxes for the input and output file checked.
Press "Insert" to create the service handler.
This creates the service handler and adds it to the grid. The inserted service handler is shown at the top of the grid.
Press "Select" to add the service handler to the criterion.
A pop-up page is shown where you must enter the URL extension that will be used to identify the service handler.
Specify:
Criteria value: Specify the name of the top element of your request document.
Comment: Leave the field blank.
This means that all requests that target the URL:
http://MyServer/express30/site/basicsite/service/xml
And contains a valid XML document with the specified name of the top element will be handled by the specified service handler.
The check mark in the Save files checkbox ensures that the temporary files generated by the handling of the requests will not be deleted by the service processor.
You can't use the browser to test most of your services. The requests from a browser will always be in a URL-encoded format - and can't contain e.g. the xml data necessary to test a XML-based web service.
To help make it possible for you to test your services, we have made the (very basic) test tool we use ourselves available on our download page.
Specify the following values:
If the URL specifying the handler is: "http://MyServer/express30/site/basicsite/service/file/guide" (see above):
Internet ServerName: MyServer
Port: 80 (if the URL starts with MyServer:nnnn/...) - then you specify the value nnnn.
URL: /express30/site/basicsite/service/file/guide
HTTP version: HTTP/1.1
Method: Get
Use SSL: *No
Request filename: Specify a file containing the request data.
Response filename: Specify a file to receive the response data. The file does not have to exist, but the folder it is placed in must exist.
In the header table, specify a suitable value for the content type (e.g. text/xml;charset=utf-8)
Press Execute, and check whether the response file contains the correct data.
Background: Handling web service requests
Online documentation - WebsydianExpress v3.0