uk.ac.starlink.ast

Class AstObject

java.lang.Object

uk.ac.starlink.ast.AstObject

Direct Known Subclasses:

Axis, Channel, KeyMap, Mapping

public class AstObject
extends Object

Java interface to the AST Object class - base class for all AST Objects. This class is the base class from which all other classes in the AST library are derived. It provides all the basic Object behaviour and Object manipulation facilities required throughout the library. There is no Object constructor, however, as Objects on their own are not useful.

Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA

See Also:

AST Object

Field Summary

Fields

Modifier and Type	Field and Description
static double	AST__BAD Bad coordinate value.
static int	AST__TUNULL No-change value for use with tune.
protected long	pointer Holds the C pointer to the AST object.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AstObject() Dummy constructor.

Method Summary

Modifier and Type	Method and Description
void	annul() Annul this object.
void	clear(String attrib) Clear attribute values for an Object.
AstObject	copy() Copy an Object.
void	delete() Delete this object.
boolean	equals(Object obj) Determine whether two AstObjects are similar in all respects.
protected void	finalize() Finalize the object; this annuls the AST object to free resources.
static int	getAstConstantI(String constname) Gets the value of a named integer constant from the underlying AST library.
boolean	getB(String attrib) Get a boolean attribute value by name.
String	getC(String attrib) Get a character attribute value by name.
double	getD(String attrib) Get a double precision attribute value by name.
float	getF(String attrib) Get a floating point attribute value by name.
int	getI(String attrib) Get a integer attribute value by name.
String	getID() Get object identification string.
String	getIdent() Get permanent Object identification string.
long	getL(String attrib) Get a long integer attribute value by name.
int	getNobject() Get number of Objects in class.
int	getObjSize() Get the in-memory size of the Object.
int	getRefCount() Get count of active Object pointers.
int	hashCode() Return a hash code for this AstObject.
static boolean	isThreaded() Indicates whether the package is running in threaded mode or not.
static String	reportVersions() Returns a string giving the versions of AST and of JNIAST.
boolean	sameObject(Object obj) Determine whether two AstObjects are references to the same underlying object.
void	set(String settings) Set attribute values for an Object.
void	setB(String attrib, boolean value) Set a boolean attribute value by name.
void	setC(String attrib, String value) Set a character attribute value by name.
void	setD(String attrib, double value) Set a double precision attribute value by name.
void	setF(String attrib, float value) Set a floating point attribute value by name.
void	setI(String attrib, int value) Set a integer attribute value by name.
void	setID(String ID) Set object identification string.
void	setIdent(String Ident) Set permanent Object identification string.
void	setL(String attrib, long value) Set a long integer attribute value by name.
void	show() Display a textual representation of an Object on standard output.
boolean	test(String attrib) Test if an Object attribute value is set.
static int	tune(String name, int value) Set or get an integer-valued AST global tuning parameter.

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

pointer

protected long pointer

Holds the C pointer to the AST object. Used by native code.

AST__BAD

public static final double AST__BAD

Bad coordinate value.

AST__TUNULL

public static final int AST__TUNULL

No-change value for use with tune.

Constructor Detail

AstObject

protected AstObject()

Dummy constructor. This constructor does not create a valid AstObject object, but is required for inheritance by AstObject's subclasses.

Method Detail

finalize

protected void finalize()
                 throws Throwable

Finalize the object; this annuls the AST object to free resources. Subclasses which override this method should call it in their finalizers.

Overrides:

finalize in class Object

Throws:

Throwable

getAstConstantI

public static int getAstConstantI(String constname)

Gets the value of a named integer constant from the underlying AST library.

Parameters:

constname - the name of the constant ("AST__something")

Returns:

the value of constname

Throws:

IllegalArgumentException - if no constant by that name exists

isThreaded

public static boolean isThreaded()

Indicates whether the package is running in threaded mode or not. If true, multiple AST calls may execute at once (though there are per-object locks). Otherwise, only one AST call is ever in progress at any one time.

Returns:

true iff JNIAST is operating in threaded mode

annul

public void annul()

Annul this object. Associated resources in the underlying library are reclaimed. Following this call the object cannot be used.

