uk.ac.starlink.votable
Class VOElement

java.lang.Object
  |
  +--uk.ac.starlink.votable.VOElement
Direct Known Subclasses:
FieldElement, LinkElement, TableElement, ValuesElement

public class VOElement
extends Object

Generic element in a VOTable document. This class is extended to provide the classes associated with specific VOTable elements. It provides handling for some of the characteristics common to various VOTable elements, for instance DESCRIPTION elements.

This element and its subclasses provide some methods for returning the values of specific attributes from the element in question, such as getName, getID. This is either for convenience or in order to return some non-String object from these attributes. For attribute values which are not covered by specific methods in this way, the getAttribute(java.lang.String) method can be used.

The recommended way of navigating round a VOTable document tree is by using the getChild* and getParent methods which return other VOElement objects. If you like doing things the hard way however, you can access the DOM Element underlying each VOElement and navigate round the underlying DOM structure itself, creating a new VOElement when you get to the node you're after so you can use the methods provided by VOElement (such as TableElement's TableElement.getData() method).

You should in general get instances of VOElement using the VOElementFactory class.

Note: An alternative implementation would have VOElement implement the Element interface itself. There are a couple of reasons this would be a bit problematic, but is probably doable. If anyone can persuade me it's a useful thing to do, I might go ahead).


Constructor Summary
  VOElement(Element el, String systemId)
          Constructs a VOElement from a DOM element.
protected VOElement(Element el, String systemId, String tagname)
          Constructs a VOElement from a DOM element which is required to have a given tagname.
 
Method Summary
 boolean equals(Object other)
          Indicates whether this VOElement is equivalent to another.
 String getAttribute(String attname)
          Returns the value of a named attribute for this element, or null if there is no such attribute.
 String getAttribute(String attname, String implied)
          Returns the value of a named attribute for this element, or a default ('#IMPLIED') value if the attribute is not present.
 VOElement getChildByName(String tagname)
          Returns the first child element of this element which has a given name.
 VOElement[] getChildren()
          Returns the child elements of this element.
 VOElement[] getChildrenByName(String tagname)
          Returns all the child elements of this element which have a given name.
 URL getContext()
          Returns the base URL associated with this VOElement.
 VOElement[] getDescendantsByName(String tagname)
          Returns all the descendants of this element which have a given name.
 String getDescription()
          Returns the text of a DESCRIPTION element associated with this object, or null if none exists.
 Element getElement()
          Returns the DOM element on which this VOElement object is based.
 String getHandle()
          Returns something that can be used informally as a name for this element.
 String getID()
          Returns the ID attribute value for this element, or null if none exists.
 String getName()
          Returns the name attribute value for this element, or null if none exists.
 VOElement getParent()
          Returns the parent element of this element as a VOElement.
 Source getSource()
          Returns an XML Source corresponding to this element.
 String getSystemId()
          Returns the system identifier against which relative URIs should be resolved.
 String getTagName()
          Returns the tagname of the Element on which this object is based, that is the element's name, like "RESOURCE" or "FIELD".
 String getTextContent()
          Returns the text contained in this element.
 boolean hasAttribute(String attname)
          Indicates whether this element has a value for a given attribute.
 int hashCode()
          Returns the hash code of the DOM Element.
 String toString()
          Returns the same value as getHandle().
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

VOElement

public VOElement(Element el,
                 String systemId)
Constructs a VOElement from a DOM element. The systemId is also required since some elements (STREAM, LINK) may need it for URL resolution. It may be null however (which is fine if there are no relative URLs used in the document). In general application code should use one of the static methods in VOElementFactory in preference to this constructor.

Parameters:
el - DOM element on which the new object will be based
systemId - the location of the document

VOElement

protected VOElement(Element el,
                    String systemId,
                    String tagname)
Constructs a VOElement from a DOM element which is required to have a given tagname.

Parameters:
el - DOM element on which the new object will be based
systemId - the location of the document
tagname - the name that el is required to have
Throws:
IllegalArgumentException - if el has a name other than tagname
Method Detail

getDescription

