Class VOElementFactory
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.
- Author:
- Mark Taylor (Starlink)
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic boolean
Determines whether the default strictness state is true or false when theSTRICT_PROPERTY
property has not been set.static final String
Property which determines the default strictness state. -
Constructor Summary
ConstructorsConstructorDescriptionConstructs a new VOElementFactory with the default storage policy.VOElementFactory
(uk.ac.starlink.table.StoragePolicy policy) Constructs a new VOElementFactory with a given storage policy. -
Method Summary
Modifier and TypeMethodDescriptionuk.ac.starlink.table.StoragePolicy
Returns the storage policy currently in effect.boolean
isStrict()
Indicates whether a strict reading of the VOTable standard is in effect.static boolean
Indicates whether strict interpretation of the VOTable standard is on by default (if it has not been set explicitly).makeVOElement
(File file) Builds a custom DOM read from a file and returns a new VOElement based on its top-level element.makeVOElement
(InputStream strm, String systemId) Builds a custom DOM from an input stream and returns a new VOElement based on its top-level element.makeVOElement
(String uri) Builds a custom DOM read from a URI and returns a new VOElement based on its top-level element.makeVOElement
(URL url) Builds a custom DOM read from a URL and returns a new VOElement based on its top-level element.makeVOElement
(DOMSource dsrc) Returns a VOElement based on a DOM source.makeVOElement
(Source xsrc) Returns a VOElement based on an XML Source.makeVOElement
(Document doc, String systemId) Returns a new VOElement based on a DOM Document node.makeVOElement
(Element el, String systemId) Returns a VOElement based on a given DOM element.makeVOElement
(uk.ac.starlink.util.DataSource datsrc) Builds a custom DOM read from a DataSource and returns a new VOElement based on its top-level element.void
setStoragePolicy
(uk.ac.starlink.table.StoragePolicy policy) Sets the storage policy.void
setStrict
(boolean strict) Determines whether a strict reading of the VOTable standard will be enforced.transformToDOM
(Source xsrc, boolean validate) Gets a custom DOMSource from a generic XML Source.
-
Field Details
-
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 ofSTRICT_DEFAULT
. The return value of theisStrict()
method will be set like this unless strictness is set explicitly.- See Also:
-
STRICT_DEFAULT
public static boolean STRICT_DEFAULTDetermines whether the default strictness state is true or false when theSTRICT_PROPERTY
property has not been set. True by default.
-
-
Constructor Details
-
VOElementFactory
public VOElementFactory(uk.ac.starlink.table.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:
-
-
Method Details
-
getStoragePolicy
public uk.ac.starlink.table.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(uk.ac.starlink.table.StoragePolicy policy) Sets the storage policy. This determines how row data found in the DOM will be stored.- Parameters:
policy
- new storage policy
-
makeVOElement
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). Ifel
is already a VOElement, it is just returned.- Parameters:
el
- DOM element on which the new object will be basedsystemId
- the location of the document
-
makeVOElement
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 nodesystemId
- the location of the document- Returns:
- VOElement based on
doc
-
makeVOElement
Returns a VOElement based on a DOM source.- Parameters:
dsrc
- DOM source representing an Element or Document node- Returns:
- VOElement based on
dsrc
-
makeVOElement
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:
SAXException
- ifxsrc
is not a DOM source and there is a parse error transforming it to a DOMIOException
- ifxsrc
is not a DOM source and there is an I/O error transforming to a DOM
-
makeVOElement
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 datasystemId
- the location of the document- Returns:
- new VOElement
- Throws:
SAXException
IOException
-
makeVOElement
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:
SAXException
IOException
-
makeVOElement
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:
SAXException
IOException
-
makeVOElement
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:
SAXException
IOException
-
makeVOElement
public VOElement makeVOElement(uk.ac.starlink.util.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
- Throws:
SAXException
IOException
-
transformToDOM
Gets a custom DOMSource from a generic XML Source. All elements in the returned DOM will be instances ofVOElement
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 sourcevalidate
- whether to use a validating parser if the transformation needs to be done (that is, ifxsrc
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:
SAXException
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
orPARAM
element with adatatype
attribute of "char
" or "unicodeChar
" but noarraysize
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:
- A
-
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 ofisStrictByDefault()
.- Returns:
- true if the VOTable standard is being interpreted strictly
- See Also:
-
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 namedSTRICT_PROPERTY
, or ofSTRICT_DEFAULT
if that is not set.- Returns:
- whether VOTable strict interpretation is on by default
- See Also:
-