uk.ac.starlink.votable

## Class VOElementFactory

- java.lang.Object
- - uk.ac.starlink.votable.VOElementFactory

-     public class VOElementFactory
      extends java.lang.Object

  Provides methods for constructing VOElements from a variety of sources. A VOElement can be made either from an existing DOM `Element` or from some non-DOM source such as a file, input stream, or SAX stream. In the latter case a DOM is built using the `transformToDOM(javax.xml.transform.Source,boolean)` method with no validation. There are several optimisations performed by this method which distinguish it from a DOM that you'd get if you constructed it directly; the most important ones are that the data-bearing parts (children of STREAM or TABLEDATA elements) of the XML document are not included in the built DOM, and that any reference to the VOTable DTD is resolved locally rather than making a potential network connection. You almost certainly don't need to worry about this; however if for some reason you want to work on a 'normal' DOM, or if you want validation, you can construct the DOM yourself and invoke one of the non-transforming `makeVOElement` methods on the result.

  The various `makeVOElement` methods may return an object of class `VOElement` or of one of its subclasses, according to the name of the element in question; specific subclasses are provided only where some extra functionality is available, for instance the `TableElement.getData()` method of the `TableElement` class. One upshot of this is that a tree of VOElements need not conform to the VOTable DTD, elements of any name may be in it. Wherever an element has a name which matches an element with specific significance in a VOTable document however, such as "TABLE", it is handled accordingly.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `STRICT_DEFAULT` Determines whether the default strictness state is true or false when the `STRICT_PROPERTY` property has not been set.
    `static java.lang.String` | `STRICT_PROPERTY` Property which determines the default strictness state.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `VOElementFactory()` Constructs a new VOElementFactory with the default storage policy.
    `VOElementFactory(StoragePolicy policy)` Constructs a new VOElementFactory with a given storage policy.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `StoragePolicy` | `getStoragePolicy()` Returns the storage policy currently in effect.
    `boolean` | `isStrict()` Indicates whether a strict reading of the VOTable standard is in effect.
    `static boolean` | `isStrictByDefault()` Indicates whether strict interpretation of the VOTable standard is on by default (if it has not been set explicitly).
    `VOElement` | `makeVOElement(DataSource datsrc)` Builds a custom DOM read from a DataSource and returns a new VOElement based on its top-level element.
    `VOElement` | `makeVOElement(org.w3c.dom.Document doc, java.lang.String systemId)` Returns a new VOElement based on a DOM Document node.
    `VOElement` | `makeVOElement(javax.xml.transform.dom.DOMSource dsrc)` Returns a VOElement based on a DOM source.
    `VOElement` | `makeVOElement(org.w3c.dom.Element el, java.lang.String systemId)` Returns a VOElement based on a given DOM element.
    `VOElement` | `makeVOElement(java.io.File file)` Builds a custom DOM read from a file and returns a new VOElement based on its top-level element.
    `VOElement` | `makeVOElement(java.io.InputStream strm, java.lang.String systemId)` Builds a custom DOM from an input stream and returns a new VOElement based on its top-level element.
    `VOElement` | `makeVOElement(javax.xml.transform.Source xsrc)` Returns a VOElement based on an XML Source.
    `VOElement` | `makeVOElement(java.lang.String uri)` Builds a custom DOM read from a URI and returns a new VOElement based on its top-level element.
    `VOElement` | `makeVOElement(java.net.URL url)` Builds a custom DOM read from a URL and returns a new VOElement based on its top-level element.
    `void` | `setStoragePolicy(StoragePolicy policy)` Sets the storage policy.
    `void` | `setStrict(boolean strict)` Determines whether a strict reading of the VOTable standard will be enforced.
    `javax.xml.transform.dom.DOMSource` | `transformToDOM(javax.xml.transform.Source xsrc, boolean validate)` Gets a custom DOMSource from a generic XML Source.

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

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