public String getDescription()
Returns the text of a DESCRIPTION element associated with this object, or null if none exists.

Returns:
the description

getID

public String getID()
Returns the ID attribute value for this element, or null if none exists.

Returns:
the ID

getName

public String getName()
Returns the name attribute value for this element, or null if none exists.

Returns:
the name

getAttribute

public String getAttribute(String attname)
Returns the value of a named attribute for this element, or null if there is no such attribute.

Parameters:
attname - the name of the attribute to retrieve
Returns:
the value of attribute attname

getAttribute

public String getAttribute(String attname,
                           String implied)
Returns the value of a named attribute for this element, or a default ('#IMPLIED') value if the attribute is not present.

Parameters:
attname - the name of the attribute to retrieve
implied - the default value
Returns:
the value of the attribute attname if present, or implied if not

hasAttribute

public boolean hasAttribute(String attname)
Indicates whether this element has a value for a given attribute.

Parameters:
attname - the name of an attribute
Returns:
true iff this element has an attribute called attname

getParent

public VOElement getParent()
Returns the parent element of this element as a VOElement. Note that the returned object is not guaranteed to be one of the elements in the VOTable DTD. If this element is at the root of the document, null will be returned.


getChildren

public VOElement[] getChildren()
Returns the child elements of this element. Each is returned as a VOElement or the appropriate specific VOElement subclass.

Returns:
an array of VOElement children of this one

getChildrenByName

public VOElement[] getChildrenByName(String tagname)
Returns all the child elements of this element which have a given name. Each is returned as a VOElement or the appropriate specific VOElement subclass.

Parameters:
tagname - the element name required
Returns:
an array of VOElement children of this one, all with element name tagname

getChildByName

public VOElement getChildByName(String tagname)
Returns the first child element of this element which has a given name. If there are more than one with the given name, later ones are ignored. If there are none, null is returned. The element is returned as a VOElement or the appropriate specific VOElement subclass.

Parameters:
tagname - the element name required
Returns:
the first child of this one with element name tagname

getDescendantsByName

public VOElement[] getDescendantsByName(String tagname)
Returns all the descendants of this element which have a given name. Each is returned as a VOElement or the appropriate specific VOElement subclass. They are returned in preorder traversal order.

Parameters:
tagname - the element name required
Returns:
an array of all the VOElement descendants (to any level) of this one which have the element name tagname

getTagName

public String getTagName()
Returns the tagname of the Element on which this object is based, that is the element's name, like "RESOURCE" or "FIELD".

Returns:
the element's name (note, not the value of the name attribute

getElement

public Element getElement()
Returns the DOM element on which this VOElement object is based.

Returns:
the DOM element

getSource

public Source getSource()
Returns an XML Source corresponding to this element.

Returns:
a source containing the XML content of this element

getSystemId

public String getSystemId()
Returns the system identifier against which relative URIs should be resolved.

Returns:
the system ID, or null

getContext

public URL getContext()
Returns the base URL associated with this VOElement. This will normally be the same for the entire VOTable, namely the URL of the VOTable document itself, and it will typically be got from the System ID supplied at VOTable creation time. Or, it may not be known at all, in which case null is returned.

Returns:
the base URL associated with this element

toString

public String toString()
Returns the same value as getHandle().

Overrides:
toString in class Object
Returns:
a string representation of this object

getHandle

public String getHandle()
Returns something that can be used informally as a name for this element. May be ID or something other than the value of the name attribute itself if no name exists.

Returns:
a label for this element

getTextContent

public String getTextContent()
Returns the text contained in this element. Any text elements are concatenated and other elements such as element structure is ignored. This method is only designed to be used on elements which have a CDATA content model, but it will return a usable result for others.

Returns:
the text content

equals

public boolean equals(Object other)
Indicates whether this VOElement is equivalent to another.

Overrides:
equals in class Object
Parameters:
other - comparison object
Returns:
true iff other is based on the same DOM Element as this is

hashCode

public int hashCode()
Returns the hash code of the DOM Element.

Overrides:
hashCode in class Object

Copyright © 2004 CLRC: Central Laboratory of the Research Councils. All rights reserved.