uk.ac.starlink.ast

Class XmlChan

java.lang.Object

uk.ac.starlink.ast.AstObject

uk.ac.starlink.ast.Channel

uk.ac.starlink.ast.XmlChan

public class XmlChan
extends Channel

Java interface to the AST XmlChan class - I/O Channel using XML to represent Objects. A XmlChan is a specialised form of Channel which supports XML I/O operations. Writing an Object to an XmlChan (using astWrite) will, if the Object is suitable, generate an XML description of that Object, and reading from an XmlChan will create a new Object from its XML description.

Normally, when you use an XmlChan, you should provide "source" and "sink" functions which connect it to an external data store by reading and writing the resulting XML text. These functions should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such functions are supplied, a Channel will read from standard input and write to standard output.

Alternatively, an XmlChan can be told to read or write from specific text files using the SinkFile and SourceFile attributes, in which case no sink or source function need be supplied.

Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA

See Also:

AST XmlChan

Field Summary

Fields

Modifier and Type	Field and Description
static String	AST__XMLNS XML namespace for elements in AstObject serialization.

Fields inherited from class uk.ac.starlink.ast.AstObject

AST__BAD, AST__TUNULL, pointer

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XmlChan() This constructor does not do all the required construction to create a valid XmlChan object, but is required for inheritance by user subclasses of XmlChan.
	XmlChan(InputStream in, OutputStream out) Creates a channel which reads from the given InputStream and writes to the given OutputStream.

Method Summary

Modifier and Type	Method and Description
String	getXmlFormat() Get system for formatting Objects as XML.
boolean	getXmlIndent() Get XmlIndent attribute.
int	getXmlLength() Get controls output buffer length.
String	getXmlPrefix() Get the namespace prefix to use when writing.
void	setXmlFormat(String xmlFormat) Set system for formatting Objects as XML.
void	setXmlIndent(boolean xmlIndent) Set XmlIndent attribute.
void	setXmlLength(int xmlLength) Set controls output buffer length.
void	setXmlPrefix(String xmlPrefix) Set the namespace prefix to use when writing.

Methods inherited from class uk.ac.starlink.ast.Channel

copy, finalize, getComment, getFull, getReportLevel, getSkip, getStrict, read, setComment, setFull, setReportLevel, setSkip, setStrict, sink, source, warnings, write

Methods inherited from class uk.ac.starlink.ast.AstObject

annul, clear, delete, equals, getAstConstantI, getB, getC, getD, getF, getI, getID, getIdent, getL, getNobject, getObjSize, getRefCount, hashCode, isThreaded, reportVersions, sameObject, set, setB, setC, setD, setF, setI, setID, setIdent, setL, show, test, tune

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

AST__XMLNS

public static final String AST__XMLNS

XML namespace for elements in AstObject serialization.

Constructor Detail

XmlChan

public XmlChan(InputStream in,
               OutputStream out)

Creates a channel which reads from the given InputStream and writes to the given OutputStream.

Parameters:

in - a stream to read AST objects from. If null, then System.in is used.

out - a stream to write AST objects to. If null, then System.out is used.

XmlChan

protected XmlChan()

This constructor does not do all the required construction to create a valid XmlChan object, but is required for inheritance by user subclasses of XmlChan.

Method Detail

getXmlFormat

public String getXmlFormat()

Get system for formatting Objects as XML. This attribute specifies the formatting system to use when AST Objects are written out as XML through an XmlChan. It affects the behaviour of the astWrite function when they are used to transfer any AST Object to or from an external XML representation.

The XmlChan class allows AST objects to be represented in the form of XML in several ways (conventions) and the XmlFormat attribute is used to specify which of these should be used. The formatting options available are outlined in the "Formats Available" section below.

By default, an XmlChan will attempt to determine which format system is already in use, and will set the default XmlFormat value accordingly (so that subsequent I/O operations adopt the same conventions). It does this by looking for certain critical items which only occur in particular formats. For details of how this works, see the "Choice of Default Format" section below. If you wish to ensure that a particular format system is used, independently of any XML already read, you should set an explicit XmlFormat value yourself.

Formats Available

The XmlFormat attribute can take any of the following (case insensitive) string values to select the corresponding formatting system:

- "NATIVE": This is a direct conversion to XML of the heirarchical format used by a standard XML channel (and also by the NATIVE encoding of a FitsChan).

- "QUOTED": This is the same as NATIVE format except that extra information is included which allows client code to convert the XML into a form which can be read by a standard AST Channel. This extra information indicates which AST attribute values should be enclosed in quotes before being passed to a Channel.

- "IVOA": This is a format that uses an early draft of the STC-X schema developed by the International Virtual Observatory Alliance (IVOA - see "http://www.ivoa.net/") to describe coordinate systems, regions, mappings, etc. Support is limited to V1.20 described at "http://www.ivoa.net/Documents/WD/STC/STC-20050225.html". Since the version of STC-X finally adopted by the IVOA differs in several significant respects from V1.20, this format is now mainly of historical interest. Note, the alternative "STC-S" format (a simpler non-XML encoding of the STC metadata) is supported by the StcsChan class.

