Package uk.ac.starlink.ast

Provides an interface to the Starlink AST library.

See: Description

Interface Summary

Interface	Description
Grf	Interface for specifying graphics implementations used by Plots.
NeedsChannelizing	Declares that an AstObject requires object-specific preparation before writing to and/or after reading from a Channel.
Ukern1Calculator	Interface for user-provided 1-d kernel interpolation functions.

Class Summary

Class	Description
AstObject	Java interface to the AST Object class - base class for all AST Objects.
AstPackage	Provides information about the status of the JNIAST package.
AstroCoords	Represents an AstroCoords element from the Space-Time Coordinate (STC) metadata.
Axis	Java interface to the AST Axis class.
Box	Java interface to the AST Box class - a box region with sides parallel to the axes of a Frame.
Channel	Java interface to the AST Channel class - basic (textual) I/O channel.
Circle	Java interface to the AST Circle class - a circular or spherical region within a Frame.
CmpFrame	Java interface to the AST CmpFrame class - compound Frame.
CmpMap	Java interface to the AST CmpMap class - compound Mapping.
CmpRegion	Java interface to the AST CmpRegion class - a combination of two regions within a single Frame.
DSBSpecFrame	Java interface to the AST DSBSpecFrame class - dual sideband spectral coordinate system description.
DssMap	Java interface to the AST DssMap class.
Ellipse	Java interface to the AST Ellipse class - an elliptical region within a 2-dimensional Frame.
FitsChan	Java interface to the AST FitsChan class - I/O Channel using FITS header cards to represent Objects.
FluxFrame	Java interface to the AST FluxFrame class - measured flux description.
Frame	Java interface to the AST Frame class - coordinate system description.
FrameSet	Java interface to the AST FrameSet class - set of inter-related coordinate systems.
GrismMap	Java interface to the AST GrismMap class - transform 1-dimensional coordinates using a grism dispersion equation.
Interval	Java interface to the AST Interval class - a region representing an interval on one or more axes of a Frame.
IntraMap	Java interface to the AST IntraMap class - map points using a private transformation function.
KeyMap	Java interface to the AST KeyMap class - store a set of key/value pairs.
LutMap	Java interface to the AST LutMap class - transform 1-dimensional coordinates using a lookup table.
Mapping	Java interface to the AST Mapping class - inter-relate two coordinate systems.
Mapping.Interpolator	Controls the interpolation scheme used by Mapping's resampling methods.
Mapping.Spreader	Controls the spreading scheme used by Mapping's rebinning methods.
MathMap	Java interface to the AST MathMap class - transform coordinates using mathematical expressions.
MatrixMap	Java interface to the AST MatrixMap class - map coordinates by multiplying by a matrix.
NullRegion	Java interface to the AST NullRegion class - a boundless region within a Frame.
PcdMap	Java interface to the AST PcdMap class - apply 2-dimensional pincushion/barrel distortion.
PermMap	Java interface to the AST PermMap class - coordinate permutation Mapping.
Plot	Java interface to the AST Plot class - provide facilities for 2D graphical output.
PointList	Java interface to the AST PointList class - a collection of points in a Frame.
Polygon	Java interface to the AST Polygon class - a polygonal region within a 2-dimensional Frame.
PolyMap	Java interface to the AST PolyMap class - map coordinates using polynomial functions.
Prism	Java interface to the AST Prism class - an extrusion of a region into higher dimensions.
RateMap	Java interface to the AST RateMap class - mapping which represents differentiation.
Region	Java interface to the AST Region class - represents a region within a coordinate system.
ResampleFlags	Aggregates flags which influence how Mapping.resample* methods operate.
SelectorMap	Java interface to the AST SelectorMap class - a Mapping that locates positions within one of a set of alternate Regions.
ShiftMap	Java interface to the AST ShiftMap class - add a constant value to each coordinate.
SkyAxis	Java interface to the AST SkyAxis class.
SkyFrame	Java interface to the AST SkyFrame class - celestial coordinate system description.
SlaMap	Java interface to the AST SlaMap class - sequence of celestial coordinate conversions.
SpecFluxFrame	Java interface to the AST SpecFluxFrame class - compound spectrum/flux Frame.
SpecFrame	Java interface to the AST SpecFrame class - spectral coordinate system description.
SpecMap	Java interface to the AST SpecMap class - sequence of spectral coordinate conversions.
SphMap	Java interface to the AST SphMap class - map 3-d Cartesian to 2-d spherical coordinates.
Stc	Java interface to the AST Stc class - represents an instance of the IVOA STC class.
StcCatalogEntryLocation	Java interface to the AST StcCatalogEntryLocation class - correspond to the IVOA STCCatalogEntryLocation class.
StcObsDataLocation	Java interface to the AST StcObsDataLocation class - correspond to the IVOA ObsDataLocation class.
StcResourceProfile	Java interface to the AST StcResourceProfile class - correspond to the IVOA STCResourceProfile class.
StcSearchLocation	Java interface to the AST StcSearchLocation class - correspond to the IVOA SearchLocation class.
SwitchMap	Java interface to the AST SwitchMap class - a Mapping that encapsulates a set of alternate Mappings.
TimeFrame	Java interface to the AST TimeFrame class - time coordinate system description.
TimeMap	Java interface to the AST TimeMap class - sequence of time coordinate conversions.
TranMap	Java interface to the AST TranMap class - mapping with specified forward and inverse transformations.
Transformer	Defines a custom general coordinate transformation function.
Transformer1	Defines a custom one-dimensional coordinate transformation function.
Transformer2	Defines a custom two-dimensional coordinate transformation function.
UinterpCalculator	Abstract class for user-provided general interpolation functions.
UnitMap	Java interface to the AST UnitMap class - unit (null) Mapping.
WcsMap	Java interface to the AST WcsMap class - implement a FITS-WCS sky projection.
WinMap	Java interface to the AST WinMap class - map one window on to another by scaling and shifting each axis.
XmlChan	Java interface to the AST XmlChan class - I/O Channel using XML to represent Objects.
ZoomMap	Java interface to the AST ZoomMap class - zoom coordinates about the origin.

