/usr/share/doc/stilts/sun256/taskApi.html is in stilts-doc 3.1.2-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | <html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="sun-style.css">
<title>Programmatic Invocation</title>
</head>
<body>
<hr>
<a href="classified.html">Next</a> <a href="jelExtend.html">Previous</a> <a href="index.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="classified.html">Commands By Category</a><br>
<b>Up: </b><a href="index.html">Top</a><br>
<b>Previous: </b><a href="jelExtend.html">Adding User-Defined Functions</a><br>
<hr>
<hr>
<h2><a name="taskApi">11 Programmatic Invocation</a></h2>
<p>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
<code>uk.ac.starlink.ttools</code> package, its subpackages,
and most of the other classes in the <code>uk.ac.starlink</code>
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
<a href="http://andromeda.star.bris.ac.uk/starjavadocs/">here</a>),
tutorial documentation is not provided, and there is no commitment
to API stability between releases.
</p>
<p>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 <code>main(String[])</code> method of the application
Main-Class
(<a href="http://andromeda.star.bris.ac.uk/starjavadocs/uk/ac/starlink/ttools/Stilts.html"><code>Stilts</code></a>)
but we document here how it can be done in a way which
allows more control, using the
<a href="http://andromeda.star.bris.ac.uk/starjavadocs/uk/ac/starlink/task/package-summary.html"><code>uk.ac.starlink.task</code></a>
parameter handling framework.
</p>
<p>Each of the STILTS tasks listed in <a href="cmdUsage.html">Appendix B</a>
is represented by a class implementing the
<a href="http://andromeda.star.bris.ac.uk/starjavadocs/uk/ac/starlink/task/Task.html"><code>Task</code></a> interface;
these all have no-arg constructors.
To run it, you need to create an instance of the class,
pass it an
<a href="http://andromeda.star.bris.ac.uk/starjavadocs/uk/ac/starlink/task/Environment.html"><code>Environment</code></a>
object which can acquire values for parameters by name, and then execute it.
The
<a href="http://andromeda.star.bris.ac.uk/starjavadocs/uk/ac/starlink/ttools/task/MapEnvironment.html"><code>MapEnvironment</code></a>
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 <a href="calc.html">calc</a> task
to perform a simple calcation:
<pre>
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();
</pre>
The execution corresponds exactly to the command-line:
<pre>
stilts calc expression="sqrt(3*3+4*4)"
</pre>
The <a href="calc-usage.html">Usage</a> section for the <code>calc</code>
task notes that the corresponding Task subclass is
<a href="http://andromeda.star.bris.ac.uk/starjavadocs/uk/ac/starlink/ttools/task/Calc.html"><code>Calc</code></a>.
</p>
<p>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 <code>MapEnvironment</code> as an alternative
to passing string values.
For the case of the input table parameters,
this is
<a href="http://andromeda.star.bris.ac.uk/starjavadocs/uk/ac/starlink/table/StarTable.html"><code>StarTable</code></a>,
so in a task like
<a href="tpipe.html">tpipe</a>
(<a href="http://andromeda.star.bris.ac.uk/starjavadocs/uk/ac/starlink/ttools/task/TablePipe.html"><code>TablePipe</code></a>),
if you want to read a file "data.fits",
you can either write
<pre>
env.setValue( "in", "data.fits" );
</pre>
or
<pre>
StarTable table = new StarTableFactory().readStarTable( "data.fits" );
env.setValue( "in", table );
</pre>
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 <a href="http://www.starlink.ac.uk/stil/sun252/">SUN/252</a> for more information on
<code>StarTable</code> handling.
</p>
<p>For some short examples of programs which invoke STILTS tasks
in this way, see the source code of some of the examples in the
<code>uk.ac.starlink.ttools.example</code> directory:
<a href="https://github.com/Starlink/starjava/blob/master/ttools/src/main/uk/ac/starlink/ttools/example/Calculator.java">Calculator</a> and
<a href="https://github.com/Starlink/starjava/blob/master/ttools/src/main/uk/ac/starlink/ttools/example/Head10.java">Head10</a>.
</p>
<p>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
<a href="https://github.com/Starlink/starjava/blob/master/ttools/src/main/uk/ac/starlink/ttools/example/EnvPlanePlotter.java">EnvPlanePlotter</a>
class.
For some more tutorial introductions to using the plotting classes
programmatically, see also the example classes
<a href="https://github.com/Starlink/starjava/blob/master/ttools/src/main/uk/ac/starlink/ttools/example/SinePlot.java">SinePlot</a>,
<a href="https://github.com/Starlink/starjava/blob/master/ttools/src/main/uk/ac/starlink/ttools/example/ApiPlanePlotter.java">ApiPlanePlotter</a>,
and
<a href="https://github.com/Starlink/starjava/blob/master/ttools/src/main/uk/ac/starlink/ttools/example/BasicPlotGui.java">BasicPlotGui</a>
in the same place.
</p>
<hr><a href="classified.html">Next</a> <a href="jelExtend.html">Previous</a> <a href="index.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="classified.html">Commands By Category</a><br>
<b>Up: </b><a href="index.html">Top</a><br>
<b>Previous: </b><a href="jelExtend.html">Adding User-Defined Functions</a><br>
<hr><i>STILTS - Starlink Tables Infrastructure Library Tool Set<br>Starlink User Note256<br>STILTS web page:
<a href="http://www.starlink.ac.uk/stilts/">http://www.starlink.ac.uk/stilts/</a><br>Author email:
<a href="mailto:m.b.taylor@bristol.ac.uk">m.b.taylor@bristol.ac.uk</a><br>Mailing list:
<a href="mailto:topcat-user@jiscmail.ac.uk">topcat-user@jiscmail.ac.uk</a><br></i></body>
</html>
|