|
|
This guide shows how you can create a simple service handler that receives a file and responds with another file.
A case would be when you need to receive a file from a client containing data you need to process. Based on the data contained in the request, you create another file that is returned to the client.
The abstract FileServiceHandler does not have any prerequisites to the type of data that is stored in the request and response files. Common examples could be comma-separated data or other text based data files.
To create the service handler in Plex, you define the following triples:
| Source Object | Verb | Target Object |
|---|---|---|
| MyServiceHandler | is a FNC | WSYAPI/Abstract.FileServiceHandler |
| MyServiceHandler | implement SYS | Yes |
This defines the correct interface for the function, which ensures that it can be called by the service processor.
It also provides information about the location of the input file containing the request and a proposed location for the output file where the handler can write its response data.
In the action diagram, there is an edit point "Handle request". At this point, the information transferred from the service processor will be available in the local variables InputFile, OutputFile, and Keys and the local variable RequestInformation has been populated with basic information about the request.
Open the action diagram and in the Post Point Handle Request, enter the code necessary for reading the file. The location of the file is found in the local variable InputFile.
After having read the file, create a response file in the location specified in the local variable OutputFile.
This handling is obviously dependent on the business logic that must be implemented.
How you can read the request file and write to the response file is very much dependent on the variant of WebsydianExpress you are using (WinC, WinC/iSeries, Java, iSeries) and how the data are structured in the file. In many cases you will have to create specialized source code objects in Plex to handle the file access and the interpretation of the data.
Some low-level Websydian functions handles reading and writing for text-based files. If you do not have an obvious solution for this, you are welcome to contact Websydian Support. Please specify the variant and WebsydianExpress version you are using and specify the type of data you want to read/write, and we will check if you can use any of our existing low-level functions for the purpose.
As the data will be returned to the client as an http-response, it is important to consider the content-type header that will describe the content of the response to the client.
The default behavior of the service processor is to return the content type of the request as the content type of the response.
For the FileServiceHandler, this will in some cases not be the correct behavior. You can control this by calling the SetContentType API.
The character set you specify must correspond to the character set of the data saved in the response file.
In general we recommend that you use the same character set as the one specified for the request, this can be found in the local variable RequestInformation.
If the request did not contain a charset in the Content-type header (e.g. text/xml instead of text/xml;charset=utf-8), the character set that is specified in the RequestCharset field in the RequestInformation variable is determined based on the default character set specified when starting the application service. This means that the received data might not correspond to the character set. It is highly recommended that all Content-type headers for text based data contain a charset.
Generate and build MyServiceHandler. Move the generated object to PlaceObjectsHere (Java, WinC, WinC/iSeries) or to the application library (iSeries, default WSP30APP).
After having created the function you must declare it the administration interface. This section will describe all three possible steps. However, in most cases both the URL and the relevant criteria will already have been defined in the structure - so only the last step will be necessary.
The site settings specify a URL extension that identifies the request as being a service request. The default for this is "service". This means that if your sites entry URL is:
http://MyServer/express30/site/basicsite
Then the URL
http://MyServer/express30/site/basicsite/service
Will specify that request is a service request.
The URL element in the service structure specifies an extension to the service URL. This URL is used to identify the service processor that will process the request and identify the handler.
To specify this URL, go to the service structure in the administration interface, select the root element and press "Add".
This opens a page where you enter the URL extension and some control parameters for the URL.
Specify the following:
Based on these values, and if you have defined the service URL described above, requests for the following URL will be handled by the FileServiceProcessor program:
http://MyServer/express30/site/basicsite/service/file
Apart from the URL extension, the most important entered value is the service processor. This specifies the program that extracts the information from the request and processes it before calling the service handler.
The selected program is one of the standard service processors, which is delivered as part of the runtime.
When the URL has been added to the service structure, you need to specify which rules the service processor that is specified by the URL should use to identify the service handler to call.
In this case, you will select a criteria of the type URL, which will make the service processor use the part of the URL following "http://MyServer/express30/site/basicsite/service/file" to identify the service handler.
In the service structure, select the URL "file", press "Add".
Specify the following:
Criteria: Select URL
Comment: Leave the field blank.
The previous two steps will often have been performed by an administrator. They will normally only have to be done once for each type of service you want to provide.
This last step is the one you will have to perform for each single service handler program you create. This is the step where you make the service handler publicly available.
Select the criterion you specified previously, press "Add". You will be shown a list of all existing service handlers. As you have just created the program, the handler will not exist in the list.
Press "Insert" to create the service handler.
Specify the following:
Status: Select "Active".
Program: Write the implementation name of the service handler program.
Name: Write "File handling".
Save files: Check the checkbox.
WSDL operation: Leave the field blank.
Comment: Leave the field blank.
Keep the two checkboxes for the input and output file checked.
Press "Insert" to create the service handler.
This creates the service handler and adds it to the grid. The inserted service handler is shown at the top of the grid.
Press "Select" to add the service handler to the criterion.
A pop-up page is shown where you must enter the URL extension that will be used to identify the service handler.
Specify:
Criteria value: guide
Comment: Leave the field blank.
This means that all requests that target the URL:
http://MyServer/express30/site/basicsite/service/file/guide
Will be handled by the service handler.
The check mark in the Save files checkbox ensures that the temporary files generated by the handling of the requests will not be deleted by the service processor.
You can't use the browser to test most of your services. The requests from a browser will always be in a URL-encoded format - and can't contain e.g. the xml data necessary to test a XML-based web service.
To help make it possible for you to test your services, we have made the (very basic) test tool we use ourselves available on our download page.
Specify the following values:
If the URL specifying the handler is: "http://MyServer/express30/site/basicsite/service/file/guide" (see above):
Internet ServerName: MyServer
Port: 80 (if the URL starts with MyServer:nnnn/...) - then you specify the value nnnn.
URL: /express30/site/basicsite/service/file/guide
HTTP version: HTTP/1.1
Method: Post
Use SSL: *No
Request filename: Specify a file containing the request data.
Response filename: Specify a file to receive the response data. The file does not have to exist, but the folder it is placed in must exist.
In the header table, specify a suitable value for the content type (e.g. text/xml;charset=utf-8)
Press Execute, and check whether the response file contains the correct data.
Background: Handling web service requests
Background: Understanding the service structure
Example: Implementing a FileServiceHandler that returns an exisiting file
Online documentation - WebsydianExpress v3.0