- - ### Field Detail

    - #### STRICT_PROPERTY

          public static final java.lang.String STRICT_PROPERTY

      Property which determines the default strictness state. Its value may be set to "true" or "false" case-insensitively. If unset, the default will be determined by the value of `STRICT_DEFAULT`. The return value of the `isStrict()` method will be set like this unless strictness is set explicitly.
      See Also:
        `setStrict(boolean)`, Constant Field Values

    - #### STRICT_DEFAULT

          public static boolean STRICT_DEFAULT

      Determines whether the default strictness state is true or false when the `STRICT_PROPERTY` property has not been set. True by default.

  - ### Constructor Detail

    - #### VOElementFactory

          public VOElementFactory(StoragePolicy policy)

      Constructs a new VOElementFactory with a given storage policy. The StoragePolicy object is used to determine how row data which is found within the DOM will be cached.
      Parameters:
        `policy` - storage policy

    - #### VOElementFactory

          public VOElementFactory()

      Constructs a new VOElementFactory with the default storage policy.
      See Also:
        `StoragePolicy.getDefaultPolicy()`

  - ### Method Detail

    - #### getStoragePolicy

          public StoragePolicy getStoragePolicy()

      Returns the storage policy currently in effect. This is used to determine how row data found in the DOM will be stored.
      Returns:
        current storage policy

    - #### setStoragePolicy

          public void setStoragePolicy(StoragePolicy policy)

      Sets the storage policy. This determines how row data found in the DOM will be stored.
      Parameters:
        `policy` - new storage policy

    - #### makeVOElement

          public VOElement makeVOElement(org.w3c.dom.Element el,
                                         java.lang.String systemId)

      Returns a VOElement based on a given 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). If `el` is already a VOElement, it is just returned.
      Parameters:
        `el` - DOM element on which the new object will be based
        `systemId` - the location of the document

    - #### makeVOElement

          public VOElement makeVOElement(org.w3c.dom.Document doc,
                                         java.lang.String systemId)

      Returns a new VOElement based on a DOM Document node. 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).
      Parameters:
        `doc` - DOM document node
        `systemId` - the location of the document
      Returns:
        VOElement based on `doc`

    - #### makeVOElement

          public VOElement makeVOElement(javax.xml.transform.dom.DOMSource dsrc)

      Returns a VOElement based on a DOM source.
      Parameters:
        `dsrc` - DOM source representing an Element or Document node
      Returns:
        VOElement based on `dsrc`

    - #### makeVOElement

          public VOElement makeVOElement(javax.xml.transform.Source xsrc)
                                  throws org.xml.sax.SAXException,
                                         java.io.IOException

      Returns a VOElement based on an XML Source. If the source is a SAX or Stream source, this will involve a parse.
      Parameters:
        `xsrc` - the XML source representing the element
      Returns:
        VOElement based on `xsrc`
      Throws:
        `org.xml.sax.SAXException` - if `xsrc` is not a DOM source and there is a parse error transforming it to a DOM
        `java.io.IOException` - if `xsrc` is not a DOM source and there is an I/O error transforming to a DOM

    - #### makeVOElement

          public VOElement makeVOElement(java.io.InputStream strm,
                                         java.lang.String systemId)
                                  throws org.xml.sax.SAXException,
                                         java.io.IOException

      Builds a custom DOM from an input stream and returns a new VOElement based on its top-level 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).
      Parameters:
        `strm` - stream containing XML data
        `systemId` - the location of the document
      Returns:
        new VOElement
      Throws:
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### makeVOElement

          public VOElement makeVOElement(java.lang.String uri)
                                  throws org.xml.sax.SAXException,
                                         java.io.IOException

      Builds a custom DOM read from a URI and returns a new VOElement based on its top-level element.
      Parameters:
        `uri` - location of the document
      Returns:
        new VOElement
      Throws:
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### makeVOElement

          public VOElement makeVOElement(java.net.URL url)
                                  throws org.xml.sax.SAXException,
                                         java.io.IOException

      Builds a custom DOM read from a URL and returns a new VOElement based on its top-level element.
      Parameters:
        `url` - location of the document
      Returns:
        new VOElement
      Throws:
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### makeVOElement

          public VOElement makeVOElement(java.io.File file)
                                  throws org.xml.sax.SAXException,
                                         java.io.IOException

      Builds a custom DOM read from a file and returns a new VOElement based on its top-level element.
      Parameters:
        `file` - file containing XML document
      Returns:
        new VOElement
      Throws:
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### makeVOElement

          public VOElement makeVOElement(DataSource datsrc)
                                  throws org.xml.sax.SAXException,
                                         java.io.IOException

      Builds a custom DOM read from a DataSource and returns a new VOElement based on its top-level element.
      Parameters:
        `datsrc` - data source containing XML
      Returns:
        new VOElement
      Throws:
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### transformToDOM

          public javax.xml.transform.dom.DOMSource transformToDOM(javax.xml.transform.Source xsrc,
                                                                  boolean validate)
                                                           throws org.xml.sax.SAXException,
                                                                  java.io.IOException

      Gets a custom DOMSource from a generic XML Source. All elements in the returned DOM will be instances of `VOElement` or one of its specialist subclasses.

      The clever bit is that during the parse (if `xsrc` is not already a DOMSource) it intercepts SAX events which indicate the start and end of any DATA events it finds so that they are not incorporated as part of the DOM. Such elements it parses directly on the basis of what it knows about items that crop up in VOTables. This keeps the resulting DOM to a reasonable size.

      Parameters:
        `xsrc` - input XML source
        `validate` - whether to use a validating parser if the transformation needs to be done (that is, if `xsrc` is not already a DOMSource)
      Returns:
        a DOMSource representing the XML document held by `xsrc` The DOMSource's node will be either a VOElement or a VODocument
      Throws:
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### setStrict

          public void setStrict(boolean strict)

      Determines whether a strict reading of the VOTable standard will be enforced. Currently if strict is set to false the following standard-violating assumptions will be made:
      - A `FIELD` or `PARAM` element with a `datatype` attribute of "`char`" or "`unicodeChar`" but no `arraysize` attribute will be assumed to represent a character array (`arraysize="*"`) rather than a single-character value.
      Parameters:
        `strict` - true iff you want a strict reading of the VOTable standard
      See Also:
        `isStrict()`, `STRICT_PROPERTY`

    - #### isStrict

          public boolean isStrict()

      Indicates whether a strict reading of the VOTable standard is in effect. If it has not been set explicitly, this will return the result of `isStrictByDefault()`.
      Returns:
        true if the VOTable standard is being interpreted strictly
      See Also:
        `setStrict(boolean)`

    - #### isStrictByDefault

          public static boolean isStrictByDefault()

      Indicates whether strict interpretation of the VOTable standard is on by default (if it has not been set explicitly). The return value will be the value of the system property named `STRICT_PROPERTY`, or of `STRICT_DEFAULT` if that is not set.
      Returns:
        whether VOTable strict interpretation is on by default
      See Also:
        `setStrict(boolean)`