Next Previous Up Contents
Next: Commands By Category
Up: Top
Previous: Form Service

## 12 Programmatic Invocation

The STILTS package provides some capabilities, for instance plotting, that might be useful as part of other Java applications. The code that forms STILTS is fully documented at the API level; there are comprehensive javadocs throughout for the `uk.ac.starlink.ttools` package, its subpackages, and most of the other classes in the `uk.ac.starlink` tree on which it relies. Anybody is welcome to use these classes at their own risk, but the code does not form a stable API intended for public use: the javadocs are not distributed as part of the package (though you may be able to find them here), tutorial documentation is not provided, and there is no commitment to API stability between releases.

With this in mind, there are facilities for invoking the STILTS commands programmatically from third-party java code. Of course it is possible to do this by just calling the static `main(String[])` method of the application Main-Class (`Stilts`) but we document here how it can be done in a way which allows more control, using the `uk.ac.starlink.task` parameter handling framework.

Each of the STILTS tasks listed in Appendix B is represented by a class implementing the `Task` interface; these all have no-arg constructors. To run it, you need to create an instance of the class, pass it an `Environment` object which can acquire values for parameters by name, and then execute it. The `MapEnvironment` class, based on a Map containing name/value pairs, is provided for this purpose. As well as managing parameter values, MapEnvironment captures table and text output in a way that lets you retrieve it after the task has executed. Here is a simple example for invoking the calc task to perform a simple calcation:

        MapEnvironment env = new MapEnvironment();
        env.setValue( "expression", "sqrt(3*3+4*4)" );
        Task calcTask = new uk.ac.starlink.ttools.task.Calc();
        calcTask.createExecutable( env ).execute();
        String result = env.getOutputText();

The execution corresponds exactly to the command-line:

        stilts calc expression="sqrt(3*3+4*4)"

The Usage section for the `calc` task notes that the corresponding Task subclass is `Calc`.

Also in the usage section, each parameter reports the data type that it may take, and objects of this type may be used as the parameter value passed in the `MapEnvironment` as an alternative to passing string values. For the case of the input table parameters, this is `StarTable`, so in a task like tpipe (`TablePipe`), if you want to read a file "data.fits", you can either write

        env.setValue( "in", "data.fits" );

or

        StarTable table = new StarTableFactory().readStarTable( "data.fits" );
        env.setValue( "in", table );

That doesn't buy you much, but the table could equally be obtained from any other source, including being a user-defined iterable over existing data structures. See SUN/252 for more information on `StarTable` handling.

For some short examples of programs which invoke STILTS tasks in this way, see the source code of some of the examples in the `uk.ac.starlink.ttools.example` directory: Calculator and Head10.

Some commands provide additional methods for use with parameter-based invocation. In particular the plotting commands can be used to create JComponent objects that can be incorporated into an existing GUI. A working example of this can be found in the source code for the example EnvPlanePlotter class. For some more tutorial introductions to using the plotting classes programmatically, see also the example classes SinePlot, ApiPlanePlotter, and BasicPlotGui in the same place.

Next Previous Up Contents
Next: Commands By Category
Up: Top
Previous: Form Service

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