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

Selection Criteria

Introduction

The selection criteria are used by the delivered service processors to determine which handler program to call. The data used for this selection is based on the service structure defined in the administration interface.

When you provide a service using WebsydianExpress, you will have to define three different things:

  1. A URL extension to the basic URL for the current site that determines which service processor to use.
  2. The selection criteria that will be used to evaluate the request sent to this URL
  3. The handlers that can be called for this URL - together with the criterion value that will mean that this exact handler is being called.

 

Example:

You want to have a SOAP based "Create Order" service. You want the SOAPAction header for this service to be "CreateOrder".

You will start by specifying a URL that can be used for all the SOAP based services.

For this URL, you specify that the criterion "SOAPAction" should be used.

You then code and create you handler program and add this to the criterion. While doing so you specify the value "CreateOrder" for the criterion value.

This means that all requests that are sent to the specified URL, and which contains the HTTP-header SOAPAction with a value of "CreateOrder" will be transferred to the specified handler program.

 

So the selection criteria can been seen as an instruction to the service processor about what value it should extract from the request to identify the handler - in the above example, the value was the value for the SOAPAction header.

You can specify more than one selection criterion for a specific URL. When you do so, the service processor will first evaluate the first criterion, if it finds a handler based on this criterion, it will call this handler - and then terminate. If it does not find a handler, it will proceed to the second criterion etc.

Selection criteria and sites

The selection criteria are common to all sites. This means that as soon as you have specified a criterion in one site, it is available in the rest of the sites of the WebsydianExpress installation.

Pre-defined criteria

The service processors that are delivered as part of the runtime contains handling of the criteria described below. If you create your own service processor, and inherit from the abstract ServiceProcessor function either directly or indirectly, your service processor will also contain the handling of these criteria.

The description of the criteria is an explanation of how the implemented service processor interprets these criteria - if you have created your own service processors where you have overridden the basic handling of the criteria, this description will obviously no longer be valid.

Http-Header

This criterion enables you to use the value for a specific http-header to identify the handler to call.

When you add the criterion to the URL, you must specify which header you want to extract the value for.

When you add a handler program to the criterion, you must specify the value of this header that should lead to a call of this handler.

You can add several HTTP-header criteria to the same URL - just specify different header names for each criterion you add.

Example:

You want to use the Content-type header to identify the handler to call.

Add a HTTP header criterion to the relevant URL; specify "content-type" for the header name.

When adding a handler, specify which content-type you want the handler to process.

Program

As there is no way the runtime can implement all possible types and combination of criteria, the program criterion enables you to specify a program in which you can create your own logic for finding the handler program to call.

When you add the program criterion to the URL, you must specify the implementation name of the program you want to call.

When you add a handler to this criterion, you can specify any value you want to use in your program as the identification of the handler to use.

Let the specified program inherit from the function Abstract.SelectionCriteriaProgram to ensure that the interface is correct (the program is called dynamically by the runtime - any changes to the interface will lead to a runtime error).

Example

You need information about several http-headers to identify the correct handler to call (the standard http header criterion only allows for one header to be evaluated).

In the implemented function you can retrieve the value specified for each of the relevant headers using the WSYBASE/GetHeaderorEnvironmentVariable function - and create the logic that uses the values for these header to identify the suitable handler.

When you add the program criterion to the URL, you specify the implementation name of the program where you have entered the logic.

When you add a handler to the criterion, you can e.g. enter the values of the two header separated by a blank space (or another appropriate separator).

Request parameter

Apart from the address part of the URL, it can be followed by a number of request parameters - for example:

http://MyServer/express/site/basicsite?PARM1=ABC&PARM2=DEF

In the example, PARM1 and PARM2 are the available request parameters.

The request parameter criterion enables you to use the values specified for a request parameter to select the handler to call.

When you add this criterion to the URL, you must specify which request parameter you want to use the value for (e.g. PARM1).

