au.gov.aao.drama
Class SdsID

java.lang.Object
  au.gov.aao.drama.SdsID

Direct Known Subclasses:

Arg

public class SdsID
extends Object

This class implements an interface to the AAO's DRAMA SDS Library Java.

See Self Defining Data System for full details on SDS.

You should not that this class contains SDS ID's only, not complete SDS structures. Also note that mutilple SDS ID's can refer to the one SDS Structure. See the SDS document above for details on SDS ID's and structures.

As a result of the above, this class sometimes needs some help from the user to determine if the underlying SDS structure should be deleted and the id free-ed when the instance is finalized. As a result - there a three flags associated with each instance. The "delete" flag is set true to indicate the structure should be deleted when the instance is finialized. The "free" flag is set true to indicate if the SDS ID should be free-ed when the instance is finialized. The "readfree" flag indicates that SdsReadFree() should be invoked when the instance is finialized. Where possible, these flags are set automaticically, but if you are constructing an SdsID instance from externally generated SDS ID, or you wish to export the ID elsewhere, you may need to deal with these flags appropiately. The relevant functions have more details.

Version:

@(#) $Id: ACMM:DramaJava/SdsID.java,v 3.52 17-Sep-2009 14:08:19+10 tjf $

Author:

Tony Farrell

See Also:

DramaTask, Arg

Field Summary

protected int	id The underlying SDS ID of the item.
static String	RCSID The RCS (ACMM) ID.
static int	SDS_BYTE SDS Type code value - Indicates a Byte (8 bit) type.
static int	SDS_CHAR SDS Type code value - Indicates a Character type.
static int	SDS_DOUBLE SDS Type code value - Indicates a double length floating point type.
static int	SDS_FLOAT SDS Type code value - Indicates a floating point type.
static int	SDS_I64 SDS Type code value - Indicates a Long (64 bit) Integer type.
static int	SDS_INT SDS Type code value - Indicates an Integer (32 bit) type.
static int	SDS_SHORT SDS Type code value - Indicates a Short (16 bit) type.
static int	SDS_STRUCT SDS Type code value - Indicates an Sds Structure type.
static int	SDS_UBYTE SDS Type code value - Indicates an Unsigned Byte (8 bit) type.
static int	SDS_UI64 SDS Type code value - Indicates a Unsigned Long (64 bit) Integer type.
static int	SDS_UINT SDS Type code value - Indicates an Unsigned Integer (32 bit) type.
static int	SDS_USHORT SDS Type code value - Indicates an Unsigned Short (16 bit) type.

Constructor Summary

SdsID()
Create a SdsID containing a NULL Sds id.

SdsID(int item)
Create a SdsID using a C ID type.

SdsID(int item, boolean free)
Create a SdsID using a C ID type, with free flag specified.

SdsID(int item, boolean free, boolean delete)
Create a SdsID using a C ID type, with free and delete flags.

SdsID(int item, boolean free, boolean del, boolean readfree)
Create a SdsID using a C ID type, with all flags specifyable.

SdsID(SdsID source)
Create a copy of an existing SDS item.

SdsID(SdsID source, int index)
Create an access to a existing SDS structure by index

SdsID(SdsID array_id, int[] dims)
Create an access to a cell of an existing SDS structure array.

SdsID(SdsID source, String name)
Create an access to an item in an SDS structure

SdsID(SdsID parent_id, String name, int code)
Create a new child SDS item

SdsID(SdsID parent_id, String name, int code, int[] dims)
Create a new array child SDS item

SdsID(String filename)
Create an SdsID, with the structure read from a file

SdsID(String name, int code)
Create a new top-level SDS item

SdsID(String name, int code, int[] dims)
Create a new array top-level SDS item

Method Summary

void	ClearDelete() Clear DELETE flag.
void	ClearFree() Clear FREE flag.
static void	ClearFreeIDWatch() Clear watching of an ID.
void	ClearReadFree() Clear READ-FREE flag.
int	Code() Return the code of an item.
void	Debug() Debugging routine - prints the SDS id and an integer to stdout.
protected void	Debug(String event)
protected void	Debug(String event, SdsID other, String otherEvent)
void	DeepCopy(SdsID source) Make this object refer to a deep copy of the source object.
void	Delete() Delete the item explictly.
int	Dims(int[] dims) Returns the dims of an item,
void	EnableFreeIDWatch() Enable watching of this SDS id by low level SDS debugging code.
void	Extract() Extract the item from its top level structure This method makes the current item a top-level item in it's own right.
void	FillArray(SdsID filler) Fill a structured array with copies of a specified structure.
protected void	finalize() Finalizer for the SdsID class.
String[]	Get(boolean reverse) Get a string array from the SDS item.
String	Get(int offset) Return string DATA from the SDS item into a string.
void	Get(int offset, byte[] data) Get byte (8 bit) DATA from the SDS item.
void	Get(int offset, double[] data) Get double length floating point DATA from the SDS item.
void	Get(int offset, float[] data) Get float DATA from the SDS item.
void	Get(int offset, int[] data) Get int (32 bit) DATA from the SDS item.
void	Get(int offset, long[] data) Get long (64 bit) DATA from the SDS item.
void	Get(int offset, short[] data) Get short (16 bit) DATA from the SDS item.
String	GetContructorLocation() Returns a string giving the location from which the constructor for this object was invoked.
int	ID() Return the SdsID as an integer.
void	Insert(SdsID to_insert) Insert a new object into our object.
void	Insert(SdsID to_insert, int[] dims) Insert a new object into a structured array item.
void	List() List the SDS structure to stdiout.
String	Name() Return the name of an item
void	Outlives() Mark the SDS item as outliving the Java object.
void	Put(int offset, byte[] data) Put byte (8 bit) DATA to the SDS item.
void	Put(int offset, double[] data) Put double DATA to the SDS item.
void	Put(int offset, float[] data) Put float DATA to the SDS item.
void	Put(int offset, int[] data) Put int (32 bit) DATA to the SDS item.
void	Put(int offset, long[] data) Put long (64 bit) DATA to the SDS item.
void	Put(int offset, short[] data) Put short (16 bit) DATA to the SDS item.
void	Rename(String name) Rename an SDS item.
void	Resize(int[] dims) Resize an SDS array.
static void	SetDebugging(boolean flag) Enable/Disable debugging (to stdout) of various SDS operations.
void	SetDelete() Set DELETE flag.
void	SetFree() Set FREE flag.
void	SetReadFree() Set READ-FREE flag.
void	ShallowCopyNoOutlive(SdsID source) Make this id refer to the same id as another object but don't outlive it.
void	ShallowCopyOutlive(SdsID source) Make this id refer to the same id as another object and outlive it.
void	StuffUp() Debugging test routine.
String	toString() Convert an Sds structure to a string using the ArgToString C function.
void	Write(String filename) Write the SDS structure to a specified file.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

RCSID

public static final String RCSID

The RCS (ACMM) ID. This field returns the source code archive ID of this class's source file.

The returned string corresponds to the version string seen above (in the class description comments), but will contain the version details of the compiled class file's actual source file.

(ACMM is the source code archive system used by the AAO. If the string returned by RCSID does not contain the string ACMM, then it is likely the source code has been archived again outside the AAO).

See Also:

Constant Field Values

SDS_STRUCT

public static final int SDS_STRUCT

SDS Type code value - Indicates an Sds Structure type.

See Also:

Constant Field Values

SDS_CHAR

public static final int SDS_CHAR

SDS Type code value - Indicates a Character type.

See Also:

Constant Field Values

SDS_UBYTE

public static final int SDS_UBYTE

SDS Type code value - Indicates an Unsigned Byte (8 bit) type.

See Also:

Constant Field Values

SDS_BYTE

public static final int SDS_BYTE

SDS Type code value - Indicates a Byte (8 bit) type.

See Also:

Constant Field Values

SDS_USHORT

public static final int SDS_USHORT

SDS Type code value - Indicates an Unsigned Short (16 bit) type.

See Also:

Constant Field Values

SDS_SHORT

public static final int SDS_SHORT

SDS Type code value - Indicates a Short (16 bit) type.

See Also:

Constant Field Values

SDS_UINT

public static final int SDS_UINT

SDS Type code value - Indicates an Unsigned Integer (32 bit) type.

See Also:

Constant Field Values

SDS_INT

public static final int SDS_INT

SDS Type code value - Indicates an Integer (32 bit) type.

See Also:

Constant Field Values

SDS_FLOAT

public static final int SDS_FLOAT

SDS Type code value - Indicates a floating point type.

See Also:

Constant Field Values

SDS_DOUBLE

public static final int SDS_DOUBLE

SDS Type code value - Indicates a double length floating point type.

See Also:

Constant Field Values

SDS_I64

public static final int SDS_I64

SDS Type code value - Indicates a Long (64 bit) Integer type.

See Also:

Constant Field Values

SDS_UI64

public static final int SDS_UI64

SDS Type code value - Indicates a Unsigned Long (64 bit) Integer type.

See Also:

Constant Field Values

id

protected int id

The underlying SDS ID of the item.

Constructor Detail

SdsID

public SdsID()

Create a SdsID containing a NULL Sds id.

SdsID

public SdsID(int item)

Create a SdsID using a C ID type. The underlying SDS structure is NOT deleted or ID freeed when the Java object is finalized.

Parameters:

item - An integer representation of an SDS ID.

SdsID

public SdsID(int item,
             boolean free)

Create a SdsID using a C ID type, with free flag specified. The underlying SDS structure is NOT deleted when java object is finailized

Parameters:

item - An integer representation of an SDS ID.

free - Set true if SDS ID is to be freeed when the the Java object is finalized, false if this is not to be done.

SdsID

public SdsID(int item,
             boolean free,
             boolean delete)

Create a SdsID using a C ID type, with free and delete flags.

Parameters:

item - An integer representation of an SDS ID.

free - Set true if SDS ID is to be freeed when the the Java object is finalized, false if this is not to be done.

delete - Set true if underlying SDS structure is to be deleted when the the Java object is finalized, false if this is not to be done.

SdsID

public SdsID(int item,
             boolean free,
             boolean del,
             boolean readfree)

Create a SdsID using a C ID type, with all flags specifyable. Note that is does not make sense for "delete" and "readfree" to both be true, but this is not checked as yet.

Parameters:

item - An integer representation of an SDS ID.

free - Set true if SDS ID is to be freeed when the the Java object is finalized, false if this is not to be done.

del - Set true if underlying SDS structure is to be deleted when the the Java object is finalized, false if this is not to be done.

readfree - Set true if SdsReadFree is to be invoked on the SDS ID when the object is finalized - used if ID is of an SDS structure which has been read from a file.

SdsID

public SdsID(String filename)
      throws DramaException

Create an SdsID, with the structure read from a file

Parameters:

filename - The file to read the SDS structure from

Throws:

DramaException - Thrown on errors in the DRAMA code.

SdsID

public SdsID(SdsID parent_id,
             String name,
             int code)
      throws DramaException

Create a new child SDS item

Parameters:

parent_id - The SDS structure to create this item within.

name - The name of this new item

code - The SDS Code for the item type.

Throws:

DramaException - Thrown on errors in the DRAMA code.

SdsID

public SdsID(String name,
             int code)
      throws DramaException

Create a new top-level SDS item

Parameters:

name - The name of this new item

code - The SDS Code for the item type.

Throws:

DramaException - Thrown on errors in the DRAMA code.

SdsID

public SdsID(SdsID parent_id,
             String name,
             int code,
             int[] dims)
      throws DramaException

Create a new array child SDS item

Parameters:

parent_id - The SDS structure to create this item within.

name - The name of this new item

code - The SDS Code for the item type.

dims - The dimensions. Maximum of 7.

Throws:

DramaException - Thrown on errors in the DRAMA code.

SdsID

public SdsID(String name,
             int code,
             int[] dims)
      throws DramaException

Create a new array top-level SDS item

Parameters:

name - The name of this new item

code - The SDS Code for the item type.

dims - The dimensions. Maximum of 7.

Throws:

DramaException - Thrown on errors in the DRAMA code.

SdsID

public SdsID(SdsID array_id,
             int[] dims)
      throws DramaException

Create an access to a cell of an existing SDS structure array.

Parameters:

array_id - The SDS structure array we are accessing.

dims - The dimensions of the element we are accessing

Throws:

DramaException - Thrown on errors in the DRAMA code.

SdsID

public SdsID(SdsID source)
      throws DramaException

Create a copy of an existing SDS item. This does a deep copy - the SDS structure is duplicated

Parameters:

source - The structure we want to copy.

Throws:

DramaException - Thrown on errors in the DRAMA code.

SdsID

public SdsID(SdsID source,
             String name)
      throws DramaException

Create an access to an item in an SDS structure

Parameters:

source - The SDS structure we are accessing.

name - The name of the item to access.

Throws:

DramaException - Thrown on errors in the DRAMA code.

SdsID

public SdsID(SdsID source,
             int index)
      throws DramaException

Create an access to a existing SDS structure by index

Parameters:

source - The SDS structure we are accessing

index - The index to the item we want to access.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Method Detail

finalize

protected void finalize()
                 throws DramaException,
                        Throwable

Finalizer for the SdsID class. The SDS structure may be deleted, SDS ID free and or SdsReadFree invoked, depending on how the item was created

Overrides:

finalize in class Object

Throws:

DramaException - Thrown on errors in the DRAMA code.

Throwable - As per .

SetFree

public void SetFree()

Set FREE flag. Indicates that the underlying SDS Id should be free-ed when the Java object is finalized

ClearFree

public void ClearFree()

Clear FREE flag. Indicates that the underlying SDS Id should NOT be free-ed when the Java object is finalized

SetDelete

public void SetDelete()

Set DELETE flag. Indicates that the underlying SDS structure should be deleted when the Java object is finalized

ClearDelete

public void ClearDelete()

Clear DELETE flag. Indicates that the underlying SDS structure should NOT be deleted when the Java object is finalized

SetReadFree

public void SetReadFree()

Set READ-FREE flag. Indicates that when the underlying Java object is finalized, the SdsReadFree C function should be invoked - only relvant for items which have been read from a file.

ClearReadFree

public void ClearReadFree()

Clear READ-FREE flag. Indicates that when the underlying Java object is finalized, the SdsReadFree C function should NOT be invoked - only relvant for items which have been read from a file.

Outlives

public void Outlives()

Mark the SDS item as outliving the Java object. This method is used to indicate that the underlying SDS structure and ID should not be destroyed when the Java object is finalized. Used if the same SDS structure is being used elsewhere

Delete

public void Delete()
            throws DramaException

Delete the item explictly. The SDS item is deleted and if the ID is marked for freeing, the ID is freeed. You can no longer access this item. This method is normally used for deleting components of a structure.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Extract

public void Extract()
             throws DramaException

Extract the item from its top level structure This method makes the current item a top-level item in it's own right. If the underlying SDS id is to be free-ed when the Java object is finialized, then the structure will also be deleted at the same time. You can use the ClearDelete() and ClearFree() flags to change this.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Get

public void Get(int offset,
                long[] data)
         throws DramaException

Get long (64 bit) DATA from the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array to fetch the data into. The size of this array indicates how much data to fetch.

Throws:

DramaException - Thrown on errors in the DRAMA code in particular, Status code DJAVA__INSUFDATA if there is not sufficent data to fill the array.

Get

public void Get(int offset,
                int[] data)
         throws DramaException

Get int (32 bit) DATA from the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array to fetch the data into. The size of this array indicates how much data to fetch.

Throws:

DramaException - Thrown on errors in the DRAMA code in particular, Status code DJAVA__INSUFDATA if there is not sufficent data to fill the array.

Get

public void Get(int offset,
                short[] data)
         throws DramaException

Get short (16 bit) DATA from the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array to fetch the data into. The size of this array indicates how much data to fetch.

Throws:

DramaException - Thrown on errors in the DRAMA code in particular, Status code DJAVA__INSUFDATA if there is not sufficent data to fill the array.

Get

public void Get(int offset,
                byte[] data)
         throws DramaException

Get byte (8 bit) DATA from the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array to fetch the data into. The size of this array indicates how much data to fetch.

Throws:

DramaException - Thrown on errors in the DRAMA code in particular, Status code DJAVA__INSUFDATA if there is not sufficent data to fill the array.

Get

public String Get(int offset)
           throws DramaException

Return string DATA from the SDS item into a string. This method requires that the SdsID structure refer to a one dimensional array of SDS_CHAR type items. If it does, then that data is returned as a string.

Parameters:

offset - The offset into the item to fetch

Throws:

DramaException - Thrown on errors in the DRAMA code.

Get

public String[] Get(boolean reverse)
             throws DramaException

Get a string array from the SDS item. This method requires that the SdsID structure refer to a two dimensional array of SDS_CHAR type items. If it does, then that data is returned as a string array.

Parameters:

reverse - If false, then the first SDS array index is the maximum size of each string and the second is the number of items in the string array. If true, then this representation is reversed.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Get

public void Get(int offset,
                float[] data)
         throws DramaException

Get float DATA from the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array to fetch the data into. The size of this array indicates how much data to fetch.

Throws:

DramaException - Thrown on errors in the DRAMA code . * in particular, Status code DJAVA__INSUFDATA if there is not sufficent data to fill the array.

Get

public void Get(int offset,
                double[] data)
         throws DramaException

Get double length floating point DATA from the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array to fetch the data into. The size of this array indicates how much data to fetch.

Throws:

DramaException - Thrown on errors in the DRAMA code in particular, Status code DJAVA__INSUFDATA if there is not sufficent data to fill the array.

Put

public void Put(int offset,
                long[] data)
         throws DramaException

Put long (64 bit) DATA to the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array of data to put. The size of this array indicates how much data to put.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Put

public void Put(int offset,
                int[] data)
         throws DramaException

Put int (32 bit) DATA to the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array of data to put. The size of this array indicates how much data to put.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Put

public void Put(int offset,
                short[] data)
         throws DramaException

Put short (16 bit) DATA to the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array of data to put. The size of this array indicates how much data to put.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Put

public void Put(int offset,
                byte[] data)
         throws DramaException

Put byte (8 bit) DATA to the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array of data to put. The size of this array indicates how much data to put.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Put

public void Put(int offset,
                float[] data)
         throws DramaException

Put float DATA to the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array of data to put. The size of this array indicates how much data to put.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Put

public void Put(int offset,
                double[] data)
         throws DramaException

Put double DATA to the SDS item.

Parameters:

offset - The offset into the item to fetch

data - Array of data to put. The size of this array indicates how much data to put.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Name

public String Name()
            throws DramaException

Return the name of an item

Returns:

The name

Throws:

DramaException - Thrown on errors in the DRAMA code.

Code

public int Code()
         throws DramaException

Return the code of an item.

Returns:

The SDS Type code as an integer, one of the SDS_* values.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Dims

public int Dims(int[] dims)
         throws DramaException

Returns the dims of an item,

Parameters:

dims - An array to contain the dimenions. If there are insufficent, trailing dimensions are ignored (at the moment - we should actually throw an exception).

Returns:

The number of dims

Throws:

DramaException - Thrown on errors in the DRAMA code.

Rename

public void Rename(String name)
            throws DramaException

Rename an SDS item.

Parameters:

name - The name name for the item

Throws:

DramaException - Thrown on errors in the DRAMA code.

Resize

public void Resize(int[] dims)
            throws DramaException

Resize an SDS array.

Parameters:

dims - The new dimensions - maximum of 7 dimensions.

Throws:

DramaException - Thrown on errors in the DRAMA code.

List

public void List()
          throws DramaException

List the SDS structure to stdiout.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Write

public void Write(String filename)
           throws DramaException

Write the SDS structure to a specified file.

Parameters:

filename - The name of the file.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Insert

public void Insert(SdsID to_insert)
            throws DramaException

Insert a new object into our object.

Parameters:

to_insert - The structure which inserted into this structure.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Insert

public void Insert(SdsID to_insert,
                   int[] dims)
            throws DramaException

Insert a new object into a structured array item.

Parameters:

to_insert - The structure which inserted into this structure.

dims - dims The dimensions at which to insert the structure.

Throws:

DramaException - Thrown on errors in the DRAMA code.

FillArray

public void FillArray(SdsID filler)
               throws DramaException

Fill a structured array with copies of a specified structure.

Parameters:

filler - The structure to copy and fill the array with.

Throws:

DramaException - Thrown on errors in the DRAMA code.

ShallowCopyOutlive

public void ShallowCopyOutlive(SdsID source)
                        throws DramaException

Make this id refer to the same id as another object and outlive it. Any existing item referred to by this Java object is cleaned up, possibily resulting in deletion of the underlying SDS structure. By outliving it, we mean that the source free, delete and readfree flags are cleared, whilst this item has the original values of those flags.

Parameters:

source - The item to shallow copy.

Throws:

DramaException - Thrown on errors in the DRAMA code.

ShallowCopyNoOutlive

public void ShallowCopyNoOutlive(SdsID source)
                          throws DramaException

Make this id refer to the same id as another object but don't outlive it. Any existing item referred to by this Java object is cleaned up, possibily resulting in deletion of the underlying SDS structure. We don't outlive the source item - no attempt will be made to free the ID or delete the structure when this Java object is finalized.

Parameters:

source - The item to shallow copy.

Throws:

DramaException - Thrown on errors in the DRAMA code.

ID

public int ID()

Return the SdsID as an integer. Use with caution, mainly to pass to native language routines easily

DeepCopy

public void DeepCopy(SdsID source)
              throws DramaException

Make this object refer to a deep copy of the source object. A new SDS structure is created which is copy of the source object and this object is made to refer to that copy.

Parameters:

source - The item to deep copy.

Throws:

DramaException - Thrown on errors in the DRAMA code.

Debug

public void Debug()

Debugging routine - prints the SDS id and an integer to stdout.

StuffUp

public void StuffUp()

Debugging test routine. Please don't use, it will be removed later

toString

public String toString()

Convert an Sds structure to a string using the ArgToString C function.

Overrides:

toString in class Object

Returns:

A string representation of the structure.

EnableFreeIDWatch

public void EnableFreeIDWatch()
                       throws DramaException

Enable watching of this SDS id by low level SDS debugging code. This removes any watches on other ids. In the current implementation, this will result in messages being printed on stdout when this id is free-ed. This can be usefull in debugging double sds-free problems (say an SDS id being found to be bad unexpectedly)

Throws:

DramaException

See Also:

ClearFreeIDWatch()

ClearFreeIDWatch

public static void ClearFreeIDWatch()
                             throws DramaException

Clear watching of an ID.

Throws:

DramaException

See Also:

EnableFreeIDWatch()

SetDebugging

public static void SetDebugging(boolean flag)

Enable/Disable debugging (to stdout) of various SDS operations.

Parameters:

flag - Set true to enable debugging, false to disable it.

Debug

protected void Debug(String event)

Debug

protected void Debug(String event,
                     SdsID other,
                     String otherEvent)

GetContructorLocation

public String GetContructorLocation()

Returns a string giving the location from which the constructor for this object was invoked.