|
|
When a request is received by the WebsydianExpress runtime, the first thing that happens is that it is identified as being either a common web request or a service request.
For the service requests, a part of the URL is then used to identify the service processor that will perform the next step in the processing of the request. The URL's that are used to identify service processors are found in the service structure in the administration interface.
When you add a URL to the service structure one piece of information you must provide is which service processor to call when a request target the specified URL.
The service processors perform three different steps:
The pre- and post- processing is highly dependent on the type of data the service processor can handle. In fact, it is normally the type and format of the data contained in the request that determines which service processor to call.
Examples of pre-processing of the data:
Similar examples of post-processing:
The service processor uses the definitions in the service structure to find out which handler to call.
For each URL, one or more selection criteria can be specified. For each of these criteria, you can add one or more handlers. For each handler you must specify the value of the criterion that means the handler should be called.
When the service processor receives a request, it reads each of the criteria scoped by URL in the service structure. For the current criterion, it extracts the corresponding value from the request. It then checks whether a handler is specified for this value of the criterion.
As soon as a handler is found, it is called. The service processor will not investigate any more handlers or criteria.
If no handler is found for a criterion, the next criterion scoped by the URL is read, and the process is repeated.
If no handler can be identified, an error is reported in the message log, and an HTTP-status error is returned to the client.
The service processors are common for all sites. This means that when you have created a service processor in one site, it is available in all the sites that are provided by the WebsydianExpress installation.
The runtime contains three implemented service processors that you can use as is.
These three programs will be shown as possible selections for the service processor when you add a URL to the service structure.
As these programs are delivered as a part of the runtime, you do not have to have a full understanding of how the functionality is coded.
However, there are certain things that you need to understand to be able to make the correct service structure definitions and to be able to investigate error situations.
This section describes each of the implemented service processors with special emphasis on the settings you can use to influence the behavior of the service processor and how the handler can influence the service processor.
The data sent by the client as part of the request is stored in a temporary file.
The base location of this file is determined by the global setting "Temp file location". You can find this location using the menu item "Global settings" in the administration interface.
When you add a URL to the service structure, you can specify an extension of the path specified in the global setting "Temp file location".
In this way you can specify a separate temporary file folder for each URL you are offering services for.
If you leave this setting blank for the URL, the files will just be saved to the base temporary folder.
So if the "Temp file location" is set to "/EXPRESS30/temp", and you specify the extension "soap" for a URL in the service structure, the temporary files for this URL will be saved to the folder:
"/EXPRESS30/temp/soap".
If this folder does not exist, the service processor will write an error to the message log, and terminate after returning an error status to the client.
The name of the file will be IN_ followed by the unique identification of the request (the request ID).
The service processor proposes a location for the response file. It is important to note that the file is not created by the service processor.
The location of the output file is determined in the same way as the location of the input file.
The name of the file will be OUT_ followed by the request ID.
This is common for all the service processors, it is described above.
If the handler has set an error in the *Returning status, the service processor will check if the handler has specified a special http-status that should be returned to the client (using the SetHttpStatus API). If the handler has set an http-status, this will be returned to the client. If not, http-status 500 will be returned to the client.
The service processor checks whether the handler program has specified another location for the response file. This can be done by calling the SetFileName API in the handler.
Before sending the data, the service processor will send a content-type header to the client. The content-type describes the data type (e.g. text/xml, text/html) and the character set of the response data.
If a content-type has been specified by the service handler (using the SetContentType API), this content-type will be used. If not, the content-type that was specified for the request will be used.
The service processor checks whether the service structure definitions for the handler specifies that it generates output data.
You can find this information by selecting the handler in the service structure and pressing update.
If output is specified for the handler, the size of the response file is checked - if the file contains data, the data is read from the file and returned to the client.
If the global setting "Requestlog enabled" is set to no, the temporary files are deleted.
If the requestlog is enabled, the name and location of the temporary file is written to the log, and the file is kept for diagnostic purposes.
Even if the requestlog is not enabled, you can prohibit the files from being deleted by checking the "Save Files" checkbox found on the handler page in the administration interface.
The output file is not deleted if the handler has overridden the location - this ensures that you can return e.g. an existing pdf file without it being deleted.
When you specify the FileServiceProcessor as your service processor, your handlers should inherit from:
Abstract.FileServiceHandler.
This service processor is only available in the Java, WinC and WinC/iSeries variants.
To be able to create a handler that can use the generated TransacXML documents, you have to have access to the TransacXML patterns.
The abstract function for the XMLServiceHandler function is found in the WSYAPIWS model.
The data sent by the client as part of the request is stored in a temporary file.
The base location of this file is determined by the global setting "Temp file location". You can find this location using the menu item "Global settings" in the administration interface.
When you add a URL to the service structure, you can specify an extension of the path specified in the global setting "Temp file location".
In this way you can specify a separate temporary file folder for each URL you are offering services for.
If you leave this setting blank for the URL, the files will just be saved to the base temporary folder.
So if the "Temp file location" is set to "/EXPRESS30/temp", and you specify the extension "soap" for a URL in the service structure, the temporary files for this URL will be saved to the folder:
"/EXPRESS30/temp/soap".
If this folder does not exist, the service processor will write an error to the message log, and terminate after returning an error status to the client.
The name of the file will be IN_ followed by the unique identification of the request (the request ID).
An XML parser document is created, and the input file is loaded into the document.
If the document is not loaded successfully, an error is written to the message log and the processing is terminated after an error has been returned to the client.
An XML parser document for the response data is created. The document is not populated.
This is common for all the service processors, it is described above.
If the handler has set an error in the *Returning status, the service processor will check if the handler has specified a special http-status that should be returned to the client (using the SetHttpStatus API). If the handler has set an http-status, this will be returned to the client. If not, http-status 500 will be returned to the client.
The handler receives the object references to the XML parser document where the response must be stored (this can't be changed by the handler).
After the handler has returned, the service processor saves this XML document to a file.
The location of the file is determined in the same way as the location of the input file.
The name of the file will be OUT_ followed by the request ID.
If an error occurs when saving the response document, an error is written to the message log and the program terminates after sending an error to the client.
Before sending the data, the service processor will send a content-type header to the client. The content-type describes the data type (e.g. text/xml, text/html) and the character set of the response data.
If a content-type has been specified by the service handler (using the SetContentType API), this content-type will be used. If not, the content-type that was specified for the request will be used.
The service processor checks whether the service structure definitions for the handler specifies that it generates output data.
You can find this information by selecting the handler in the service structure and pressing update.
If output is specified for the handler, the size of the response file is checked - if the file contains data, the data is read from the file and returned to the client.
All the XML parser documents created by the service processor are deleted.
Please note that if you create XML documents in your handler (using WSYDOM/DomServices.CreateDocument), you must always delete these documents before the handler terminates (using DomServices.DestroyDocument). Failure to do so leads to a memory-leak in the program.
If the global setting "Requestlog enabled" is set to no, the temporary files are deleted.
If the requestlog is enabled, the name and location of the temporary file is written to the log, and the file is kept for diagnostic purposes.
Even if the requestlog is not enabled, you can prohibit the files from being deleted by checking the "Save Files" checkbox found on the handler page in the administration interface.
When you specify the XMLServiceProcessor as your service processor, your handlers should inherit from:
Abstract.XMLServiceHandler
To be able to create a handler that can use the generated TransacXML documents, you have to have access to the TransacXML patterns.
The abstract function for the XMLServiceHandler function is found in the WSYAPIWS model.
The data sent by the client as part of the request is stored in a temporary file.
The base location of this file is determined by the global setting "Temp file location". You can find this location using the menu item "Global settings" in the administration interface.
When you add a URL to the service structure, you can specify an extension of the path specified in the global setting "Temp file location".
In this way you can specify a separate temporary file folder for each URL you are offering services for.
If you leave this setting blank for the URL, the files will just be saved to the base temporary folder.
So if the "Temp file location" is set to "/EXPRESS30/temp", and you specify the extension "soap" for a URL in the service structure, the temporary files for this URL will be saved to the folder:
"/EXPRESS30/temp/soap".
If this folder does not exist, the service processor will write an error to the message log, and terminate after returning an error status to the client.
The name of the file will be IN_ followed by the unique identification of the request (the request ID).
An XML parser document is created, and the input file is loaded into the document.
If the document is not loaded successfully, an error is written to the message log and the processing is terminated after an error has been returned to the client.
A SOAP request contains a SOAP-structure that contains the "real" request document. The service processor extracts the request document and transfers this document to the handler as TransacXML object references.
Apart from this, the service processor makes references to the SOAP-Envelope (the top element of the request document) and the SOAP-Header elements available for the handler. This information is also saved as TransacXML objectreferences. The references can be retrieved by the handler by calling the GetXMLDoc API.
An XML parser document for the response data is created. The document is not populated.
This is common for all the service processors, it is described above.
If the handler has set an error in the *Returning status, the service processor will check if the handler has specified a special http-status that should be returned to the client (using the SetHttpStatus API). If the handler has set an http-status, this will be returned to the client. If not, http-status 500 will be returned to the client.
The SOAP standard describes a fault structure containing a fault code and a fault string. The handler can specify values for these fields by calling the SetSoapFault API.
If the handler hasn't specified any fault information, the service processor returns a default fault code and fault string stating that an unexpected error has occurred.
Just as the request document was contained in a SOAP structure, the response must also be placed inside such a structure before being returned to the client.
The service processor creates a document containing a SOAP envelope, imports the response document into this document and attaches the response to the SOAP-Body of the SOAP structure.
The document created in step 7 is saved to a file.
The location of the file is determined in the same way as the location of the input file.
The name of the file will be OUT_ followed by the request ID.
If an error occurs when saving the response document, an error is written to the message log and the program terminates after sending an error to the client.
Before sending the data, the service processor will send a content-type header to the client. The content-type describes the data type (e.g. text/xml, text/html) and the character set of the response data.
If a content-type has been specified by the service handler (using the SetContentType API), this content-type will be used. If not, the content-type that was specified for the request will be used.
The service processor checks whether the service structure definitions for the handler specifies that it generates output data.
You can find this information by selecting the handler in the service structure and pressing update.
If output is specified for the handler, the size of the response file is checked - if the file contains data, the data is read from the file and returned to the client.
All the XML parser documents created by the service processor are deleted.
Please note that if you create XML documents in your handler (using WSYDOM/DomServices.CreateDocument), you must always delete these documents before the handler terminates (using DomServices.DestroyDocument). Failure to do so leads to a memory-leak in the program.
If the global setting "Requestlog enabled" is set to no, the temporary files are deleted.
If the requestlog is enabled, the name and location of the temporary file is written to the log, and the file is kept for diagnostic purposes.
Even if the requestlog is not enabled, you can prohibit the files from being deleted by checking the "Save Files" checkbox found on the handler page in the administration interface.
When you specify the SoapServiceProcessor as your service processor, your handlers should inherit from:
Abstract.XMLServiceHandler.
In addition to using the 3 pre-defined service processors, you have the option of creating your own specialized service processors.
As the service processor has a pre-defined interface that can't be changed, your implementations should always inherit from Abstract.ServiceProcessor. You may not change the interface of the implemented functions.
Each of the three pre-defined functions are built using a corresponding abstract function, so if your own service processor needs the same functionality as one of the implemented service processors you can inherit from one of the abstract functions:
Reasons for creating your own service processor could be:
If the reason is that you want to create your own selection criteria, you should first investigate whether the selection criterion "Program" could be a sufficient solution for your case. By using this criterion you must only create a program that handles the selection, not a special service processor.
Background: Handling web service requests
Background: Selection criteria
Background: Understanding the service structure
Abstract function: ServiceProcessor
Abstract Function: FileServiceProcessor
Online
documentation - WebsydianExpress v3.0