When you add a handler to this criterion, you must specify the value of the request parameter that should lead to a call of this handler.

Example

You want to use the value of the PARM1 request parameter in the example URL to identify which handler to call.

Add a request parameter criterion to the URL, specify PARM1 as the request parameter name.

When you add a handler to this criterion, specify the value (e.g. ABC) that means that the handler should be called.

SOAPAction

For SOAP-requests, the standard describes a specific http-header that should be used to specify which of several operations that are provided by a URL a request should be handled by.

The SOAPAction criterion enables you to specify a value for the SOAPAction header for each handler you provide for a URL.

When you add the criterion to the URL, there is no additional information to provide.

When you add a handler to the criterion, you must specify a value for the SOAPAction header for the handler.

Example

You want to provide an order information service, where customers can ask for the state of their orders. The service should have the SOAPAction "http://MyServer/express/site/basicsite/service/soap/OrderInformation".

Add the SOAPAction criterion to the URL.

Add the handler to the criterion; specify "http://MyServer/express/site/basicsite/service/soap/OrderInformation" for the SOAPAction value.

Top element name

The top element name criterion enables you to use the name of the top element in an XML document to select the handler that should process the document.

When you add the criterion to the URL, there are no additional information to provide.

When you add the handler to the criterion, you must specify the local name of the top element of the request document the handler can process.

Please note that it is the local name of the top element only - any namespace prefix is not part of the value, as it can change unpredictably.

So if you have the following top element:

<pr:topName xmlns:pr="namespace">

    ...

</pr:topName>

- the local name is topName - not pr:topName.

The criterion is only implemented in the XMLServiceProcessor and SoapServiceProcessor functions.

This means that this criterion is not available for the iSeries variant of WebsydianExpress.

Example

You have a handler that should process a document which has the top element shown above.

Add the top element name criterion to the URL.

Add the handler to the criterion, specify topName for the top element name.

URL

The URL criterion enables you to use a part of the URL to identify which handler to call.

When you add the criterion to the URL there is no additional information to specify.

When you add the handler to the criterion, you will

 

The part used will always the section immediately following the part that was used to identify the selection criteria.

So if you have a basic URL for your site:

http://MyServer/express/site/basicsite

And have specified "service" for the service extension on the site settings - all requests for this URL will be handled as service requests:

http://MyServer/express/site/basicsite/service

You then add a URL to the tree structure - and for this URL you will specify which service processor you want to handle the requests for this URL - if you e.g. specify the URL Mask "myservice" - the URL will be:

http://MyServer/express/site/basicsite/service/myservice

The URL criterion uses the next part of the URL to find the handler - so if you specify "myvalue" for the criteria value - the handler will process all requests sent to this URL:

http://MyServer/express/site/basicsite/service/myservice/myvalue

 

Please note that any following part of the URL will be disregarded - so the handler will also receive requests sent to the following URL's:

http://MyServer/express/site/basicsite/service/myservice/myvalue/etc

http://MyServer/express/site/basicsite/service/myservice/myvalue?PARM1=ABC

Example

You want to have a service that can receive any text based file sent to the system and save the file.

You have defined the following URL in the service structure:

http://MyServer/express/site/basicsite/service/myservice

And you want to provide the service that saves the files at:

http://MyServer/express/site/basicsite/service/myservice/save

Add the URL criterion to the URL (myservice).

Add the handler to the criterion, and specify "save" as the value.

Defining your own criteria

The administration interface allows you to create your own selection criteria. After you have created the criteria, you will be able to add them to the URLs in the service structure just like you can add the system defined criteria.

However, you should note that the existing processors will not perform any handling of these criteria, so for the special criteria to have effect, you must always implement your own service processors.

Before defining your own criteria, you should consider whether you can obtain the same functionality using the "Program" selection criterion.

More information

Background: Handling web service requests

Background: Understanding the service structure

Abstract function: ServiceProcessor

Abstract function: SelectionCriteriaProgram