uk.ac.starlink.hds

Class HDSReference

java.lang.Object

uk.ac.starlink.hds.HDSReference

All Implemented Interfaces:

Cloneable

public class HDSReference
extends Object
implements Cloneable

Stores the location of an HDS object. This class can store information about where an HDSObject is stored, including the container file it lives in and its location within that (its HDS path). Objects in this class, which are not immutable, can be used to navigate up and down an HDS path in a stack-like fashion, but pushing new elements on to the end of the HDS path and popping them off.

It also deals with translating object location information to and from a URL. Other classes ought to use this class to translate between URLs and HDS paths so that the HDS URL format can be changed easily in a single place. The format of a URL representing an HDS location is currently of the form container.sdf#hdspath. This may get changed.

Author:

Mark Taylor (Starlink)

Constructor Summary

Constructors

Constructor and Description
HDSReference(File container) Constructs a new HDSReference representing the top level object in an HDS container file.
HDSReference(File container, String path) Constructs an HDSReference given a container file and an HDS path string within it.
HDSReference(File container, String[] path) Constructs an HDSReference given a container file and an HDS path array within it.
HDSReference(HDSObject hobj) Constructs an HDSReference from an existing HDSObject.
HDSReference(String path) Constructs an HDSRefernce from a 'traditional' HDS pathname.
HDSReference(URL url) Constructs an HDSReference from a URL.

Method Summary

Modifier and Type	Method and Description
Object	clone() Returns a copy of this object - modifying the returned object will not affect the original one.
File	getContainerFile() Returns the container file associated with this HDSReference (including the '.sdf' extension).
String	getContainerName() Returns the HDS-style name of the container file associated with this HDSReference - this does not include the '.sdf' extension.
HDSObject	getObject(String accessMode) Opens a new primary HDSObject at the location referenced by this HDSReference.
String[]	getPath() Returns the HDS path of this HDSReference as an array of Strings.
URL	getURL() Returns a URL which describes this HDSReference.
String	pop() Removes an element from the end of the current path, thus navigating up the HDS hierarchy.
void	push(String pathEl) Adds a new path element to the end of the current path, thus navigating down the HDS hierarchy.
String	toString()

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

HDSReference

public HDSReference(File container)

Constructs a new HDSReference representing the top level object in an HDS container file.

Parameters:

container - a File object giving the container file (including the .sdf extension)

Throws:

IllegalArgumentException - if the filename does not end '.sdf'

HDSReference

public HDSReference(File container,
                    String[] path)

Constructs an HDSReference given a container file and an HDS path array within it.

Parameters:

container - a File object giving the container file (including the .sdf extension)

path - an array of Strings each representing the name of one level of the HDS path

Throws:

IllegalArgumentException - if the filename does not end in ".sdf"

HDSReference

public HDSReference(File container,
                    String path)

Constructs an HDSReference given a container file and an HDS path string within it.

Parameters:

container - a File object giving the container file (including the .sdf extension)

path - a dot-separated string giving the HDS path

Throws:

IllegalArgumentException - if the filename does not end '.sdf'

HDSReference

public HDSReference(String path)

Constructs an HDSRefernce from a 'traditional' HDS pathname.

Parameters:

path - a dot-separated string in which the container name minus its '.sdf' forms the front and the HDS path proper forms the back

HDSReference

public HDSReference(URL url)

Constructs an HDSReference from a URL. Only URLs using the file: protocol are supported.

Parameters:

url - a URL describing the location of the HDSObject

Throws:

UnsupportedOperationException - if the protocol of url is not file

HDSReference

public HDSReference(HDSObject hobj)
             throws HDSException

Constructs an HDSReference from an existing HDSObject.

Parameters:

hobj - the object whose location is to be referenced.

Throws:

HDSException - if an HDS error occurs

Method Detail

getContainerFile

public File getContainerFile()

Returns the container file associated with this HDSReference (including the '.sdf' extension).

Returns:

the file

getContainerName

public String getContainerName()

Returns the HDS-style name of the container file associated with this HDSReference - this does not include the '.sdf' extension.

Returns:

container name

getPath

public String[] getPath()

Returns the HDS path of this HDSReference as an array of Strings.

Returns:

an array in which the first element is the name of the topmost part of the HDS path etc.

getURL

public URL getURL()

Returns a URL which describes this HDSReference.

Returns:

a URL

getObject

public HDSObject getObject(String accessMode)
                    throws HDSException

Opens a new primary HDSObject at the location referenced by this HDSReference.

Parameters:

accessMode - the HDS access mode for the hdsOpen call - "READ", "WRITE" or "UPDATE"

Throws:

HDSException

toString

public String toString()

Overrides:

toString in class Object

push

public void push(String pathEl)

Adds a new path element to the end of the current path, thus navigating down the HDS hierarchy.

Parameters:

pathEl - the new path element to add

pop

public String pop()

Removes an element from the end of the current path, thus navigating up the HDS hierarchy.

Returns:

the element which is removed

clone

public Object clone()

Returns a copy of this object - modifying the returned object will not affect the original one.

Overrides:

clone in class Object

Returns:

a clone of this HDSReference