It is not normally necessary for application code to call this method, since it is called during object finalization. User code may however call it if there is worry about retaining non-java heap memory longer than absolutely necessary, but think carefully about whether the additional clutter in user code makes this worthwhile.

delete

public void delete()

Delete this object. Associated resources in the underlying library are reclaimed, and any remaining references to the underlying object are rendered invalid.

Note that deletion is unconditional, regardless of other references to this java object or to the underlying AST object. This method should be used with caution. It is not normally necessary for application code to call it.

equals

public boolean equals(Object obj)

Determine whether two AstObjects are similar in all respects. This method is implemented by writing both objects to a Channel and comparing the resulting textual representations. It may therefore be relatively expensive.

Overrides:

equals in class Object

Parameters:

obj - object to be compared with this one

Returns:

true if obj resembles this object in all respects, false otherwise

See Also:

sameObject

hashCode

public int hashCode()

Return a hash code for this AstObject. The notion of equality in this method must match the one in the equals method. This method is implemented by writing the object to a Channel and calculating the hash code of the resulting String. It may therefore be relatively expensive.

Overrides:

hashCode in class Object

Returns:

the hash code of this AstObject

sameObject

public boolean sameObject(Object obj)

Determine whether two AstObjects are references to the same underlying object. Since AstObjects are merely containers for references to objects in the underlying AST library, two AstObjects may effectively be references to the same object (so that, for instance, changing an attribute of one will change it in the other) but the == operator applied between them will return false. This method can tell you whether two AstObjects refer to the same thing.

Parameters:

obj - an object to be compared to this one.

Returns:

true if obj references the same AST object as this does.

See Also:

equals

reportVersions

public static String reportVersions()

Returns a string giving the versions of AST and of JNIAST.

Returns:

versions of the components of this package

clear

public void clear(String attrib)

Clear attribute values for an Object. This function clears the values of a specified set of attributes for an Object. Clearing an attribute cancels any value that has previously been explicitly set for it, so that the standard default attribute value will subsequently be used instead. This also causes the astTest function to return the value zero for the attribute, indicating that no value has been set.

Notes

- Attribute names are not case sensitive and may be surrounded by white space.
- It does no harm to clear an attribute whose value has not been set.
- An error will result if an attempt is made to clear the value of a read-only attribute.

Parameters:

attrib - Pointer to a null-terminated character string containing a comma-separated list of the names of the attributes to be cleared.

Throws:

AstException - if an error occurred in the AST library

copy

public AstObject copy()

Copy an Object. This function creates a copy of an Object and returns a pointer to the resulting new Object. It makes a "deep" copy, which contains no references to any other Object (i.e. if the original Object contains references to other Objects, then the actual data are copied, not simply the references). This means that modifications may safely be made to the copy without indirectly affecting any other Object.

Notes

- A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Returns:

Pointer to the new Object.

Throws:

AstException - if an error occurred in the AST library

getC

public String getC(String attrib)

Get a character attribute value by name.

Parameters:

attrib - the name of the character attribute to retrieve

Returns:

the named attribute as a String

Throws:

AstException - if the AST routine generates an error, in particular if no character attribute called attrib exists

setC

public void setC(String attrib,
                 String value)

Set a character attribute value by name.

Parameters:

attrib - the name of the character attribute to set

value - the new value of the attribute

Throws:

AstException - if the AST routine generates an error, in particular if no writable character attribute called attrib exists

getD

public double getD(String attrib)

Get a double precision attribute value by name.

Parameters:

attrib - the name of the double precision attribute to retrieve

Returns:

the named attribute as a double

Throws:

AstException - if the AST routine generates an error, in particular if no double precision attribute called attrib exists

setD

public void setD(String attrib,
                 double value)

Set a double precision attribute value by name.

Parameters:

attrib - the name of the double precision attribute to set

value - the new value of the attribute

Throws:

AstException - if the AST routine generates an error, in particular if no writable double precision attribute called attrib exists

getF

public float getF(String attrib)

Get a floating point attribute value by name.

Parameters:

attrib - the name of the floating point attribute to retrieve

Returns:

the named attribute as a float

Throws:

AstException - if the AST routine generates an error, in particular if no floating point attribute called attrib exists

setF

public void setF(String attrib,
                 float value)

Set a floating point attribute value by name.

Parameters:

attrib - the name of the floating point attribute to set

value - the new value of the attribute

Throws:

AstException - if the AST routine generates an error, in particular if no writable floating point attribute called attrib exists

getL

public long getL(String attrib)

Get a long integer attribute value by name.

Parameters:

attrib - the name of the long integer attribute to retrieve

Returns:

the named attribute as a long

Throws:

AstException - if the AST routine generates an error, in particular if no long integer attribute called attrib exists

setL

public void setL(String attrib,
                 long value)

Set a long integer attribute value by name.

Parameters:

attrib - the name of the long integer attribute to set

value - the new value of the attribute

Throws:

AstException - if the AST routine generates an error, in particular if no writable long integer attribute called attrib exists

getI

public int getI(String attrib)

Get a integer attribute value by name.

Parameters:

attrib - the name of the integer attribute to retrieve

Returns:

the named attribute as a int

Throws:

AstException - if the AST routine generates an error, in particular if no integer attribute called attrib exists

setI

public void setI(String attrib,
                 int value)

Set a integer attribute value by name.

Parameters:

attrib - the name of the integer attribute to set

value - the new value of the attribute

Throws:

AstException - if the AST routine generates an error, in particular if no writable integer attribute called attrib exists

getB

public boolean getB(String attrib)

Get a boolean attribute value by name. This is a convenience method which calls getI but maps integers to booleans.

Parameters:

attrib - the name of the boolean attribute to retrieve

Returns:

the named attribute as a boolean

Throws:

AstException - if the AST routine generates an error, in particular if no integer attribute by this name exists

setB

public void setB(String attrib,
                 boolean value)

Set a boolean attribute value by name. This is a convenience method which calls setI but maps boolean values to integers.

Parameters:

attrib - the name of the boolean attribute to set

value - the new value of attrib

Throws:

AstException - if the AST routine generates an error, in particular if no writable integer attribute by that name exists

set

public void set(String settings)

Set attribute values for an Object. This function assigns a set of attribute values to an Object, over-riding any previous values. The attributes and their new values are specified via a character string, which should contain a comma-separated list of the form:

"attribute_1 = value_1, attribute_2 = value_2, ... "

where "attribute_n" specifies an attribute name, and the value to the right of each "=" sign should be a suitable textual representation of the value to be assigned. This value will be interpreted according to the attribute's data type.

The string supplied may also contain "printf"-style format specifiers, identified by "%" signs in the usual way. If present, these will be substituted by values supplied as additional optional arguments (using the normal "printf" rules) before the string is used.

Notes

- Attribute names are not case sensitive and may be surrounded by white space.
- White space may also surround attribute values, where it will generally be ignored (except for string-valued attributes where it is significant and forms part of the value to be assigned).
- To include a literal comma in the value assigned to an attribute, the whole attribute value should be enclosed in quotation markes. Alternatively, you can use "%s" format and supply the value as a separate additional argument to astSet (or use the astSetC function instead).
- The same procedure may be adopted if "%" signs are to be included and are not to be interpreted as format specifiers (alternatively, the "printf" convention of writing "%%" may be used).
- An error will result if an attempt is made to set a value for a read-only attribute.

Parameters:

settings - Pointer to a null-terminated character string containing a comma-separated list of attribute settings in the form described above.

Throws:

AstException - if an error occurred in the AST library

show

public void show()

Display a textual representation of an Object on standard output. This function displays a textual description of any AST Object on standard output. It is provided primarily as an aid to debugging.

Throws:

AstException - if an error occurred in the AST library

test

public boolean test(String attrib)

Test if an Object attribute value is set. This function returns a boolean result (0 or 1) to indicate whether a value has been explicitly set for one of an Object's attributes.

Notes

- Attribute names are not case sensitive and may be surrounded by white space.
- A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.
- A value of zero will also be returned if this function is used to test a read-only attribute, although no error will result.

Parameters:

attrib - Pointer to a null-terminated character string containing the name of the attribute to be tested.

Throws:

AstException - if an error occurred in the AST library

tune

