Websydian v6.1 online documentationOnline documentation - WebsydianExpress v3.5

FileServiceHandler Example - Return Existing File

Introduction

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.

Service handler

The service handler that implements the service is:

WSYAPI/_Examples.ReturnExistingFile

The service handler performs three different steps:

  1. Retrieve a document-identification from the URL
  2. Map this identification to a physical filename - make this information available for the service processor.
  3. Specifies the http-headers that are used to instruct the browser to load the response as a pdf document.

Each step is explained in more detail below - it is recommended to follow the action diagram code while reading this explanation.

Subroutine Handle Request

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.

Subroutine Find output file

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.

Subroutine Set headers

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.

Publishing the service

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.

Testing the service

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.

More information

Background: The WSYAPIWS model

Background: Handling a web service request

Background: Understanding the service structure

Background: Service handlers

Background: Service processors

Background: Selection criteria

Guide: Implementing a file service handler

Guide: Testing services

API: SetHttpStatus

API: SendHeader

API: SetContentType

API: GetTemporaryFileFolder

API: SetFileName