stella.xml
Class DOMTarget

java.lang.Object
  stella.xml.DOMTarget

All Implemented Interfaces:

DTDConstants

public class DOMTarget
extends Object
implements DTDConstants

An XML-parser-application interface to read target definition files in XML format (see w3c XML 1.0). It uses Sun's jaxp extension interface to first read in the file and parse it into a DOM object.

Note that the DOM created out of the object-definition file may be altered at runtime for the sake of error handling.

A valid object-definition file must follow this DTD grammar.

An dom target always expects that all elements are set. Targets that provide only fragmentary information must be augmented prior to processing using the various factory methods in the TargetFragment class.

What follows is a description of the individual, non-selfexplanory elements, attributes and their allowed values (if any restrictions apply).

The Object element takes two attributes, the required attribute type and the enumeration attribute access which defaults to 'enabled' . The type attribute allows the sequencer to load the proper observing sequence for this object. Access is used to qualify the access properties of a target. It defaults to enabled.
History is an element that defines the observing history of this object. If it is not directly stored in the xml-file, The db attribute defines a database access for the history. The TargetFragment#fillHistory method takes care of proper loading. A target history consists of an arbitrary number of Picks. Each Pick carries a success boolean attribute, the start and duration of the observation, along with the optional SNgot and a comment. The Observstart is a parsable date, following the generic java.text.DataFormat.parse contract. Duration is the duration of the observation, in ms. SNgot is the signal-to-noise acheived at this observation.
The optional Abort elements defines the target's behaviour in case of non-successful observations. Errors that Block a target set its access attribute to false. Delay errors disable access for the specified for time, in seconds. Retry errors immediately re-schedule the target, while Ignore specifies errors that are simply ignored, i.e. the target is considered successfully observed. If this block is missing, any error received blocks the target.
Select is a required element that is mainly intended as a hint or rule for the scheduler. The Requires element carries an expression that must be parsable to a primitive boolean at run-time. The Constrain sections, if present, consists of a Parameter entry, specifying a parameter name in the parameter set at hand for the scheduler. If a paramter stated is a TargetDependingParameter, it's value is checked against this target. Each parameter is followed by a constrain, which is one of these four possiblities:

• Min: The sensor/variable's value must be at least the stated value.
• Max: The sensor/variable's value may not exceed the stated value.
• (From, To): The sensor/variable's value must lie within the stated range. Both elements must be present.
• (Below, Above): The sensor/variable's value may not lie within the stated range. Both elements must be present

