|
|
This document is an introduction to the web service functionality provided by WebsydianExpress.
This document shows the tasks you have to perform to create and publish the web service - and provides a number of links to documents where each of the elements used to handle web service requests are explained in more detail.
Providing a web service using WebsydianExpress is a two-step procedure:
This can be compared with what is done for business processes in Websydian Express:
The most obvious difference is that you where you will create a number of programs to provide a business process (ProcessEntryPoints, EventHandlers, and PageGenerators); the most common situation for web service requests will be that you will only create one program that handles a specific request.
Note that the web service handling of WebsydianExpress does not include publishing services that are created using other tools - the aim is only to make it possible to provide custom developed WebsydianExpress programs as web services.
Handling a web service request is at the most basic level a question of receiving some request data, reading and processing these data, and creating response data based on this processing.
Fundamentally, the request and response data can be in any text-based format - common cases are XML documents, XML documents wrapped in a SOAP envelope, comma-separated files, and files containing structured records.
A developer must create a program that handles the request and generates the response. In WebsydianExpress, these programs are called service handlers.
The precise functionality of each service handler is determined by the format of the request and response document and the business logic that should be implemented to perform the service. This means that each service handler must be custom developed to perform the necessary tasks.
As a service handler is called dynamically by WebsydianExpress, it has to have a specific parameter interface. You ensure that this is the case by inheriting from WSYAPI/Abstract.ServiceHandler or another abstract function that inherits from it.
The most important thing to note is that the developer does not have to receive the data or return the data to the client - this is handled by Websydian Express. Depending on the type of service handler the implemented function inherits from it will either have access to the folder/file location of the request and response files or TransacXML object references to request and response XML documents.
The identification of which service handler that should process a request is also handled by WebsydianExpress, so the developer only has to concentrate on the processing of the data.
For developers with Websydian/WebsydianExpress experience, the service handler can to some degree be seen as having the same role as an EventHandler in a common web application - it receives information from a request and processes this information. But where the EventHandler then calls a PageGenerator to create the response, this will normally also be done by the service handler.
For developers who has experience with handling comma-separated files or other types of structured data, a service handler can be compared to the program that (normally) has been created to handle the content of a specific type of file.
After the program has been created, it has to be made publicly available. The way to do this is to add the service handler to the service structure using the menu item Web services in the administration interface.
To publish a service handler, you need to specify three different things:
The following description will go through the steps that must be performed when you want to publish a service handler. Note that the steps "Specifying the URL" and "Selecting the selection criterion" only has to be performed once for each URL you want to provide services at while the last step "Adding the service handler" has to be performed for each new service handler you want to publish.
To specify the URL, you must add a URL element to the root of the service structure.
After adding the URL element it will be shown in the service structure as follows:
When you add the URL element the two most important things you specify is:
When you specify a URL element, you specify the extension to the general service-URL that is specified for the site.
The general service-URL consists of the normal entry URL for the site and the service-URL extension. Both these settings can be found on the site settings page - and you can see the last part of the resulting URL as the text for the root element in the service structure.
So in the example shown above, the URL element xml specifies the URL:
http://.../express30/site/basicsite/services/xml ("..." must be replaced by servername:serverport - e.g. www.websydian.com or localhost:8080).
In addition to specifying the URL extension, you must also select the Service Processor that should handle the request and identify the service handler.
All service processors perform three different tasks:
There are three pre-defined service processors. These are delivered as part of the runtime:
The file service processor saves the received data in a file, identifies and calls the handler, retrieves the file containing the response data and returns these data to the client.
The XML service processor receives the data, loads the data using an XML parser, identifies and calls the handler function, extracts the data from the response document and returns these data to the client.
The soap service processor receives the data, loads the data using an XML parser, extracts the body document from the Soap envelope, identifies and calls the handler, wraps the response in a soap envelope, extracts the data containing the soap document and returns it to the client.
In the screen-shot, the XML Service Processor has been chosen - this is the service processor you will use to process XML documents using the TransacXML pattern libraries.
Each URL can be used to access a number of service handlers. To make it possible to identify which service handler that should be called, you must add one or more criteria elements to the URL element.
The selection criteria scoped by a URL element specifies how the service processor used by the URL element can identify the handler to call.
There are 6 basic selection criteria that can be specified:
In the screen shot, the criterion "Top element name" has been selected. This instructs the service processor to read the name of the top element of the request document and try to use this to identify a service handler.
The service processor and the selected criterion are predefined values that can be selected. As each service handler is custom developed, you must create a service handler record before you can add this to the criterion.
When you select the criterion and press "Add", a list of all defined service handlers is shown:
If it is an existing service handler you want to publish, you can just select it - but in most cases it is necessary to create the service handler record first.
Press Insert to go to the insert page for service handlers.
The most important information to specify is the program field. Here you must specify the implementation name of the service handler you want to publish.
Press "Insert" to create the service handler record.
The grid page will be loaded - showing the created service handler record - select this record to add it to the criteria.
When a record is selected, a pop-up window is shown. In this pop-up, you must specify the criterion value that will mean that the service handler is called. As the "Top element name" was selected, specify the name of the top element of the XML document that the service handler can process.
After adding the service handler to the criteria you have finished publishing the service.
The service structure now shows that if an XML document is sent to http://.../express30/site/basicsite/services/xml - and the name of the top element of this document is "MyTopElementName", then the service handler "Example program for documentation" will be called.
Each service handler can be added in several places in the service structure - just as each URL element can scope multiple selection criteria and each criterion can scope multiple service handlers.
If other web services of the same type already has been published for the site, both the URL element and the criterions will already have been specified. So the only thing you have to do to publish a new service handler is to create the service handler record - and add it to the criterion while specifying the value of the criterion that will mean that the service handler is called.
The description above explains the different steps that you must take to create and publish a web service using WebsydianExpress.
The diagram shows the same information - but it is more focused on how the request is being handled. The diagram and explanation of the same has been added to this document in order to provide an alternative way to understand the different elements that controls the handling of web service requests.
When WebsydianExpress receives a request, it is identified whether the request targets the service-URL specified on the site settings - if it does, the handling of web service requests is started.
The next step is to find the correct URL element in the service structure - this is done by comparing the part of the URL that follows the service-URL with the definitions in the service structure.
If you don't want to use this default way to identify the URL element that should be used, you can create a callback function for the callback point FindServiceProcessor - in this callback function you can override the way WebsydianExpress identifies the URL element.
When a URL element is identified, it also identifies the service processor to call.
The service processor uses the criteria that are scoped by the URL element to identify the service handler to call.
The service handler is the custom-developed program that is being published as a web service.
Background: Service processors
Background: Selection criteria
Background: Understanding the service structure
Reference: FindServiceProcessor callback point
Online
documentation - WebsydianExpress v3.0