|
|
This document describes the example file service that is delivered as part of the demosite.
The service handler returns one of three documents based on information specified in the URL of the request.
Services like this can for instance be used to service product sheets or images based on an item-identification.
In this example, the service handler sends headers that instruct the browser to load the document instead of saving it.
The service handler that implements the service is:
WSYAPI/_Examples.ReturnExistingFile
The service handler performs three different steps:
Each step is explained in more detail below - it is recommended to follow the action diagram code while reading this explanation.
This subroutine starts by calling the low-level WSYBASE/GetHeaderOrEnvironmentVariable function. This is a function that can retrieve information about the request that is not normally available. Calling this function with the parameter <EnvironmentProperty.Query string> retrieves the part of the URL that follows the "?".
So for the URL
http://...express30/site/demosite/service/file/pdf?WSDOCID=FIRST
The function will return WSDOCID=FIRST.
The service function SystemFunctions.GetRequestParameterValue splits this string and returns the value of the parameter (in the example above, this will be FIRST).
If the WSDOCID parameter is not part of the URL or no value is specified for the parameter, the service handler can't identify a document to service. In this case an error status should be returned to the client. This is ensured by calling the SetHttpStatus API with the code 400. In this case the field Environment<*Returning status> is set to *Error - this informs the service processor that it should not try to return any response document to the client.
The WSDOCID parameter specifies an alias for the document to load. In many cases the id will be something that you can use to generate the name of the file you want to return to the client. But to keep this example simple, a case structure that translates the id to a file name is used to find the name of the file to load.
If no file is identified, the SetHttpStatus API is used to specify the http status 404 to the client.
The next step is to find the folder the files are located in. In this case, the files are placed in a subfolder "example" that is scoped by the temporary folder that is specified for the installation.
The GetTemporaryFileFolder API is used to identify the temporary folder.
Finally the SetFileName API is used to inform the service processor about where it should find the output file.
If the service returns data, it must also return a content-type http header that specifies the type of data that is returned.
The default behavior of the service processors is to return the content type that was specified for the request. In this case, this is a meaningless behavior - as no request data are specified. This means the service handler must specify the content type to return to the client. This is done using the SetContentType API. The content type application/pdf is specified to indicate that a pdf document is returned.
Apart from the default headers that are handled by the service processors, you can specify additional headers using this SendHeader API.
In this case Content-disposition header is specified with the value "inline" to inform the browser that the document should be loaded instead of saved.
The generated objects are delivered as part of the runtime. In a normal situation; you would naturally have to start by moving the generated program objects to the correct application folder.
In the administration interface of the demosite open the service structure.
The three URLs each use a different service processor.
The service is deployed on the "file" URL.
The "file" URL element scopes one criterion: "URL".
This means that the runtime will use the part of the URL following "file" to identify a service handler for all requests that targets the URL:
...express30/service/site/demosite/file
The service handler for this service is scoped by the criteria - and the value for the criteria is specified as "pdf".
This means that the service handler will handle the requests that target:
...express30/service/site/demosite/file/pdf
The FileServiceProcessor saves the request data to a file and makes the name of the file available for the service handler.
After the service handler has been called, the processor returns the generated response file to the client.
As the service uses information that is part of the URL to identify the document to return, it does not need to provide any input document for the service.
This means that it can be called from a browser.
The http-headers that is specified for the response informs the browser that the response contains a pdf document that should be loaded in the browser.
To load the document in the browser, you must use a browser that has installed to suitable plug-in for showing pdf documents and the pdf extension must be assigned to this plug-in for your system.
Try accessing the service by entering the following URLs in the address field of the browser:
http://...express30/site/basicsite/service/file/pdf?WSDOCID=FIRST
http://...express30/site/basicsite/service/file/pdf?WSDOCID=SECOND
http://...express30/site/basicsite/service/file/pdf?WSDOCID=THIRD
Each of these URLs should load a different pdf document in the browser.
If you do not specify any WSDOCID or specify a non-existing id, an error page serviced by the webserver should be shown.
Background: The WSYAPIWS model
Background: Handling a web service request
Background: Understanding the service structure
Background: Service processors
Background: Selection criteria
Online documentation - WebsydianExpress v3.0