Next Previous Up Contents
Next: Form Service
Up: Server Mode
Previous: Caching and Performance

### 11.2 Task Service

This servlet allows execution of a single STILTS command by making an HTTP request with the command name and parameters, rather than by presenting them on the command line. You might want to run this service if you are providing a web service to external users which is able to access files residing on the server, for instance generating static table plots (though see the Plot service for more sophisticated server-side visualisation) 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 output HTTP headers such as Content-Type, and secondly it avoids the Java startup overheads for each invocation.

The URLs accepted by the service are of the form

       <task-base-url>/<task-name>?<arg-name>=<arg-value>&<arg-name>=<arg-value>...

The `<task-name>` is one of the STILTS command names as listed in Appendix B, and the `<arg-name>=<arg-value>` pairs are the parameter settings for that command; the parameter settings are syntactically an `application/x-www-form-urlencoded` query string. These parameters may be supplied as a POST body rather than as part of a GET query if preferred, though since the task invocation will normally be idempotent, GET may be more respectable.

The HTTP response depends on the behaviour of the task in question. If the task is one that outputs a table or sequence of tables, such as `tpipe` or `tmatch2`, the HTTP response will be the serialized form of the table in an appropriate format. By default that is currently VOTable (Content-Type "`application/x-votable+xml`"), but that can be altered by supplying the appropriate output format parameter, e.g. "`ofmt=fits`". Plotting commands return an image in a default graphics format; again the output format can be controlled using command paramters in the same way as on the command line. Output for some other commands such as `calc` may just be plain text.

Here are some example invocations, assuming the default server base URL of `http://localhost:2112/stilts/`:

    http://localhost:2112/stilts/

  Returns an HTML page giving version information and some links to example usages of the server.

    http://localhost:2112/stilts/task/tpipe

  Returns an HTML page giving usage instructions for the `tpipe` task.

    http://localhost:2112/stilts/task/calc?expression=21%2b2

  Invokes the `calc` task to return a document containing the text "`23`". Note that the plus ("`+`") sign in the expression has to be encoded using the sequence "`%2b`" since "`+`" has a special significance in query URLs - see for instance sec 2.2 of RFC 1738.

    http://localhost:2112/stilts/task/plot2plane?in=/data/table1.vot&layer1=mark&x1=RMAG&y1=BMAG

  Invokes the `plot2d` task to return a magnitude-magnitude diagram of the named server-side file as an image, probably an `image/png` (but see the Plot Service if you want interactive plots).

    http://localhost:2112/stilts/task/tcopy?in=/data/cat.fits&ofmt=ecsv

  Invokes the `tcopy` task to return a translation of the named server-side FITS file to ECSV format.

Note that in the current form of this service 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 this service directly to external clients should bear this in mind.

Next Previous Up Contents
Next: Form Service
Up: Server Mode
Previous: Caching and Performance

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