|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectuk.ac.starlink.ast.AstObject
uk.ac.starlink.ast.Channel
uk.ac.starlink.ast.XmlChan
public class XmlChan
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.
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
Field Summary | |
---|---|
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 | |
---|---|
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 | |
---|---|
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 |
---|
public static final String AST__XMLNS
Constructor Detail |
---|
public XmlChan(InputStream in, OutputStream out)
InputStream
and writes to the given OutputStream
.
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.protected XmlChan()
Method Detail |
---|
public String getXmlFormat()
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.
- "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 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
- When reading an
- 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
-
- Velocities associated with SpaceFrames cannot be read.
- Any
- Any second or subsequent
- Any second or subsequent
- Any
- Any CoordFlavor element found within a
-
-
- 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.
-
- Vertices within
public void setXmlFormat(String xmlFormat)
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.
- "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 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
- When reading an
- 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
-
- Velocities associated with SpaceFrames cannot be read.
- Any
- Any second or subsequent
- Any second or subsequent
- Any
- Any CoordFlavor element found within a
-
-
- 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.
-
- Vertices within
xmlFormat
- the XmlFormat attribute of this object
public boolean getXmlIndent()
public void setXmlIndent(boolean xmlIndent)
xmlIndent
- the XmlIndent attribute of this objectpublic int getXmlLength()
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.
public void setXmlLength(int xmlLength)
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.
xmlLength
- the XmlLength attribute of this objectpublic String getXmlPrefix()
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.
public void setXmlPrefix(String xmlPrefix)
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.
xmlPrefix
- the XmlPrefix attribute of this object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |