WebsydianExpress - Callback Point

FindServiceProcessor

Type

Site specific callback point implemented by the handling of web service requests.

When is the callback point called

When the runtime has identified a request as being a web service request, it identifies a service processor that can perform the identification of the service handler that will perform the actual handling of the received data. This identification is done based on the URL that has been specified for the request.

The FindServiceProcessor is called after the WebsydianExpress runtime has performed the standard identification of the service processor to call, before the service processor is called.

How does the callback point influence later functionality

If no value is specified for the output field ServiceProcessorImplName, the runtime will not call any service processor.

Please note that any program specified must have the interface that is defined by the WSYAPI/Abstract.ServiceProcessor function. If you specify a value for the field, this identifies the program that will be called.

If you do not specify anything in the output field ServiceURLSurrogate, the program specified by the ServiceProcessorImplName parameter will be called. But as no URL element has been specified, the default resolving of the selection criteria based on the service structure can't be used. You will have to create your own logic for selecting a service handler and the calling of the handler in the program specified by the ServiceProcessorImplName parameter.

If you specify Yes for the parameter IntranetOnly, and the request has not originated in the intranet, an error will be returned to the client.

The input to the callback function contains the same three fields, the values specified in these fields are the ones that either the runtime or the previously called callback function have specified.

It is always the last callback function to be called that will determine the final result. It is up to the callback function to decide whether it will take the input into account.

Example of use

One case could be if it is necessary that all services are provided on the same URL (maybe because this makes it easier to setup special access for the services).

This means that the "normal" way of finding a service processor can't be used - as it uses a part of the URL to identify the URL element.

An alternative way to identify the service processor to call is to use a specific http-header.

All http-requests contain a number of http-headers. These http-headers are name-value pairs. In addition to the standard headers (e.g. Content-type, Content-length), you can specify other custom headers. You might for example specify that the http-header "ServiceProcessorSelect" is used to specify the service processor to call.

This can be done in the following manner.

To have this functionality, you need to do two things:

1. For each service processor you add to the site, you must specify a value for the http-header ServiceProcessorSelect.
2. Create a callback function that retrieves the value for the ServiceProcessorSelect header and identifies the corresponding service processor based on the values you specified previously.

1. Specify a value for the http-header

When you create a URL element in the service structure you would normally specify a value for the URL extension that identifies the element. As the URL extension is not used in this case, you can just use this field for the value of the http header. So if you want to call the FileServiceProcessor for the case where ServiceProcessorSelect=FILE - you would specify the value FILE for the URL-Mask.

2. Create a callback function

Create a callback function that inherits from: Callback.WebServer.FindServiceProcessor.AbstractCallbackFunction.

In this function, extract the http-header from the request. You can do this by calling WSYBASE/GetHeaderOrEnvironmentVariable - specify "ServiceProcessorSelect" for the EnvironmentProperty parameter.

After extracting the header, use the APIServer.WebServices.GetServiceURLsForSite API to read all the URL elements that has been specified for the site.

For each of these elements, compare the value of the field ServiceURLMask with the extracted header value.

After identifying the URL element that corresponds to the header, use the ServiceURLSurrrogate from this record to call the APIServer.WebServices.GetURLAndServiceProcessor API.

Use the output from this function to populate the CallbackOutput local variable.

Abstract callback function

Inherit from CallbackFunctions.CallbackPoints.WebServer.FindServiceProcessor.AbstractCallbackFunction to create a callback function that can be called by this callback point.

CallbackInput

This local variable contains:

• APIFields.ServiceURLSurrogate - The unique identification of the URL element record that either the runtime or a previously called callback function has specified.
• APIFields.SiteKey - The site specified by the URL of the request.
• APIFields.RequestID - The identification of the request that is being handled. Use the function: WSYBASE/GetCurrentRequestInformation to retrieve more information about the request.
• APIFields.EntryURL - The URL specified for the request.
• APIFields.ServiceURLMask - The part of the URL the runtime uses to identify the URL element.
• APIFields.ServiceProcessorImplName - The implementation name of the service processor that either the runtime or a previously called callback function has specified.
• APIFields.IntranetOnly - Specifies whether the service processor only will be called if the request originates from the intranet, this value has been determined by either the runtime or a previously called callback function.

CallbackOutput

This local variable contains:

• APIFields.ServiceURLSurrogate - Specify the unique identification of URL element. This will make it possible for the called service processor to use the data registered in the web service structure to determine the service handler to call.
• APIFields.ServiceProcessorImplName - Specify the name of the service processor that is to be called. Please note that any program specified must have the interface that is defined by the WSYAPI/Abstract.ServiceProcessor function
• APIFields.IntranetOnly - Specify whether the service handler function only is to be called if the request originates in the intranet.