The IVOA Format

The IVOA support caters only for certain parts of V1.20 of the draft Space-Time Coordinate (STC) schema (see http://www.ivoa.net/Documents/WD/STC/STC-20050225.html). Note, this draft has now been superceded by an officially adopted version that differs in several significant respects from V1.20. Consequently, the "IVOA" XmlChan format is of historical interest only.

The following points should be noted when using an XmlChan to read or write STC information (note, this list is currently incomplete):

- Objects can currently only be read using this format, not written.
- The AST object generated by reading an <STCMetadata> element will be an instance of one of the AST "Stc" classes: StcResourceProfile, StcSearchLocation, StcCatalogEntryLocation, StcObsDataLocation.
- When reading an <STCMetadata> element, the axes in the returned AST Object will be in the order space, time, spectral, redshift, irrespective of the order in which the axes occur in the <STCMetadata> element. If the supplied <STCMetadata> element does not contain all of these axes, the returned AST Object will also omit them, but the ordering of those axes which are present will be as stated above. If the spatial frame represents a celestial coordinate system the spatial axes will be in the order (longitude, latitude).
- Until such time as the AST TimeFrame is complete, a simple 1-dimensional Frame (with Domain set to TIME) will be used to represent the STC <TimeFrame> element. Consequently, most of the information within a <TimeFrame> element is currently ignored.
- <SpaceFrame> elements can only be read if they describe a celestial longitude and latitude axes supported by the AST SkyFrame class. The space axes will be returned in the order (longitude, latitude).
- Velocities associated with SpaceFrames cannot be read.
- Any <GenericCoordFrame> elements within an <AstroCoordSystem> element are currently ignored.
- Any second or subsequent <AstroCoordSystem> found within an STCMetaData element is ignored.
- Any second or subsequent <AstroCoordArea> found within an STCMetaData element is ignored.
- Any <OffsetCenter> found within a <SpaceFrame> is ignored.
- Any CoordFlavor element found within a <SpaceFrame> is ignored.
- <SpaceFrame> elements can only be read if they refer to one of the following space reference frames: ICRS, GALACTIC_II, SUPER_GALACTIC, HEE, FK4, FK5, ECLIPTIC.
- <SpaceFrame> elements can only be read if the reference position is TOPOCENTER. Also, any planetary ephemeris is ignored.
- Regions: there is currently no support for STC regions of type Sector, ConvexHull or SkyIndex.
- The AST Region read from a CoordInterval element is considered to be open if either the lo_include or the hi_include attribute is set to false.
- <RegionFile> elements are not supported.
- Vertices within <Polygon> elements are always considered to be joined using great circles (that is, <SmallCircle> elements are ignored).

Returns:

this object's XmlFormat attribute

setXmlFormat

public void setXmlFormat(String xmlFormat)

Set system for formatting Objects as XML. This attribute specifies the formatting system to use when AST Objects are written out as XML through an XmlChan. It affects the behaviour of the astWrite function when they are used to transfer any AST Object to or from an external XML representation.

The XmlChan class allows AST objects to be represented in the form of XML in several ways (conventions) and the XmlFormat attribute is used to specify which of these should be used. The formatting options available are outlined in the "Formats Available" section below.

By default, an XmlChan will attempt to determine which format system is already in use, and will set the default XmlFormat value accordingly (so that subsequent I/O operations adopt the same conventions). It does this by looking for certain critical items which only occur in particular formats. For details of how this works, see the "Choice of Default Format" section below. If you wish to ensure that a particular format system is used, independently of any XML already read, you should set an explicit XmlFormat value yourself.

Formats Available

The XmlFormat attribute can take any of the following (case insensitive) string values to select the corresponding formatting system:

- "NATIVE": This is a direct conversion to XML of the heirarchical format used by a standard XML channel (and also by the NATIVE encoding of a FitsChan).

- "QUOTED": This is the same as NATIVE format except that extra information is included which allows client code to convert the XML into a form which can be read by a standard AST Channel. This extra information indicates which AST attribute values should be enclosed in quotes before being passed to a Channel.

- "IVOA": This is a format that uses an early draft of the STC-X schema developed by the International Virtual Observatory Alliance (IVOA - see "http://www.ivoa.net/") to describe coordinate systems, regions, mappings, etc. Support is limited to V1.20 described at "http://www.ivoa.net/Documents/WD/STC/STC-20050225.html". Since the version of STC-X finally adopted by the IVOA differs in several significant respects from V1.20, this format is now mainly of historical interest. Note, the alternative "STC-S" format (a simpler non-XML encoding of the STC metadata) is supported by the StcsChan class.

The IVOA Format

The IVOA support caters only for certain parts of V1.20 of the draft Space-Time Coordinate (STC) schema (see http://www.ivoa.net/Documents/WD/STC/STC-20050225.html). Note, this draft has now been superceded by an officially adopted version that differs in several significant respects from V1.20. Consequently, the "IVOA" XmlChan format is of historical interest only.

The following points should be noted when using an XmlChan to read or write STC information (note, this list is currently incomplete):

- Objects can currently only be read using this format, not written.
- The AST object generated by reading an <STCMetadata> element will be an instance of one of the AST "Stc" classes: StcResourceProfile, StcSearchLocation, StcCatalogEntryLocation, StcObsDataLocation.
- When reading an <STCMetadata> element, the axes in the returned AST Object will be in the order space, time, spectral, redshift, irrespective of the order in which the axes occur in the <STCMetadata> element. If the supplied <STCMetadata> element does not contain all of these axes, the returned AST Object will also omit them, but the ordering of those axes which are present will be as stated above. If the spatial frame represents a celestial coordinate system the spatial axes will be in the order (longitude, latitude).
- Until such time as the AST TimeFrame is complete, a simple 1-dimensional Frame (with Domain set to TIME) will be used to represent the STC <TimeFrame> element. Consequently, most of the information within a <TimeFrame> element is currently ignored.
- <SpaceFrame> elements can only be read if they describe a celestial longitude and latitude axes supported by the AST SkyFrame class. The space axes will be returned in the order (longitude, latitude).
- Velocities associated with SpaceFrames cannot be read.
- Any <GenericCoordFrame> elements within an <AstroCoordSystem> element are currently ignored.
- Any second or subsequent <AstroCoordSystem> found within an STCMetaData element is ignored.
- Any second or subsequent <AstroCoordArea> found within an STCMetaData element is ignored.
- Any <OffsetCenter> found within a <SpaceFrame> is ignored.
- Any CoordFlavor element found within a <SpaceFrame> is ignored.
- <SpaceFrame> elements can only be read if they refer to one of the following space reference frames: ICRS, GALACTIC_II, SUPER_GALACTIC, HEE, FK4, FK5, ECLIPTIC.
- <SpaceFrame> elements can only be read if the reference position is TOPOCENTER. Also, any planetary ephemeris is ignored.
- Regions: there is currently no support for STC regions of type Sector, ConvexHull or SkyIndex.
- The AST Region read from a CoordInterval element is considered to be open if either the lo_include or the hi_include attribute is set to false.
- <RegionFile> elements are not supported.
- Vertices within <Polygon> elements are always considered to be joined using great circles (that is, <SmallCircle> elements are ignored).

Parameters:

xmlFormat - the XmlFormat attribute of this object

getXmlIndent

public boolean getXmlIndent()

Get XmlIndent attribute.

Returns:

this object's XmlIndent attribute

setXmlIndent

public void setXmlIndent(boolean xmlIndent)

Set XmlIndent attribute.

Parameters:

xmlIndent - the XmlIndent attribute of this object

getXmlLength

public int getXmlLength()

Get controls output buffer length. This attribute specifies the maximum length to use when writing out text through the sink function supplied when the XmlChan was created.

The number of characters in each string written out through the sink function will not be greater than the value of this attribute (but may be less). A value of zero (the default) means there is no limit - each string can be of any length.

Returns:

this object's XmlLength attribute

setXmlLength

public void setXmlLength(int xmlLength)

Set controls output buffer length. This attribute specifies the maximum length to use when writing out text through the sink function supplied when the XmlChan was created.

The number of characters in each string written out through the sink function will not be greater than the value of this attribute (but may be less). A value of zero (the default) means there is no limit - each string can be of any length.

Parameters:

xmlLength - the XmlLength attribute of this object

getXmlPrefix

public String getXmlPrefix()

Get the namespace prefix to use when writing. This attribute is a string which is to be used as the namespace prefix for all XML elements created as a result of writing an AST Object out through an XmlChan. The URI associated with the namespace prefix is given by the symbolic constant AST__XMLNS defined in ast.h. A definition of the namespace prefix is included in each top-level element produced by the XmlChan.

The default value is a blank string which causes no prefix to be used. In this case each top-level element will set the default namespace to be the value of AST__XMLNS.

Returns:

this object's XmlPrefix attribute

setXmlPrefix

public void setXmlPrefix(String xmlPrefix)

Set the namespace prefix to use when writing. This attribute is a string which is to be used as the namespace prefix for all XML elements created as a result of writing an AST Object out through an XmlChan. The URI associated with the namespace prefix is given by the symbolic constant AST__XMLNS defined in ast.h. A definition of the namespace prefix is included in each top-level element produced by the XmlChan.

The default value is a blank string which causes no prefix to be used. In this case each top-level element will set the default namespace to be the value of AST__XMLNS.

Parameters:

xmlPrefix - the XmlPrefix attribute of this object