|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectuk.ac.starlink.hds.HDSObject
public class HDSObject
Provides a Java interface to the Starlink
HDS
library. The methods provided here are all implemented using JNI
native code and are intended to map one-to-one to the public Fortran
calls provided by HDS, using similar arguments to those calls.
Other useful methods on HDS objects should be provided by
other classes which extend or contain instances of HDSObject
.
For this reason there is no constructor, a factory method like
hdsOpen
or datFind
should be used instead.
On the whole, the implementation of this class is such that a call to one of these methods results in a call to the similarly-named routine in the HDS library. This is not always the most efficient way to procure the data requested.
The arguments of the methods declared by this class are not identical
with those of the corresponding Fortran HDS calls, and
the documentation for each of the HDSObject
methods
should be checked before use. However, the following rules in
general apply:
HDSObject
object represented by that locator.
The locator itself is kept as a (private) member of the the
HDSObject
, and will never be referred to by Java
code.
HDSException
is called. The getMessage
method of the HDSException
returns the error message generated. All methods can therefore
throw an HDSException
.
HDSObject
object.
long
s.
Using the above rules, we see that, for instance:
CALL DAT_FIND( LOC1, NAME, LOC2, STATUS )becomes
public native HDSObject datFind( String name ) throws HDSException;
Note: This class is not complete; it is being added to as calls are required.
Field Summary | |
---|---|
static int |
DAT__SZNAM
Maximum number of characters in the name of an HDS component. |
static int |
DAT__SZTYP
maximum number of characters in the name of an HDS type string. |
Method Summary | |
---|---|
void |
datAnnul()
Annul locator. |
HDSObject |
datCell(long[] position)
Get an HDSObject from a cell (element) of an array object. |
HDSObject |
datClone()
Clone locator. |
void |
datCopy(HDSObject hdsobj,
String name)
Recursively copy an object into a component. |
void |
datErase(String name)
Erase component. |
HDSObject |
datFind(String name)
Find named component. |
String |
datGet0c()
Read scalar primitive as String type. |
double |
datGet0d()
Read scalar primitive as double type. |
int |
datGet0i()
Read scalar primitive as int type. |
boolean |
datGet0l()
Read scalar primitive as boolean type. |
float |
datGet0r()
Read scalar primitive as float type. |
Object |
datGetc(long[] shape)
Read a primitive as String type. |
Object |
datGetd(long[] shape)
Read a primitive as double type. |
Object |
datGeti(long[] shape)
Read a primitive as integer type. |
Object |
datGetl(long[] shape)
Read a primitive as boolean type. |
Object |
datGetr(long[] shape)
Read a primitive as float type. |
String[] |
datGetvc()
Read a primitive as String type as if it were
vectorised (regardless of its actual shape). |
double[] |
datGetvd()
Read a primitive as double type as if it were
vectorised (regardless of its actual shape). |
int[] |
datGetvi()
Read a primitive as int type as if it were
vectorised (regardless of its actual shape). |
boolean[] |
datGetvl()
Read a primitive as boolean type as if it were
vectorised (regardless of its actual shape). |
float[] |
datGetvr()
Read a primitive as float type as if it were
vectorised (regardless of its actual shape). |
HDSObject |
datIndex(int index)
Index into component list. |
Buffer |
datMapv(String type,
String mode)
Map primitive. |
String |
datName()
Enquire object name. |
int |
datNcomp()
Enquire number of components. |
void |
datNew(String name,
String type,
long[] dims)
Create component. |
HDSObject |
datParen()
Locate parent structure. |
boolean |
datPrmry()
Enquire primary/secondary locator status. |
void |
datPrmry(boolean primary)
Set primary/secondary locator status. |
void |
datPut0c(String value)
Write scalar primitive. |
void |
datPut0d(double value)
Write scalar primitive. |
void |
datPut0i(int value)
Write scalar primitive. |
void |
datPut0l(boolean value)
Write scalar primitive. |
void |
datPut0r(float value)
Write scalar primitive. |
void |
datPutvc(String[] value)
Write a primitive as if it were vectorised (regardless of its actual shape). |
void |
datPutvd(double[] value)
Write a primitive as if it were vectorised (regardless of its actual shape). |
void |
datPutvi(int[] value)
Write a primitive as if it were vectorised (regardless of its actual shape). |
void |
datPutvl(boolean[] value)
Write a primitive as if it were vectorised (regardless of its actual shape). |
void |
datPutvr(float[] value)
Write a primitive as if it were vectorised (regardless of its actual shape). |
String |
datRef()
Obtain a reference for an HDSObject. |
long[] |
datShape()
Enquire object shape. |
long |
datSize()
Enquire object size. |
boolean |
datState()
Enquire object state. |
boolean |
datStruc()
Enquire whether object is a structure. |
boolean |
datThere(String name)
Enquire if a component of a structure exists. |
String |
datType()
Enquire object type. |
void |
datUnmap()
Unmap an object mapped by another HDSObject method. |
boolean |
datValid()
Enquire locator validity. |
protected void |
finalize()
|
static int |
hdsGtune(String param)
Get HDS tuning parameter value. |
static HDSObject |
hdsNew(String file,
String name,
String type,
long[] dims)
Create container file. |
static HDSObject |
hdsOpen(String container,
String accessMode)
Open container file. |
static void |
hdsShow(String topic)
Show HDS statistics. |
int |
hdsTrace(String[] results)
Trace object path. |
static void |
hdsTune(String param,
int value)
Set HDS tuning parameter. |
String |
toString()
|
Methods inherited from class java.lang.Object |
---|
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int DAT__SZNAM
public static final int DAT__SZTYP
Method Detail |
---|
protected void finalize() throws Throwable
finalize
in class Object
Throwable
public String toString()
toString
in class Object
public static int hdsGtune(String param) throws HDSException
hdsTune(java.lang.String, int)
routine).
param
- Name of the tuning parameter
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public static HDSObject hdsNew(String file, String name, String type, long[] dims) throws HDSException
file
- the name of the container file to be created. ".sdf"
will be added an extension is not specified.name
- the name of the object to be createdtype
- the HDS type of the top-level object to be createddims
- the dimensions of the top-level object to be created
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public static HDSObject hdsOpen(String container, String accessMode) throws HDSException
container
- the container file nameaccessMode
- the access mode "READ", "UPDATE" or "WRITE"
HDSObject
representing
the newly opened container file
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public static void hdsShow(String topic) throws HDSException
topic
- name of the topic on which to supply information.
One of "DATA", "FILES" or "LOCATORS".
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public int hdsTrace(String[] results) throws HDSException
results
- a two-element String array. On exit the first element
will be set to the object path name within the
container file, and the second element to the
container file name.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public static void hdsTune(String param, int value) throws HDSException
param
- Name of the tuning parametervalue
- the value of the tuning parameter
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datAnnul() throws HDSException
It is not generally necessary for client code to call this method (though it is permissible), since it is called by the finalizer method. The garbage collector can therefore be relied upon to annul resources which are associated with unreferenced HDSObjects in due course. Note however that there is no guarantee when (or if) garbage collection will be performed, so side-effects of datAnnul, such as the unmapping of mapped data, must be invoked explicitly rather than leaving them to get done when the automatic annul is done.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public HDSObject datCell(long[] position) throws HDSException
HDSObject
from a cell (element) of an array object.
position
- the location within the array of the cell to
retreive
HDSObject
representing the
indicated element of the array
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public HDSObject datClone() throws HDSException
HDSObject
referring to the same
object as this HDSObject
except
that the locator will always be secondary
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datCopy(HDSObject hdsobj, String name) throws HDSException
hdsobj
- destination objectname
- component name in destination object
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datErase(String name) throws HDSException
name
- the name of the component within this
HDSObject
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public HDSObject datFind(String name) throws HDSException
name
- the name of the component within this
HDSObject
HDSObject
representing the
named component
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public Object datGetc(long[] shape) throws HDSException
String
type.
shape
- an array giving the shape of
the HDS primitive
Object
giving the contents of
this primitive HDSObject. If this object
represents an HDS array primitive, the return
value is an array, or
array of arrays, or ... of String
s,
according to the dimensionality of the primitive.
If this object is a scalar primitive
(shape
has dimensionality of zero)
it will be the scalar value as a
String
.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public Object datGetl(long[] shape) throws HDSException
boolean
type.
shape
- an array giving the shape of
the HDS primitive
Object
giving the contents of
this primitive HDSObject. If this object
represents an HDS array primitive,
the return value is an array, or
array of arrays, or ... of boolean
s,
according to the dimensionality of the primitive.
If this object is a scalar primitive
(shape
has dimensionality of zero)
it will be an Boolean
wrapping the
value.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public Object datGeti(long[] shape) throws HDSException
integer
type.
shape
- an array giving the shape of
the HDS primitive to return
Object
giving the contents of
this primitive HDSObject. If this object
represents an HDS array primitive,
the return value is an array, or
array of arrays, or ... of int
s,
according to the dimensionality of the primitive.
If this object is a scalar primitive
(shape
has dimensionality of zero)
it will be an Integer
wrapping the
value.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public Object datGetr(long[] shape) throws HDSException
float
type.
shape
- an array giving the shape of
the HDS primitive to return
Object
giving the contents of
this primitive HDSObject. If this object
represents an HDS array primitive,
the return value is an array, or
array of arrays, or ... of float
s,
according to the dimensionality of the primitive.
If this object is a scalar primitive
(shape
has dimensionality of zero)
it will be an Float
wrapping the
value.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public Object datGetd(long[] shape) throws HDSException
double
type.
shape
- an array giving the shape of
the HDS primitive to return
Object
giving the contents of
this primitive HDSObject. If this object
represents an HDS array primitive,
the return value is an array, or
array of arrays, or ... of double
s,
according to the dimensionality of the primitive.
If this object is a scalar primitive
(shape
has dimensionality of zero)
it will be an Double
wrapping the
value.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public String[] datGetvc() throws HDSException
String
type as if it were
vectorised (regardless of its actual shape).
The length of the returned array will be the size of the entire array
of this object (note: one element for each array element, not for
each character). Trailing blanks in the strings will be trimmed so
strings may be smaller than their declared size. This method cannot
be used to read arrays with more than Integer.MAX_VALUE
elements.
String
s,
one for each element in the primitive array.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public boolean[] datGetvl() throws HDSException
boolean
type as if it were
vectorised (regardless of its actual shape).
The length of the returned array will be the size of the entire
array of this object. This method cannot be used to read arrays
with more than Integer.MAX_VALUE
elements.
boolean
s
containing all the values of the primitive array
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public int[] datGetvi() throws HDSException
int
type as if it were
vectorised (regardless of its actual shape).
The length of the returned array will be the size of the entire
array of this object. This method cannot be used to read arrays
with more than Integer.MAX_VALUE
elements.
int
s
containing all the values of the primitive array
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public float[] datGetvr() throws HDSException
float
type as if it were
vectorised (regardless of its actual shape).
The length of the returned array will be the size of the entire
array of this object. This method cannot be used to read arrays
with more than Integer.MAX_VALUE
elements.
float
s
containing all the values of the primitive array
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public double[] datGetvd() throws HDSException
double
type as if it were
vectorised (regardless of its actual shape).
The length of the returned array will be the size of the entire
array of this object. This method cannot be used to read arrays
with more than Integer.MAX_VALUE
elements.
double
s
containing all the values of the primitive array
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public String datGet0c() throws HDSException
String
type.
As with the underlying HDS routine, this may be used to return a
representation of a scalar value of any type.
HDSObject
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public boolean datGet0l() throws HDSException
boolean
type.
HDSObject
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public int datGet0i() throws HDSException
int
type.
HDSObject
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public float datGet0r() throws HDSException
float
type.
HDSObject
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public double datGet0d() throws HDSException
double
type.
HDSObject
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public HDSObject datIndex(int index) throws HDSException
index
- position in list of component to return
HDSObject
representing the
index
'th component of this
HDSObject
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public Buffer datMapv(String type, String mode) throws HDSException
Buffer
of a type determined
by the type parameter. Note that the unsigned HDS types (_UWORD and
_UBYTE) are not currently supported (an IllegalArgumentException
will be thrown).
type
- an HDS type string giving the type with which to map
the array; one of "_BYTE", "_WORD", "_INTEGER", "_REAL",
"_DOUBLE".mode
- a string indicating access mode; one of "READ",
"WRITE", "UPDATE".
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)
UnsupportedOperationException
- if the JNI implementation
does not support mapping of a direct bufferpublic String datName() throws HDSException
HDSObject
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public int datNcomp() throws HDSException
HDSObject
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datNew(String name, String type, long[] dims) throws HDSException
name
- the name of the new component.type
- the type of the new component - if it matches one of the
primitive types a primitive is created, otherwise it
is assumed to be a structuredims
- component dimensions
HDSException
- if an HDS error occurs (STATUS is not SAI__OK) -
in particular if the named componene already
exists in this HDSObjectpublic HDSObject datParen() throws HDSException
HDSException
- if an HDS error occurs (STATUS is not SAI__OK) -
in particular if the object has no parent
because it is at the top level in an HDS
container file.public boolean datPrmry() throws HDSException
datPrmry
method
to handle the distinct get/set semantics of the underlying routine.
true
if the locator of this HDSObject
is primary, false
if it is secondary
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPrmry(boolean primary) throws HDSException
datPrmry
method
to handle the distinct get/set semantics of the underlying routine.
primary
- true
to set the locator of this
HDSObject
to primary, or
false
to set it to secondary
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPut0c(String value) throws HDSException
value
- the value to be written
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPut0l(boolean value) throws HDSException
value
- the value to be written
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPut0i(int value) throws HDSException
value
- the value to be written
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPut0r(float value) throws HDSException
value
- the value to be written
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPut0d(double value) throws HDSException
value
- the value to be written
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPutvc(String[] value) throws HDSException
Integer.MAX_VALUE
elements.
value
- an array containing the values to be written.
Must contain enough elements to fill the entire object.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPutvl(boolean[] value) throws HDSException
Integer.MAX_VALUE
elements.
value
- an array containing the values to be written.
Must contain enough elements to fill the entire object.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPutvi(int[] value) throws HDSException
Integer.MAX_VALUE
elements.
value
- an array containing the values to be written.
Must contain enough elements to fill the entire object.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPutvr(float[] value) throws HDSException
Integer.MAX_VALUE
elements.
value
- an array containing the values to be written.
Must contain enough elements to fill the entire object.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datPutvd(double[] value) throws HDSException
Integer.MAX_VALUE
elements.
value
- an array containing the values to be written.
Must contain enough elements to fill the entire object.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public String datRef() throws HDSException
HDSException
public long[] datShape() throws HDSException
HDSObject
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public long datSize() throws HDSException
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public boolean datState() throws HDSException
HDSException
public boolean datStruc() throws HDSException
true
if this object is a structure,
otherwise false
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public boolean datThere(String name) throws HDSException
name
- the name of a component whose existence is
to be queried
true
if a component called
name
is
contained in this object, otherwise
false
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public String datType() throws HDSException
String
giving one of the
following HDS type strings:
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)public void datUnmap() throws HDSException
HDSException
public boolean datValid() throws HDSException
true
if this HDSobject
refers to a valid HDS object, false
otherwise. It should normally be true unless
the datAnnul
method has been
called on it.
HDSException
- if an HDS error occurs (STATUS is not SAI__OK)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |