Next Previous Up Contents
Next: Usage
Up: Command Reference
Previous: Examples


B.16 server: Runs an HTTP server to perform STILTS commands

server runs an HTTP server which makes some or all of the various STILTS tasks available to local or remote clients making HTTP requests rather than using the more usual command line interface.

When you run server it will start up a server which runs until it is interrupted, and write to the screen the base URL at which it can be accessed, for instance "http://localhost:2112/stilts/". If you point your browser here you will see some examples (hyperlinks to server requests) of how to use the server. Currently there are two main sets of capabilities:

Tasks (baseURL/task/task-name)
There is a URL as above associated with each STILTS task provided by the server. The task parameters are passed in the usual way for HTTP queries, using application/x-www-form-urlencoded (see e.g. the HTML FORM specification). Some examples are given in the Client Examples subsection below. Either HTTP GET or POST methods may be used; since the task invocations will normally be idempotent, GET is more respectable, but long URLs can cause trouble in some circumstances (MS IE apparently imposes a limit of about 2000 characters) so POST may be preferable for lengthy invocations.
Forms (baseURL/form/)
There are a couple of example HTML Forms which can be used to access the server tasks. These by no means show all the capabilities of the tasks that they use, they are just intended to be examples of how forms can be used in this way.
In general if you request a URL which contains no useful information, an attempt will be made to return an HTML page directing you to a more useful starting point.

You might want to run STILTS in server mode if you are providing a web service to external users which is able to access files residing on the server, for instance generating table plots or row selections on the fly. This can be done without the server mode, for instance by invoking the stilts script or java from a CGI script to serve each request, but using server mode has two advantages: first it provides correct HTTP headers such as Content-Types, and secondly it avoids the Java startup overheads for each invocation. Note however that in its current form no great attention has been paid to security, so it may be possible for clients to read and write files and expend significant system resources by making certain requests to the server. Anyone exposing the STILTS HTTP server directly to external clients should bear this in mind.

For more flexibility you can run STILTS in servlet mode. See the javadocs and sources of the uk.ac.starlink.ttools.server.TaskServlet class. The server command is a fairly thin wrapper around this, which simply deploys the servlet in an embedded web application container (Jetty). By using the servlet class in your own custom web application instead you can customise the way it is accessed, for instance providing improved security.

Note: The server command and associated servlet code are at time of writing (v2.0) experimental, and probably buggy and missing some features which ought to be present. If you have requirements which are not currently provided, please contact the author for discussion.


Next Previous Up Contents
Next: Usage
Up: Command Reference
Previous: Examples

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk