Websydian v6.1 online documentationOnline documentation - WebsydianExpress v3.5

Service Processors

Introduction

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:

  1. Receive and pre-process the service request.
  2. Identify and call the service handler that contains the business logic.
  3. Post-process the response data and return the processed data to the client.

 

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:

  1. Save the data to a file, the location of which is then transferred as a parameter to the hander
  2. Load the data to an XML parser, resulting in an XML document that can be handled using the TransacXML patterns.

Similar examples of post-processing:

  1. Read the content of a response file created by the handler - return this content to the client.
  2. Read the content of a response XML document - return the content to the client.

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.

Service processors and sites

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.

Pre-defined service processors

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.

FileServiceProcessor

Functionality

  1. Receive the data from the request and save the data to a file
  2. Determine default location of the response file
  3. Identify and call handler
  4. Handle errors from handler
  5. Read the response data from a file created by the handler and return data to the client
  6. Delete temporary files

Step-by-step

1. Receive the data from the request and save the data to a file

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).

2. Determine the default location of the response file

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.

3. Identify and call handler

This is common for all the service processors, it is described above.

4. Handle errors from handler

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.

5. Read the response data from a file created by the handler and return data 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.

6. Delete temporary files

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.

 

Handler

When you specify the FileServiceProcessor as your service processor, your handlers should inherit from:

Abstract.FileServiceHandler.

XMLServiceProcessor

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.

Functionality

  1. Receive the data from the request and save the data to a file
  2. Load an XML document from the file
  3. Create an XML document for the response data
  4. Identify and call handler
  5. Handle errors from handler
  6. Save the response document to a file
  7. Send response to the client
  8. Delete XML documents and temporary files

 

1. Receive the data from the request and save the data to a file

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).

2. Load an XML document from the file

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.

3. Create an XML document for the response data

An XML parser document for the response data is created. The document is not populated.

4. Identify and call handler

This is common for all the service processors, it is described above.

5. Handle errors from handler

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.

6. Save the response document to a file

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.

7. Send response to 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.

8. Delete temporary files and XML documents

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.

 

Handler

When you specify the XMLServiceProcessor as your service processor, your handlers should inherit from:

Abstract.XMLServiceHandler

 

SoapServiceProcessor

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.

Functionality

  1. Receive the data from the request and save the data to a file
  2. Load an XML document from the file
  3. Extract the request document from the SOAP-Body.
  4. Create an XML document for the response data
  5. Identify and call handler
  6. Handle errors from handler
  7. Create a SOAP structure attach the response document to the SOAP-Body
  8. Save the response SOAP document to a file
  9. Send response to the client
  10. Delete XML documents and temporary files

 

1. Receive the data from the request and save the data to a file

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).

2. Load an XML document from the file

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.

3. Extract the request document from the SOAP-Body

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.

4. Create an XML document for the response data

An XML parser document for the response data is created. The document is not populated.

5. Identify and call handler

This is common for all the service processors, it is described above.

6. Handle errors from handler

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.

7. Create a SOAP structure attach the response document to the SOAP-Body

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.

8. Save the response SOAP document to a file

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.

9. Send response 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.

10. Delete temporary files and XML documents

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.

 

Handler

When you specify the SoapServiceProcessor as your service processor, your handlers should inherit from:

Abstract.XMLServiceHandler.

Creating your own service processors

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:

  1. You do not want to use the service structure to identify the handler to call
  2. You have created your own special selection criteria
  3. You need to perform special pre- or post- processing of the data before calling the handler

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.

 

More Information

Background: Handling web service requests

Background: Selection criteria

Background: Service handlers

Background: WSYAPIWS model

Background: Understanding the service structure

Reference: Global settings

API: SetHttpStatus

API: SetFileName

API: SendHeader

API: GetXMLDoc

API: SetSoapFault

API: SetContentType

Abstract function: ServiceProcessor

Abstract Function: FileServiceProcessor

Abstract Function: XMLServiceProcessor

Abstract Function: SoapServiceProcessor