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

FileServiceHandler Example

Introduction

This document describes the example file service that is delivered as part of the demosite.

The example shows an implementation of a simple file based service which reads a text-based request file, copies the content to a response file and returns the content to the client.

So the service can be seen as a copy service - not very useful in real life situations, but it does show how you can use the FileServiceHandler to access a request file and create a response file.

Service handler

The service handler that implements the service is:

WSYAPI/_Examples.CopyServiceHandler

A short explanation of the code:

  1. Send Content-Type

    The response must specify a content-type. The default behavior of the ServiceProcessor is to send text/xml with the charset of the request. As this service can handle several different text based content types, it just uses the header specified by the client for the request.

  2. Open input and output files

    In this example, we have used the low-level ReadHtmlPage and WriteToFile Websydian functions. These demand that you open the file before accessing the data. This is the case for most read/write functionality.

  3. Loop through the request - create the response

    The ReadHtmlPage function reads blocks of data from the request file. After a block has been read, it is written to the response file.

    Please note that the ReadHtmlPage is designed to read text-data from a file - as Plex does not handle binary data in text fields, you can't use this function to read anything but text-based data. The Java-version of this program is not designed to handle UTF-8 or UTF-16 data.

  4. Close files

    This step is performed in the Terminate subroutine. It is very important to close files after opening them - or the service processor will not be able to read the response file and return it to the client.

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 the file copy service is scoped by the criteria - and the value for the criteria is specified as "copy".

This means that the copy service handler will handle the requests that target:

...express30/service/site/demosite/file/copy

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

The services can't be called from a browser - as there is no way for the handler to provide the request data.

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.

If the URL specifying the copy service is: "http://MyServer/express30/site/demosite/service/file/copy" (see above) - specify the following values:

Internet ServerName: MyServer

Port: 80 (if the URL starts with MyServer:nnnn/...) - then you specify the value nnnn.

URL: /express30/site/demosite/service/file/copy

HTTP version: HTTP/1.1

Method: Post

Use SSL: *No

Request filename: Specify a file containing the request data.

The request document is an html document.

In the header table you must change the value for the content type to: text/html;charset=ISO-8859-1

Press Execute, The response headers and file will be shown in the bottom of the panel.

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