public static int tune(String name,
                       int value)

Set or get an integer-valued AST global tuning parameter. This function returns the current value of an integer-valued AST global tuning parameter, optionally storing a new value for the parameter. For character-valued tuning parameters, see astTuneC.

Tuning Parameters

ObjectCaching A boolean flag which indicates what should happen to the memory occupied by an AST Object when the Object is deleted (i.e. when its reference count falls to zero or it is deleted using astDelete). If this is zero, the memory is simply freed using the systems "free" function. If it is non-zero, the memory is not freed. Instead a pointer to it is stored in a pool of such pointers, all of which refer to allocated but currently unused blocks of memory. This allows AST to speed up subsequent Object creation by re-using previously allocated memory blocks rather than allocating new memory using the systems malloc function. The default value for this parameter is zero. Setting it to a non-zero value will result in Object memory being cached in future. Setting it back to zero causes any memory blocks currently in the pool to be freed. Note, this tuning parameter only controls the caching of memory used to store AST Objects. To cache other memory blocks allocated by AST, use MemoryCaching. MemoryCaching A boolean flag similar to ObjectCaching except that it controls caching of all memory blocks of less than 300 bytes allocated by AST (whether for internal or external use), not just memory used to store AST Objects.

Notes

- This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances.
- All threads in a process share the same AST tuning parameters values.

Parameters:

name - The name of the tuning parameter (case-insensitive).

value - The new value for the tuning parameter. If this is AST__TUNULL, the existing current value will be retained.

Returns:

The original value of the tuning parameter. A default value will be returned if no value has been set for the parameter.

Throws:

AstException - if an error occurred in the AST library

getID

public String getID()

Get object identification string. This attribute contains a string which may be used to identify the Object to which it is attached. There is no restriction on the contents of this string, which is not used internally by the AST library, and is simply returned without change when required. The default value is an empty string.

An identification string can be valuable when, for example, several Objects have been stored in a file (using astWrite) and are later retrieved (using astRead). Consistent use of the ID attribute allows the retrieved Objects to be identified without depending simply on the order in which they were stored.

This attribute may also be useful during debugging, to distinguish similar Objects when using astShow to display them.

Notes

- Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the astWrite function.

Returns:

this object's ID attribute

setID

public void setID(String ID)

Set object identification string. This attribute contains a string which may be used to identify the Object to which it is attached. There is no restriction on the contents of this string, which is not used internally by the AST library, and is simply returned without change when required. The default value is an empty string.

An identification string can be valuable when, for example, several Objects have been stored in a file (using astWrite) and are later retrieved (using astRead). Consistent use of the ID attribute allows the retrieved Objects to be identified without depending simply on the order in which they were stored.

This attribute may also be useful during debugging, to distinguish similar Objects when using astShow to display them.

Notes

- Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the astWrite function.

Parameters:

ID - the ID attribute of this object

getIdent

public String getIdent()

Get permanent Object identification string. This attribute is like the ID attribute, in that it contains a string which may be used to identify the Object to which it is attached. The only difference between ID and Ident is that Ident is transferred when an Object is copied, but ID is not.

Returns:

this object's Ident attribute

setIdent

public void setIdent(String Ident)

Set permanent Object identification string. This attribute is like the ID attribute, in that it contains a string which may be used to identify the Object to which it is attached. The only difference between ID and Ident is that Ident is transferred when an Object is copied, but ID is not.

Parameters:

Ident - the Ident attribute of this object

getNobject

public int getNobject()

Get number of Objects in class. Number of Objects in class.

Returns:

this object's Nobject attribute

getObjSize

public int getObjSize()

Get the in-memory size of the Object. This attribute gives the total number of bytes of memory used by the Object. This includes any Objects which are encapsulated within the supplied Object.

Returns:

this object's ObjSize attribute

getRefCount

public int getRefCount()

Get count of active Object pointers. This attribute gives the number of active pointers associated with an Object. It is modified whenever pointers are created or annulled (by astClone, astAnnul or astEnd for example). The count includes the initial pointer issued when the Object was created.

If the reference count for an Object falls to zero as the result of annulling a pointer to it, then the Object will be deleted.

Returns:

this object's RefCount attribute