Exception Summary

Exception	Description
AstException	Thrown to indicate that there has been an AST error of some description.

Package uk.ac.starlink.ast Description

Provides an interface to the Starlink AST library.

AST library vs. uk.ac.starlink.ast package

The classes and methods here provide, via classes comprising native code which calls the underlying AST library, a complete interface to AST V1.8-3. The following sections discuss differences between the AST library and this interface to it.

Class hierarchy

The class hierarchy of the AST library is exactly replicated in this package, though this package contains some additional classes and interfaces used in the implementation which are not subclasses of AstObject. The classes are named the same, but without the 'Ast' prefix, except for AstObject, as a convenience to prevent a clash with java.lang.Object (should the same apply to Frame to prevent a clash with java.awt.Frame?)

Methods

The methods are named the same as in the AST library except without the 'Ast' prefix. In almost all classes there is a one-to-one correspondence between AST functions and methods in this package (though see the list below for omissions). In a few cases extra methods are provided here as conveniences. In particular, specific getter/setter methods are provided for each attribute of AstObject and all its subclasses. The generic set and set<type> methods may be used to set attributes, but using the specific methods provides better type safety.

Method arguments

Method arguments broadly follow their specifications in the AST library, but there are differences:

• boolean, rather than int type is used for integer arguments/return values with boolean intent,
• on the whole pointers are eschewed in favour of return values to provide the results of a call,
• callbacks are implemented using specially defined classes or interfaces
• where a method must be able to indicate an error condition communicating this via return value is eschewed in favour of raising an exception.
• in some cases, the length of an array argument is not required, since unlike in C, this is implicit in the passed array itself

Thus for instance:

   void astTran1( AstMapping *this, int npoint, const double xin[], 
                  int forward, double xout[] )

becomes

   public double[] tran1( int npoint, double[] xin, boolean forward )

(this is implicit, forward is of type boolean rather than int, and xout is the return value rather than a pre-allocated array into which the result can be written), and

   int astGQch( float *chv, float *chh )

becomes

   public float[] qch() throws Exception

(failure is indicated by throwing an Exception rather than by a zero return value, and the result is a returned array consisting of the two calculated values, rather than writing new values into locations pointed to by the arguments).

