|
|
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:
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.
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.
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.
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.
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.
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).
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).
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.
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.
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.
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.
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.
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.
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
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.
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.
Background: Handling web service requests
Background: Understanding the service structure
Online
documentation - WebsydianExpress v3.0