uk.ac.starlink.votable
Class VOElementFactory

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

public class VOElementFactory
extends Object

Provides static 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.


Constructor Summary
VOElementFactory()
           
 
Method Summary
static VOElement makeVOElement(DataSource datsrc)
          Builds a custom DOM read from a DataSource and returns a new VOElement based on its top-level element.
static VOElement makeVOElement(Document doc, String systemId)
          Returns a new VOElement based on a DOM Document node.
static VOElement makeVOElement(DOMSource dsrc)
          Returns a new VOElement based on a DOM source.
static VOElement makeVOElement(Element el, String systemId)
          Returns a new VOElement based on a given DOM element.
static VOElement makeVOElement(File file)
          Builds a custom DOM read from a file and returns a new VOElement based on its top-level element.
static VOElement makeVOElement(InputStream strm, String systemId)
          Builds a custom DOM from an input stream and returns a new VOElement based on its top-level element.
static VOElement makeVOElement(Source xsrc)
          Returns a new VOElement based on an XML Source.
static VOElement makeVOElement(String uri)
          Builds a custom DOM read from a URI and returns a new VOElement based on its top-level element.
static VOElement makeVOElement(URL url)
          Builds a custom DOM read from a URL and returns a new VOElement based on its top-level element.
static DOMSource transformToDOM(Source xsrc, boolean validate)
          Gets a DOMSource from a generic XML Source.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

VOElementFactory

public VOElementFactory()
Method Detail

makeVOElement

public static VOElement makeVOElement(Element el,
                                      String systemId)
Returns a new 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).

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

makeVOElement

public static VOElement makeVOElement(DOMSource dsrc)
Returns a new VOElement based on a DOM source.

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

makeVOElement

public static VOElement makeVOElement(Source xsrc)
                               throws SAXException,
                                      IOException
Returns a new VOElement based on an XML Source. If xsrc is not a DOMSource, it will be transformed to a DOM using transformToDOM first.

Parameters:
xsrc - the XML source representing the element
Returns:
VOElement based on xsrc
Throws:
SAXException - if xsrc is not a DOM source and there is a parse error transforming it to a DOM
IOException - if xsrc is not a DOM source and there is an I/O error transforming to a DOM

makeVOElement

public static VOElement makeVOElement(Document doc,
                                      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 static VOElement makeVOElement(InputStream strm,
                                      String systemId)
                               throws SAXException,
                                      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
SAXException
IOException

makeVOElement

public static VOElement makeVOElement(String uri)
                               throws SAXException,
                                      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
SAXException
IOException

makeVOElement

public static VOElement makeVOElement(URL url)
                               throws SAXException,
                                      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
SAXException
IOException

makeVOElement

public static VOElement makeVOElement(File file)
                               throws SAXException,
                                      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
SAXException
IOException

makeVOElement

public static VOElement makeVOElement(DataSource datsrc)
                               throws SAXException,
                                      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
SAXException
IOException

transformToDOM

public static DOMSource transformToDOM(Source xsrc,
                                       boolean validate)
                                throws SAXException,
                                       IOException
Gets a DOMSource from a generic XML Source. If the source is already a DOMSource, there's nothing to do. If it represents a stream however, it parses it to produce a DOM, and wraps that up as a Source. The clever bit is that it intercepts SAX events indicating the start and end of any DATA elements 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
SAXException
IOException

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