If a Merit is given (TargetFragment defaults to TargetFragment#DEFGAIN and TargetFragment#DEFTIMESLOT), it is used to specify the dispatch-scheduling behaviour. The merit consists of an optional Timeslot and a variable number of Gains. Both elements define Meriting objects, the only difference is how they are treated in calculating the target merit: First, all gains are summed up and then multiplied with the timeslot, or one if no timeslot is given. This also implies that gains should default to zero, while a undefined timeslot should deliver one in its Meriting.getMerit(stella.ParameterClustering, stella.TargetDefinition, java.util.Collection, long) method. Depending on the -required- class attribute, the corresponding meriting class is instantiated at runtime and initialized with the Init section, if present. The list of Constants give names and values of various parameters used within the meriting instance.
The Star section is a required one, it must be present at least once. It may have a unique identifier attribute, id. This id may be used in the #getProperties method. Any star section consists of five subsections, where the first two are mandatory, namely General, Instrument, Guiding, FitsHeader and FieldOfView. The General section consists of the following elements:

• Name: Required. This name is used for a look-up in the local Tycho-2 database. It is recommended that you use Tycho2 catalog references, like 'tyc 8023-177-1'. If this is not possible, hip or hd numbers may be used ('hd 12545', 'hip 9630'). If the entry does not start with one of these three catalog identifiers, the stated name is used as the generic name. Though it cannot be looked up in the database, at least right ascension, declination, and Johnson V must be explicetly given. Additionally, the field-of-view lookup is affected, see TargetFragment#fillUndefinedElements. Note that due to the general SQL- contract catalog identifiers are non-case sensitive.
• RA: May be specified to either overrule the database entry or to specify objects not in the database. In degrees, equinox 2000.0.
• Dec: May be specified to either overrule the database entry or to specify objects not in the database. In degrees, equinox 2000.0.
• PmRA: May be specified to either overrule the database entry or to specify objects not in the database. Proper motion in ra in mas/yr, already multiplied with cosine of the declination. ICRS 2000.0.
• PmDec: May be specified to either overrule the database entry or to specify objects not in the database. Proper motion in dec in mas/yr, ICRS 2000.0.
• V: May be specified to either overrule the database entry or to specify objects not in the database. Brightness in Johnson V, magnitudes.
• B-V: May be specified to either overrule the database entry or to specify objects not in the database. Color index Johnson B-V, magnitudes.

General stellar properties not found in the target definition are filled from the Tycho database if possible. The Instrument subsection consists of the following elements. It may also carry an id attribute. At the time of this writing, the following section may be subject to change.

• Wavelength: Required. Specifies the spectral region to cover. The format is free in the sense that meaningful definition may be added at any time.
• ExposureTime or S-N: Required. Specifies the exposure time (in seconds) or the required S/N. At the time of this writing it is not clear if the S/N is actually measured or only used to derive an exposure time, depending on airmass and other environmental parameters.
• Buffer or Enlarge: Optional. Specifies either an additional exposure buffer in seconds or a factor by with the exposure time may be enlarged. Defaults to zero buffer.
• Fiber: Optional. Specifies the fiber to use, identified with its diameter in microns. Defaults to 50. At the time of this writing it is not clear if there are more than one fiber present at all.

All of these parameters may carry a class to specify the run-time class of these parameters for further reference in Double and/or Boolean nodes The optinal Guiding subsection consists of two optional elements,

• Method: The guiding method to use, defaults to Beamsplitter. Only certain names are allowed.
• Filter: The color-filter to use in front of the guiding camera. Defaults to clear. Only certain identifiers allowed.

The optional FitsHeader subsection consists of three types of elements, all of them may be present zero or more times.

• Extern: A String that is transfered to the fits-header as-is.
• Intern: A String denoting a global variable, see Parameter. May have an attribute at stating when the variable's value should be recorded. Valid at identifiers are 'start', 'end', and 'central'. Defaults to central.
• Condition : An element referring to a valid sensor name. The name of the sensor whose read-out should be included in the FITS header is given in the required attribute sensor. The empty sub-elements Val, MinVal, MaxVal, Sig, Start and End refer to way the sensor value should be derived.

The optional FieldOfView star subsections consists of the same elements as the general star subsection. The only difference is that the name is an otional element, while right ascension, declination and Johnson V are required. Note that the target star must always be the first FieldOfView entry. If no field of view is specified (as will be the normal way), the tycho catalog is querried for entries around the target star. All entries found are translated into field of view subsections, see TargetFragment#fillUndefinedElements.
The optional Sky elements are similar to the star entry. Note that it is not required that the entire functionality of the grammer is actually implemented in software. The XML-definition is merely a format to allow the stating of all relevant data, regardless whether they are used or not.

Nested Class Summary

static class	DOMTarget.Deserialize A class to test serialization.
static class	DOMTarget.FileToFile A class that reads in an xml-file, parses, and writes an xml-file.
static class	DOMTarget.Filter A class that reads in an xml-file, parses, and writes an xml-file, if it satisfies a certain filter.
static class	DOMTarget.Properties A class that reads in an xml-file, parses, and prints out the global properties of the target.
static class	DOMTarget.Serialize A class that reads in an xml-file, parses, and serializes it.
static class	DOMTarget.SerializeMerit A clas to test serialization of merits.

Field Summary

Fields inherited from interface stella.xml.DTDConstants

ABORT, ABOVE, ABSTRACT, ABSTRACTPROPOSAL, ADDRESS, BELOW, BLOCK, BROADCAST, BROADCASTWITH, BV, CHANGE, CLASS, COMMAND, COMMANDID, COMMANDINIT, COMMANDLAST, COMMANDPARAMETER, COMMANDREF, COMMENT, COMPLETE, CONDITION, CONSTANT, CONSTANTNAME, CONSTANTVALUE, CONSTRAINT, CONSTRAINTOVERDUE, CONSTRAINTRELAX, DATA, DAUGHTER, DEC, DELAY, DELAYMAX, DELAYTIME, DISABLED, DOCPATH, DURATION, ELAPSED, EMAIL, ENABLED, EPOCH, EQUINOX, EXCEPTION, EXCEPTIONDAUGHTER, EXCEPTIONFOR, EXCEPTIONSUCCESSOR, EXCEPTIONTHIS, FALSE, FIELDOFVIEW, FILE, FITSHEADER, FITSHEADERID, FORMATCLASS, FORMATPATTERN, FROM, GAIN, HISTORY, HISTORYCOMPLETE, HISTORYDB, HISTORYMAX, HISTORYREAD, IGNORE, IMAGETYPE, INIT, INSTITUTION, INSTRUMENT, INTERN, KEY, MAX, MERIT, MIN, NOTIFY, OBJECT, OBJECTID, OBJECTNAME, OBSERVSTART, PICK, PICKMERIT, PICKSUCCESS, PMDEC, PMRA, POSITION, RA, RATE, REC, REQUIRES, RETRY, RETRYMAX, SELECT, SENDING, SEQUENCE, SEQUENCETYPE, SET, SETNAME, SETUP, SETUPID, STEP, STEPCOUNTER, STEPWHILE, SUCCESSOR, TARGET, TARGETACCESS, TARGETDB, TARGETNAME, TARGETNAMEPROPOSAL, TARGETREAD, TARGETSUBMITTED, TARGETTYPE, TASK, TASKDONE, TASKID, TEAM, TIMESLOT, TITLE, TO, TRUE, USER, V, VARIABLE

Constructor Summary

DOMTarget()

Method Summary

private static Element	appendErrorElements(Element root, String tag, List err) Takes a list of strings that are error names and converts them into an element tree.
private static Element	appendMeritElements(Element root, String tag, List merit) Takes a list of living Meriting references and converts them to either DTDConstants.TIMESLOT or DTDConstants.GAIN elements, depending on the tag name supplied.
private static Comparable	constraintParse(Node con, String tag, String fclass, String fpatt) Parses a constraint node to get min/max/from-to/below-above out of it.
static ParsedTarget	deserializeTarget(String tel, File in) Deserializes an object from an URL.
static ParsedTarget	deserializeTarget(String tel, URL in) Deserializes an object from an URL.
private static List<Appointable.Constraint>	getConstraintList(Element xml, String tag) Scans a node for constraint elements.
private static ExpressionEvaluator	getExpression(Node xml, String tag) Scans an element for an expresion.
private static List	parseHistory(Document xml, int len, DateFormat df) Parses the history list from an xml file.
static ParsedTarget	parseTarget(String tel, Document xml, boolean allowdb, Map prop) Parses a document that describes a STELLA target into a ParsedTarget.
static ParsedTarget	parseTarget(String tel, Document xml, Map prop) Parses a document that describes a STELLA target into a ParsedTarget.
static boolean	serializeTarget(ParsedTarget write, File out) Serializes an object to a file.
static Document	toDocument(ParsedTarget target, Map prop) Converts a parsed target into a DOM.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DOMTarget

public DOMTarget()

Method Detail

parseTarget

public static final ParsedTarget parseTarget(String tel,
                                             Document xml,
                                             Map prop)

Parses a document that describes a STELLA target into a ParsedTarget. The document handed over should have all optional fields filled in, i.e. it should be created with the TargetFragment#createTargetDocument method.

parseTarget

public static final ParsedTarget parseTarget(String tel,
                                             Document xml,
                                             boolean allowdb,
                                             Map prop)

Parses a document that describes a STELLA target into a ParsedTarget. The document handed over should have all optional fields filled in, i.e. it should be created with the TargetFragment#createTargetDocument method.

toDocument

public static Document toDocument(ParsedTarget target,
                                  Map prop)

Converts a parsed target into a DOM. This dom may then be stored as an xml file.

getExpression

private static ExpressionEvaluator getExpression(Node xml,
                                                 String tag)

Scans an element for an expresion.

getConstraintList

private static final List<Appointable.Constraint> getConstraintList(Element xml,
                                                                    String tag)

Scans a node for constraint elements.

constraintParse

private static Comparable constraintParse(Node con,
                                          String tag,
                                          String fclass,
                                          String fpatt)

Parses a constraint node to get min/max/from-to/below-above out of it. Each node may carry an attribute stating its formatter class and formatter pattern. Default parsing of strings to double is done.

parseHistory

private static List parseHistory(Document xml,
                                 int len,
                                 DateFormat df)

Parses the history list from an xml file. Only used if no database is given.

deserializeTarget

public static final ParsedTarget deserializeTarget(String tel,
                                                   File in)

Deserializes an object from an URL. If deserialization fails, return null

deserializeTarget

public static final ParsedTarget deserializeTarget(String tel,
                                                   URL in)

Deserializes an object from an URL. If deserialization fails, return null

serializeTarget

public static final boolean serializeTarget(ParsedTarget write,
                                            File out)

Serializes an object to a file. If deserialization fails, false is returned.

appendErrorElements

private static final Element appendErrorElements(Element root,
                                                 String tag,
                                                 List err)

Takes a list of strings that are error names and converts them into an element tree. The root element is handed over and for each error name found a sub-element with the given tag-name is appended to the root element.

Parameters:

root - The root element, an DTDConstants.EXCEPTION

tag - The tag name for appending error names

err - A list of error names.

Returns:

The enhanced root element

appendMeritElements

private static final Element appendMeritElements(Element root,
                                                 String tag,
                                                 List merit)

Takes a list of living Meriting references and converts them to either DTDConstants.TIMESLOT or DTDConstants.GAIN elements, depending on the tag name supplied. Each merit-element constructed is appended to the root-element.