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
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-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-urlencodedquery 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
the HTTP response will be the serialized form of the table
in an appropriate format. By default that is currently VOTable
but that can be altered by supplying the appropriate output
format parameter, e.g. "
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
may just be plain text.
Here are some example invocations, assuming the default
server base URL of
calctask 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.
plot2dtask 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).
tcopytask 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.