uk.ac.starlink.votable

## Class VOElement

- java.lang.Object
- - uk.ac.starlink.votable.dom.DelegatingNode
  - - uk.ac.starlink.votable.dom.DelegatingElement
    - - uk.ac.starlink.votable.VOElement

- All Implemented Interfaces:
    org.w3c.dom.Element, org.w3c.dom.Node
  Direct Known Subclasses:
    FieldElement, FieldRefElement, GroupElement, LinkElement, ParamRefElement, TableElement, TimesysElement, ValuesElement

      public class VOElement
      extends DelegatingElement

  Element implementation for use within VOTable documents. This implements the DOM Element interface, and so can be used just as a normal DOM element (including adding/removing/editing nodes). However, it also provides a few extra convenience methods, some of which are based on knowledge of the nature of the elements within a VOTable document.

  This class is extended to provide the classes associated with specific VOTable elements. These in turn provide more additional methods associated with the specific properties of such elements, for instance the `TableElement` class has a `getData` which returns the actual table cell data. Those element types which don't require any extra associated functionality (such as RESOURCE) don't have their own subclass, they are just represented as `VOElement`s. The class of each element in the DOM is determined by its tag name - so every TABLE element will be represented in the DOM as a `TableElement` and so on.

- - ### Field Summary

    - ### Fields inherited from interface org.w3c.dom.Node

      `ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `VOElement` | `getChildByName(java.lang.String votagname)` Returns the first child element of this element which has a given name in the VOTable namespace.
    `VOElement[]` | `getChildren()` Returns the child elements of this element.
    `VOElement[]` | `getChildrenByName(java.lang.String votagname)` Returns all the child elements of this element which have a given name in the VOTable namespace.
    `java.lang.String` | `getDescription()` Returns the text of a DESCRIPTION element associated with this object, or `null` if none exists.
    `org.w3c.dom.NodeList` | `getElementsByVOTagName(java.lang.String voTagName)` Returns a NodeList of all descendant Elements with a given unqualified tag name in the VOTable namespace, in the order in which they are encountered in a preorder traversal of this Element tree.
    `int` | `getElementSequence()` Returns the number of elements with the same tag name as this one which were present in the document when this one was added to it.
    `java.lang.String` | `getHandle()` Returns something that can be used informally as a name for this element.
    `java.lang.String` | `getID()` Returns the `ID` attribute value for this element, or `null` if none exists.
    `java.lang.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.
    `VOElement` | `getReferencedElement(java.lang.String refAtt, java.lang.String votagname)` Returns an element from the same document whose ID-typed attribute matches the value of a given (reference) attribute of this element.
    `java.lang.String` | `getSystemId()` Returns any system ID associated with this node.
    `java.lang.String` | `getVOTagName()` Returns the name of this element in the VOTable namespace.
    `java.lang.String` | `toString()` Returns the same value as `getHandle()`.

    - ### Methods inherited from class uk.ac.starlink.votable.dom.DelegatingElement

      `getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS`

    - ### Methods inherited from class uk.ac.starlink.votable.dom.DelegatingNode

      `appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.w3c.dom.Node

      `appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData`

- - ### Method Detail

    - #### getDescription

          public java.lang.String getDescription()

      Returns the text of a DESCRIPTION element associated with this object, or `null` if none exists. The return value is a plain text string - any XML tags (XHTML is allowed in the VOTable1.1 DESCRIPTION content model) are stripped out. If you want the full XML structure of the DESCRIPTION tag, use instead `getChildByName("DESCRIPTION")`.
      Returns:
        the description

    - #### getID

          public java.lang.String getID()

      Returns the `ID` attribute value for this element, or `null` if none exists.
      Returns:
        the ID

    - #### getName

          public java.lang.String getName()

      Returns the `name` attribute value for this element, or `null` if none exists.
      Returns:
        the name

    - #### 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.
      Returns:
        parent VOElement

    - #### getChildren

          public VOElement[] getChildren()

      Returns the child elements of this element. Each is returned as an instance of VOElement or one of its specific subclasses.
      Returns:
        an array of VOElement children of this one

    - #### getChildrenByName

          public VOElement[] getChildrenByName(java.lang.String votagname)

      Returns all the child elements of this element which have a given name in the VOTable namespace. Each is returned as a VOElement or the appropriate specific VOElement subclass.

      Note that since STIL v2.8, but not before, the namespacing of the argument to this method is influenced by the default `Namespacing` class.

      Parameters:
        `votagname` - the unqualified element name in the VOTable namespace required (such as "TABLE")
      Returns:
        an array of VOElement children of this one, all with element name `tagname`

    - #### getChildByName

          public VOElement getChildByName(java.lang.String votagname)

      Returns the first child element of this element which has a given name in the VOTable namespace. 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.

      Note that since STIL v2.8, but not before, the namespacing of the argument to this method is influenced by the default `Namespacing` class.

      Parameters:
        `votagname` - the unqualified element name in the VOTable namespace required (such as "TABLE")
      Returns:
        the first child of this one with element name `tagname`

    - #### toString

          public java.lang.String toString()

      Returns the same value as `getHandle()`.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of this object

    - #### getHandle

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

    - #### getSystemId

          public java.lang.String getSystemId()

      Returns any system ID associated with this node. It is the system ID (basically, a relative or absolute location) of the owner document.
      Returns:
        system ID

    - #### getVOTagName

          public java.lang.String getVOTagName()

      Returns the name of this element in the VOTable namespace.
      Returns:
        unqualified VOTable element name for this element, such as "TABLE"

    - #### getElementSequence

          public int getElementSequence()

      Returns the number of elements with the same tag name as this one which were present in the document when this one was added to it.
      Returns:
        sequence number of this element among similarly named ones

    - #### getReferencedElement

          public VOElement getReferencedElement(java.lang.String refAtt,
                                                java.lang.String votagname)

      Returns an element from the same document whose ID-typed attribute matches the value of a given (reference) attribute of this element. The result is constrained to have a particular tag name; if no such element exists, null is returned.
      Parameters:
        `refAtt` - name of referencing attribute of this element
        `votagname` - the unqualified element name in the VOTable namespace required (such as "TABLE")
      Returns:
        element with required tag name, or null

    - #### getElementsByVOTagName

          public org.w3c.dom.NodeList getElementsByVOTagName(java.lang.String voTagName)

      Returns a NodeList of all descendant Elements with a given unqualified tag name in the VOTable namespace, in the order in which they are encountered in a preorder traversal of this Element tree. This does the same as `Element.getElementsByTagName(java.lang.String)`, but takes care of VOTable namespacing issues; calling it with the argument "TABLE" will find all VOTable TABLE descendants.
      Parameters:
        `voTagName` - unqualified element name in VOTable namespace
      Returns:
        list of matching element nodes