|
|
Abstract.FileServiceHandler
ServiceHandlers are the functions that are custom developed to handle the data for a specific type of request.
It is in your implementation of FileServiceHandler functions you will code your own business logic to handle specific types of request where the request and response are data contained in files.
The function is called by the service processor - this is done as a dynamic call. To keep this as simple as possible, all parameters are transferred using a memory store, the FileServiceHandler contains code that reads this memory store, and populates local variables with the data.
The abstract FileServiceHandler reads the name and location of where the service processor has saved the input file, and reads where the service processor proposes the output file should be saved. These data are written to the local variables InputFile and OutputFile.
This abstract function is normally used together with a FileServiceProcessor function. The FileServiceProcessor function has received the data from the request and saved them to the input file.
At this point the FileServiceHandler is called.
After the call to the ServiceHandler, the ServiceProcessor reads the output file and returns the data to the client.
You should create one function that inherits from the FileServiceHandler for each document you want to be able to receive as a file.
In the FileServiceHandler, you will find the edit point Handle Request. When this edit point is reached, the InputFile and OutputFile local variables have been populated.
In the InputFile variable, you will find the location of the file containing the data received with the request.
In the OutputFile variable, you will find the location, the service processor proposes for the file containing the data that should be returned to the client. Please note that this file does not exist - it is only a proposed location.
Place your handling of the request data and the creation of the file containing the data that must be returned to the client in this edit point.
In some cases, you might want to return an existing file to the client instead of creating a new one. You can specify this by calling the SetFileName API with the WSFileType parameter set to "Output". When you choose to change the output file, the service processor will not delete this file, even though the other temporary files are deleted. This avoids the necessity to copy the file if you want the file to exist after the request has been handled.
In general, if you create a new file containing the output data, you should save this file in the location specified in the OutputFile variable, this makes it possible for the service processor to either keep the file or delete it based on the settings for handling temporary files specified for the service handler and the settings for the requestlog.
If the handling of the data results in an error that must be reported to the client, you should set the Environment.*Returning status field to *Error. You can still write data to the output file - e.g. error information for the client. Setting the *Returning status to error will make the service processor return HTTP Status 500 to the client. If you want to override this, you can use the API SetHttpStatus to specify the HTTP status you want to report to the client.
Apart from the information about the input and output files, you can find other information from the request in the local variable RequestInformation.
In the local variables Keys, you can find the keys for the records that have been used to determine that this specific ServiceHandler has been called.
An example implementation of a FileServiceHandler can be found in the WSYAPI model:
_Examples.CopyServiceHandler
Please note that all ServiceHandler functions are called dynamically based on the entries specified in the service structure tree. This means that you may not change the interface of the implemented function.
You should either use the FileServiceHandler functions together with the FileServiceProcessor functions or, if you create your own service processor that does not inherit from FileServiceProcessor, ensure that the SetFileName API has been called for both input and output before the FileServiceHandler function is called.
Background: Handling web service requests
Abstract function: FileServiceProcessor
Guide: Implementing a FileServiceHandler function
Guide: Implementing a FileServiceHandler that returns an exisiting file
Online documentation - WebsydianExpress v3.5