uk.ac.starlink.ast

Class Channel

java.lang.Object

uk.ac.starlink.ast.AstObject

uk.ac.starlink.ast.Channel

Direct Known Subclasses:

FitsChan, XmlChan

public class Channel
extends AstObject

Java interface to the AST Channel class - basic (textual) I/O channel.

This class is used for reading and writing AST objects from/to external media. The Channel class itself reads from System.in or another InputStream and writes to System.out or another OutputStream. To perform I/O to some other object, extend this class and override the source and sink methods.

See Also:

AST Channel

Field Summary

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

AST__BAD, AST__TUNULL, pointer

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Channel() This constructor does not do all the required construction to create a valid Channel object, but is required for inheritance by user subclasses of Channel.
protected	Channel(Channel dummy) This is a dummy constructor which does nothing at all.
	Channel(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
AstObject	copy() This method is currently unsupported for Channel and its subclasses because of difficulties in its implementation, and because it is probably not that useful.
protected void	finalize() Finalizes the object.
boolean	getComment() Get include textual comments in output.
int	getFull() Get set level of output detail.
int	getReportLevel() Get determines which read/write conditions are reported.
boolean	getSkip() Get skip irrelevant data.
boolean	getStrict() Get report an error if any unexpeted data items are found.
AstObject	read() Reads an AST object from this channel.
void	setComment(boolean comment) Set include textual comments in output.
void	setFull(int full) Set set level of output detail.
void	setReportLevel(int reportLevel) Set determines which read/write conditions are reported.
void	setSkip(boolean skip) Set skip irrelevant data.
void	setStrict(boolean strict) Set report an error if any unexpeted data items are found.
protected void	sink(String line) Writes a String which forms one line of the textual representation of an AST object to the channel's output stream.
protected String	source() Reads a String which forms one line of the textual representation of an AST object from the channel's input stream.
KeyMap	warnings() Returns any warnings issued by the previous read or write operation.
int	write(AstObject obj) Writes an AST object to this channel.

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

Constructor Detail

Channel

public Channel(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.

Channel

protected Channel()

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

Channel

protected Channel(Channel dummy)

This is a dummy constructor which does nothing at all. It is invoked by the FitsChan constructor to prevent it having to use the no-argument constructor which does things FitsChan does not want.

Method Detail

finalize

protected void finalize()
                 throws Throwable

Finalizes the object. Certain resources allocated by the native code are freed, and the finalizer of the superclass is called.

Overrides:

finalize in class AstObject

Throws:

Throwable

source

protected String source()
                 throws IOException

Reads a String which forms one line of the textual representation of an AST object from the channel's input stream. If the end of the stream is reached, null is returned. If an IOException occurs during the reading, it is thrown.

This method is called by the read method. To implement a channel which reads from a source other than an InputStream, override this method. The method should return null when there is no more input, and may throw an IOException in case of error.

Returns:

a line of text read from the input stream, as a String. If the end of the stream has been reached, null is returned.

Throws:

IOException - if an I/O error occurs during reading

sink

protected void sink(String line)
             throws IOException

Writes a String which forms one line of the textual representation of an AST object to the channel's output stream. If an IOException occurs during the writing, it is thrown.

This method is called by the write method. To implement a channel which writes to a source other than an OutputStream, override this method. The method can do anything it likes with its argument, and may throw an exception in case of error.

Parameters:

line - a String which forms one line of the textual description of an AST object which is being written.

Throws:

IOException - if an I/O error occurs during writing.

read

public AstObject read()
               throws IOException

Reads an AST object from this channel. The source method is invoked to obtain the textual representation.

Returns:

the AstObject which has been read. null is returned, without error, if no further objects remain to be read on the stream

Throws:

IOException - if such an exception was generated by the source method

AstException - if an error occurs in the AST library

write

public int write(AstObject obj)
          throws IOException

Writes an AST object to this channel. The sink method is invoked to send the textual representation.

Parameters:

obj - an AstObject to be written

Returns:

number of objects written (1 on success)

Throws:

IOException - if such an exception was generated by the sink method

AstException - if an error occurs in the AST library

copy

public AstObject copy()

This method is currently unsupported for Channel and its subclasses because of difficulties in its implementation, and because it is probably not that useful.

Overrides:

copy in class AstObject

Returns:

Pointer to the new Object.

Throws:

UnsupportedOperationException - always

warnings

public KeyMap warnings()

Returns any warnings issued by the previous read or write operation. This function returns an AST KeyMap object holding the text of any warnings issued as a result of the previous invocation of the astRead or astWrite function on the Channel. If no warnings were issued, a a NULL value will be returned.

Such warnings are non-fatal and will not prevent the read or write operation succeeding. However, the converted object may not be identical to the original object in all respects. Differences which would usually be deemed as insignificant in most usual cases will generate a warning, whereas more significant differences will generate an error.

The "Strict" attribute allows this warning facility to be switched off, so that a fatal error is always reported for any conversion error.

Notes

- The returned KeyMap uses keys of the form "Warning_1", "Warning_2", etc.
- A value of NULL will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Returns:

A pointer to the KeyMap holding the warning messages, or NULL if no warnings were issued during the previous read operation.

Throws:

AstException - if an error occurred in the AST library

getComment

public boolean getComment()

Get include textual comments in output. This is a boolean attribute which controls whether textual comments are to be included in the output generated by a Channel. If included, they will describe what each item of output represents.

If Comment is non-zero, then comments will be included. If it is zero, comments will be omitted.

Returns:

this object's Comment attribute

setComment

public void setComment(boolean comment)

Set include textual comments in output. This is a boolean attribute which controls whether textual comments are to be included in the output generated by a Channel. If included, they will describe what each item of output represents.

If Comment is non-zero, then comments will be included. If it is zero, comments will be omitted.

Parameters:

comment - the Comment attribute of this object

getFull

public int getFull()

Get set level of output detail. This attribute is a three-state flag and takes values of -1, 0 or +1. It controls the amount of information included in the output generated by a Channel.

If Full is zero, then a modest amount of non-essential but useful information will be included in the output. If Full is negative, all non-essential information will be suppressed to minimise the amount of output, while if it is positive, the output will include the maximum amount of detailed information about the Object being written.

Notes

- All positive values supplied for this attribute are converted to +1 and all negative values are converted to -1.

Returns:

this object's Full attribute

setFull

public void setFull(int full)

Set set level of output detail. This attribute is a three-state flag and takes values of -1, 0 or +1. It controls the amount of information included in the output generated by a Channel.

If Full is zero, then a modest amount of non-essential but useful information will be included in the output. If Full is negative, all non-essential information will be suppressed to minimise the amount of output, while if it is positive, the output will include the maximum amount of detailed information about the Object being written.

Notes

- All positive values supplied for this attribute are converted to +1 and all negative values are converted to -1.

Parameters:

full - the Full attribute of this object

getReportLevel

public int getReportLevel()

Get determines which read/write conditions are reported. This attribute determines which, if any, of the conditions that occur whilst reading or writing an Object should be reported. These conditions will generate either a fatal error or a warning, as determined by attribute Strict. ReportLevel can take any of the following values:

0 - Do not report any conditions.

1 - Report only conditions where significant information content has been changed. For instance, an unsupported time-scale has been replaced by a supported near-equivalent time-scale. Another example is if a basic Channel unexpected encounters data items that may have been introduced by later versions of AST.

2 - Report the above, and in addition report significant default values. For instance, if no time-scale was specified when reading an Object from an external data source, report the default time-scale that is being used.

3 - Report the above, and in addition report any other potentially interesting conditions that have no significant effect on the conversion. For instance, report if a time-scale of "TT" (terrestrial time) is used in place of "ET" (ephemeris time). This change has no signficiant effect because ET is the predecessor of, and is continuous with, TT. Synonyms such as "IAT" and "TAI" are another example.

The default value is 1. Note, there are many other conditions that can occur whilst reading or writing an Object that completely prevent the conversion taking place. Such conditions will always generate errors, irrespective of the ReportLevel and Strict attributes.

Returns:

this object's ReportLevel attribute

setReportLevel

public void setReportLevel(int reportLevel)

Set determines which read/write conditions are reported. This attribute determines which, if any, of the conditions that occur whilst reading or writing an Object should be reported. These conditions will generate either a fatal error or a warning, as determined by attribute Strict. ReportLevel can take any of the following values:

0 - Do not report any conditions.

1 - Report only conditions where significant information content has been changed. For instance, an unsupported time-scale has been replaced by a supported near-equivalent time-scale. Another example is if a basic Channel unexpected encounters data items that may have been introduced by later versions of AST.

2 - Report the above, and in addition report significant default values. For instance, if no time-scale was specified when reading an Object from an external data source, report the default time-scale that is being used.

3 - Report the above, and in addition report any other potentially interesting conditions that have no significant effect on the conversion. For instance, report if a time-scale of "TT" (terrestrial time) is used in place of "ET" (ephemeris time). This change has no signficiant effect because ET is the predecessor of, and is continuous with, TT. Synonyms such as "IAT" and "TAI" are another example.

The default value is 1. Note, there are many other conditions that can occur whilst reading or writing an Object that completely prevent the conversion taking place. Such conditions will always generate errors, irrespective of the ReportLevel and Strict attributes.

Parameters:

reportLevel - the ReportLevel attribute of this object

getSkip

public boolean getSkip()

Get skip irrelevant data. This is a boolean attribute which indicates whether the Object data being read through a Channel are inter-mixed with other, irrelevant, external data.

If Skip is zero (the default), then the source of input data is expected to contain descriptions of AST Objects and comments and nothing else (if anything else is read, an error will result). If Skip is non-zero, then any non-Object data encountered between Objects will be ignored and simply skipped over in order to reach the next Object.

Returns:

this object's Skip attribute

setSkip

public void setSkip(boolean skip)

Set skip irrelevant data. This is a boolean attribute which indicates whether the Object data being read through a Channel are inter-mixed with other, irrelevant, external data.

If Skip is zero (the default), then the source of input data is expected to contain descriptions of AST Objects and comments and nothing else (if anything else is read, an error will result). If Skip is non-zero, then any non-Object data encountered between Objects will be ignored and simply skipped over in order to reach the next Object.

Parameters:

skip - the Skip attribute of this object

getStrict

public boolean getStrict()

Get report an error if any unexpeted data items are found. This is a boolean attribute which indicates whether a warning rather than an error should be issed for insignificant conversion problems. If it is set non-zero, then fatal errors are issued instead of warnings, resulting in the AST error status being set. If Strict is zero (the default), then execution continues after minor conversion problems, and a warning message is added to the Channel structure. Such messages can be retrieved using the astWarnings function.

Notes

- This attribute was introduced in AST version 5.0. Prior to this version of AST unexpected data items read by a basic Channel always caused an error to be reported. So applications linked against versions of AST prior to version 5.0 may not be able to read Object descriptions created by later versions of AST, if the Object's class description has changed.

Returns:

this object's Strict attribute

setStrict

public void setStrict(boolean strict)

Set report an error if any unexpeted data items are found. This is a boolean attribute which indicates whether a warning rather than an error should be issed for insignificant conversion problems. If it is set non-zero, then fatal errors are issued instead of warnings, resulting in the AST error status being set. If Strict is zero (the default), then execution continues after minor conversion problems, and a warning message is added to the Channel structure. Such messages can be retrieved using the astWarnings function.

Notes

- This attribute was introduced in AST version 5.0. Prior to this version of AST unexpected data items read by a basic Channel always caused an error to be reported. So applications linked against versions of AST prior to version 5.0 may not be able to read Object descriptions created by later versions of AST, if the Object's class description has changed.

Parameters:

strict - the Strict attribute of this object