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/
http://localhost:2112/stilts/task/tpipe
tpipe task.
http://localhost:2112/stilts/task/calc?expression=21%2b2
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
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
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.