uk.ac.starlink.hdx
Class HdxResourceType

java.lang.Object
  extended by uk.ac.starlink.hdx.HdxResourceType

public class HdxResourceType
extends Object

Encapsulates the types of data contained within the HDX namespace. Each of the instances of this class can be used as a type indicator, which additionally encapsulates the various properties that type has.

To add an extension class, which registers a new HdxResourceType, you must do two things:

  1. Define a class which registers the new type, through a call to newHdxResourceType(java.lang.String), in a static initialiser.
  2. If the new class is called my.new.type, and if there is an `Hdx property' HdxResourceType.load.my.new.type with the value true (or anything which the Boolean class evaluates to true), then the specified class is loaded during initialization of this HdxResourceType class. This is an `Hdx property', which means that it may be specified as either a System property, or in an Hdx property file as described in HdxProperties.

Alternatively, you may register the type by explicitly loading and initialising the class (and thus executing its static initialiser). This can happen as a result of a call to some static method in the class, or explicitly via java.lang.Class.forName.

The structure of the elements within the HDX namespace is as follows: XXX ADD STRUCTURE DEFINITION -- WHAT FORMAT?

There is no DTD which corresponds to this document structure. The method which checks this is isValidHdx(Document), which is equivalent to a call to isValid(Element) on object HDX.

Version:
$Id$
Author:
Norman Gray (norman@astro.gla.ac.uk)

Field Summary
static HdxResourceType HDX
          The overall container of HDX objects
static String HDX_NAMESPACE
          The namespace for HDX
static HdxResourceType NONE
          Not a HDX-registered object, used as error/unknown type.
static HdxResourceType TITLE
          A generic type for titles of HDX objects
 
Method Summary
static Iterator getAllTypes()
          Obtains an iterator containing all the HdxResourceType types which are defined.
 Class getConstructedClass()
          Obtains the expected Java type corresponding to this Hdx type.
 String getHoistAttribute()
          Retrieves the value of the `hoist' attribute.
 boolean isValid(Element el)
          Tests whether the given element is a valid instance of this type.
static boolean isValidHdx(Document doc)
          Checks that the Document is valid HDX.
static HdxResourceType match(Element el)
          Returns a HdxResourceType object which matches the specified Element.
static HdxResourceType match(String gi)
          Returns a HdxResourceType object which matches the specified element name.
static HdxResourceType newHdxResourceType(String name)
          Creates and returns a new resource type.
 void registerHdxResourceFactory(HdxResourceFactory factory)
          Registers a handler for this type.
 void setConstructedClass(Class c)
          Sets the class or interface which constructed objects of this type must be assignable to.
 void setConstructedClass(String classname)
          Sets the class of interface which constructed objects of this type must be assignable to.
 void setElementValidator(ElementValidator validator)
          Registers an instance of the ElementValidator type, which will do the work of validating this type of resource.
 void setHoistAttribute(String s)
          Defines the `hoist' attribute.
 String toString()
          Returns a printable version of the resource type
 String xmlName()
          Gives the XML element name corresponding to the resource type.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

HDX_NAMESPACE

public static final String HDX_NAMESPACE
The namespace for HDX

See Also:
Constant Field Values

HDX

public static HdxResourceType HDX
The overall container of HDX objects


TITLE

public static HdxResourceType TITLE
A generic type for titles of HDX objects


NONE

public static HdxResourceType NONE
Not a HDX-registered object, used as error/unknown type.

Method Detail

newHdxResourceType

public static HdxResourceType newHdxResourceType(String name)
Creates and returns a new resource type.

Parameters:
name - The name of the new resource type, which will also become its XML element name. It is an error for this resource type to already exist.
Returns:
a new resource object, or null if a type with that name already exists.

toString

public String toString()
Returns a printable version of the resource type

Overrides:
toString in class Object

xmlName

public String xmlName()
Gives the XML element name corresponding to the resource type.


getHoistAttribute

public String getHoistAttribute()
Retrieves the value of the `hoist' attribute.

Returns:
the String value of the hoist attribute, or null if none has been defined.
See Also:
setHoistAttribute(java.lang.String)

setHoistAttribute

public void setHoistAttribute(String s)
Defines the `hoist' attribute. This is an attribute which is defaulted from the element content when it is read in.

For example if the <mytype> type has a hoist attribute of value, then the XML <mytype> something </mytype> is deemed equivalent to <mytype value="something"/>. This is never put in element content when objects are written to XML, but is only used when objects are constructed from `foreign' DOMs. If this is null, no attribute is defaulted.


setConstructedClass

public void setConstructedClass(Class c)
Sets the class or interface which constructed objects of this type must be assignable to.

Parameters:
c - a class which constructed objects must match. This may be null to turn off such verification, but that is probably a bad idea.
See Also:
setConstructedClass(String)

setConstructedClass

public void setConstructedClass(String classname)
                         throws HdxException
Sets the class of interface which constructed objects of this type must be assignable to.

Parameters:
classname - the name of a class which constructed objects must match. This may be null to turn off such verification, but that is probably a bad idea.
Throws:
HdxException - if the specified class cannot be found
See Also:
setConstructedClass(Class)

getConstructedClass

public Class getConstructedClass()
Obtains the expected Java type corresponding to this Hdx type.

If no such type has been registered, this returns the class object for the Object class, Object.class. You may compare the result of this method for equality with Object.class to determine if a type was registered, or use it directly, since Object.class.isInstance(obj) is true for any Java object.

Returns:
the Class object registered with setConstructedClass(java.lang.Class), or Object.class if no type was so registered

isValidHdx

public static boolean isValidHdx(Document doc)
Checks that the Document is valid HDX.

This allows the following assertions for the Document doc, and any node n immediately contained within it

 assert doc.getDocumentElement().getTagName
    .equals(HdxResourceType.HDX.xmlName());
 assert n.getNodeType() == Node.ELEMENT_NODE; // only text nodes
 assert HdxResourceType.match(n) != HdxResourceType.NONE; // all registered
 
There are other constraints which you might want to check: if they are violated, you might want to throw an exception, but until they are checked in this method, and the appropriate assertion listed above, they should not be checked in assert statements.

Returns:
true if the document does represent a valid HDX DOM
See Also:
isValid(Element)

isValid

public boolean isValid(Element el)
Tests whether the given element is a valid instance of this type. The actual validation work is performed by the ElementValidator instance registered with method setElementValidator(uk.ac.starlink.hdx.ElementValidator).

Parameters:
el - an element to be validated.
Returns:
true if the element is a valid instance of this type; if the type has no validator, then return true always.

setElementValidator

public void setElementValidator(ElementValidator validator)
Registers an instance of the ElementValidator type, which will do the work of validating this type of resource.


registerHdxResourceFactory

public void registerHdxResourceFactory(HdxResourceFactory factory)
Registers a handler for this type. New handlers are added at the front of the list.


match

public static HdxResourceType match(Element el)
Returns a HdxResourceType object which matches the specified Element.

This matches only elements which are in no namespace. That is, if the given element is in any namespace, including the HDX namespace, this does not match it.

Returns:
one of the static resource type constants, or a `type' NONE if the string does not match anything.
See Also:
match(String)

match

public static HdxResourceType match(String gi)
Returns a HdxResourceType object which matches the specified element name.

Parameters:
gi - an element name. This may be null, in which case this `matches' type NONE.
Returns:
one of the static resource type constants, or a `type' NONE if the string does not match anything.

getAllTypes

public static Iterator getAllTypes()
Obtains an iterator containing all the HdxResourceType types which are defined. The list does not include type NONE, and is in an arbitrary order.



Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.