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();

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

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" );

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

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.