HdxResourceType (Starlink-UK API)

java.lang.Object
- 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

Fields
Modifier and Type	Field and Description
`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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.

Class HdxResourceType

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

HDX_NAMESPACE

HDX

TITLE

NONE

Method Detail

newHdxResourceType

toString

xmlName

getHoistAttribute

setHoistAttribute

setConstructedClass

setConstructedClass

getConstructedClass

isValidHdx

isValid

setElementValidator

registerHdxResourceFactory

match

match

getAllTypes