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: 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 {@link uk.ac.starlink.ast.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 {@link java.lang.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 {@link uk.ac.starlink.ast.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 {@link java.lang.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.