It is therefore recommended that programming is done with reference to the documentation of this package rather than of SUN/211. However, because of the strict type-checking of java compilers, it is unlikely that misconceptions about method signatures arising from familiarity with the C or Fortran versions of AST will result in compilable but incorrect code.

Where an array argument needs to be of a certain length the native code checks that it is at least of that length. If it is not, an exception is thrown to that effect. However, supplying an array which is longer than required in such cases is not regarded as an error.

Symbolic constants

Relevant AST symbolic constants are made available by public static final fields of the same name in the class to which they are relevant. These are guaranteed to have the same value as their AST library counterparts (the implementation obtains them at runtime using the definitions in the "ast.h" header file). Access is also available by name using the AstObject's getAstConstant<type> methods, though this is intended mainly for use within this package, and somewhat deprecated for user code. Thus the FrameSet class contains the declaration:

   public static final int AST__CURRENT = getAstCurrentI( "AST__CURRENT" );

API documentation

API Documentation has largely been generated by extracting comments wholesale from the AST source code and turning it into doc comments, which have then been processed by javadoc in the usual way. Although comments about a given argument ought to apply to the the correct argument, some of the language will be incorrect (e.g. 'pointer' where it should say 'reference'), and some comments will be irrelevant or possibly misleading. In the future, some (actually, quite a lot of) work will be required if the comments are to read like they were written for java.

Error conditions

Errors are handled in a robust way using Exceptions. If any call in the underlying AST library sets the AST Status to a non-zero value, this will be indicated to the calling java code by the throwing of an AstException. AstException provides a getStatus method (and defines the corresponding status values) so that the exact nature of the error which caused the trouble can be determined if desired. In a few cases, the java or native code will throw an AstException not generated by the AST library too; in this case the status will have the value AstException.SAI__ERROR. AstException extends RuntimeException, so that declaring and catching such throwables is not enforced by the compiler. Efforts have been made to ensure that Exceptions will be thrown in all cases rather than causing a JVM crash, but the JNI is a bit tricky in some circumstances, and there may be cases I haven't thought of. Please report JVM crashes (which will almost certainly be a result of JNI code in this package rather than an error in the JVM as they tend to report).

Synchronization

All calls to the underlying AST library itself (though not to the various methods of the classes which form this package) are effectively synchronized - a lock is obtained on an object maintained by the JNI code for this purpose. This implementation detail is required so that AST calls from different threads do not interfere with each other, by overwriting one or two C globals. In most cases this should not be noticeable, but it may have response time implications for multithreaded applications which invoke the the few time-consuming AST calls such as the resample<type> methods of Mapping.

Unimplemented functions

Here is a list of the AST functions which are not implemented because they are not appropriate in a Java context in one way or another:

astBegin, astEnd, astExempt, astExport

Objects are garbage collected in the usual way when references expire

astClearStatus, astSetStatus, astStatus, astWatch, astOK

Status handling is managed by throwing an AstException when an error occurs in native AST code

astIsA<Class>

Use instanceof instead - the class hierarchy in this package is identical to that of AST (for the classes which appear in AST)

astGrfPop, astGrfPush

The setGrf and getGrf methods of Plots provide this functionality.

Tolerance of absent native code

Being substantially an interface to native code, this package breaks java's platform independence. Client code may wish to invoke the package in such a way that it can tolerate being used on a platform where the native code (shared library) is not available. Of course the JNIAST functionality will be lost, but if that is not a fundamental part of the client code's functionality, it may be better to do this than to throw a fatal error. This can make it possible to run (albeit with reduced functionality) on a wider range of platforms than would otherwise be possible.

To do this, code can use the AstPackage.isAvailable() method, which indicates whether the requisite native code is available for use. If it is, then AST processing can take place as usual, but if not then as long as code avoids attempting to create or dereference any instance of AstObject or its subclasses it should run without errors (I think). Attempting to create or dereference an AstObject when AstPackage.isAvailable returns false will normally result in a LinkageError of some sort.

Package status

This package is a temporary measure; in due course it will be superceded by the pure java WCS package. WCS is being actively worked on now (mid 2002), but the timescale for completion is uncertain.