stella.xml

Class TargetFactory

java.lang.Object

stella.xml.TargetFactory

All Implemented Interfaces:

DTDConstants

public class TargetFactory
extends Object
implements DTDConstants

A class to allow easy production of target-xml files. It is meant for single-object files and not for target chains or target lists. It provides basic facilities and should be used to allow GUI, e-mail, and command-line construction of a target file. It uses Simbad and VizieR queries to fill in relevant astrometric data. This class is somewhat compulsary to the TargetFragment class which is the old class used to expand not-fully qualified xml-targets.

Field Summary

Fields

Modifier and Type	Field and Description
static SimpleDateFormat	DATEFORMAT The date formatter to use.
private static Document	dom The empty document used to create document fragments.

Fields inherited from interface stella.xml.DTDConstants

ABORT, ABOVE, ABSTRACT, ABSTRACTPROPOSAL, ADDRESS, BELOW, BLOCK, BROADCAST, BROADCASTWITH, BV, CHAINING, 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

Constructors

Constructor and Description
TargetFactory()

Method Summary

Modifier and Type	Method and Description
private static void	addList(Element father, List children) Adds a list of document fragments as childs to the main element.
private static Node	addTextList(Node father, String type, List text) Adds errors in the specified section.
protected static Element	appendConstraints(Element select, List constrain) Appends a list of non-bull constraints to an element.
private static Element	constraintChoice(Element c, Object border) Takes a comparable object and adds attributes to the element plus the parsable conatraint text.
static Map	createAbstract(String text, Map collect) Creates a document fragment with a DTDConstants.ABSTRACT element carrying the provided text in a single text-node child.
static List<Element>	createConstant(Map<String,Object> params) Creates a constant element.
static Map	createDaughter(List dau, Map collect) Creates a document fragment with DTDConstants.DAUGHTER elements enclosing the provided daughter target names.
static Map	createDuration(Number dur, Map collect) Creates a document fragment with a DTDConstants.DURATION element carrying the provided user name in a single text-node child.
private static Map	createElementWithSingleText(String tag, String text, Map collect) Creates a document fragment, adds an element with the given tag name to it as the first child and creates a text node that is appended to the new element as a single child.
static Map	createEmail(Collection<? extends javax.mail.Address> address, Collection<UserProfile.Notifies> notify, Map collect) Creates a document fragment with an DTDConstants.EMAIL element carrying The e-mail address of the user plus additional notification elements.
static Map	createException(String forwhom, List block, int delaymax, long delaytime, List delay, List abort, int retrymax, List retry, List ignore, Map collect) Creates an exception element.
static Map	createFile(String file, Map collect) Creates a document fragment with a DTDConstants.FILE element carrying the provided file name in a single text-node child.
static Map	createFitsHeader(String id, List fits, Map collect) Creates a single fits-header element from an id and a list of DTDConstants.INTERN elements.
static Map	createHistory(Map collect) Creates an empty histroy element.
static Map	createInstitution(UserProfile.Affil inst, Map collect) Creates a document fragment with a DTDConstants.INSTITUTION element carrying the provided user name in a single text-node child.
static Element	createInternFitsHeader(String key, String var, String remark) Creates a single intern fits-header element with the given key and variable name.
static Element	createMerit(String tag, String classname, String init, Map params) Creates an element that contains everything that builds up a merit.
static Map	createObject(Star main, String id, List fov, Map collect) Creates the object entry.
static Map	createRate(String requires, List constraints, Map collect) Creates the select section.
static Map	createSelect(String requires, List constraints, List gains, List timeslots, Map collect) Creates the select section.
static Map	createSetup(String id, String instrument, List cons, Map collect) Creates a setup element using an setup-id, an instrument description as a string and a constant element.
static Map	createSuccessor(String suc, Map collect) Creates a document fragment with a DTDConstants.SUCCESSOR element carrying the provided successor file name in a single text-node child.
static Document	createTargetFromMap(String access, String type, Map docfrag) Uses a map of essential STELLA-xml top-level elements to pre-created document fragments and puts them together into a single document.
static Map	createTargetName(String name, String propid, Map collect) Creates a document fragment with a DTDConstants.TARGETNAME element and puts it into the lookup table provided.
static Map	createTeam(List<String> team, Map collect) Creates a document fragment with a DTDConstants.TEAM element carrying the provided user names in a variable-length User fassion.
static Map	createTitle(String title, Map collect) Creates a document fragment with a DTDConstants.FILE element carrying the provided file name in a single text-node child.
static Map	createUser(String user, Map collect) Creates a document fragment with a DTDConstants.USER element carrying the provided user name in a single text-node child.
static void	setDom(Document empty) Sets the dom from which fragement creation is done.

Methods inherited from class java.lang.Object

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

Field Detail

dom

private static Document dom

The empty document used to create document fragments.

DATEFORMAT

public static final SimpleDateFormat DATEFORMAT

The date formatter to use.

Constructor Detail

TargetFactory

public TargetFactory()

Method Detail

setDom

public static void setDom(Document empty)

Sets the dom from which fragement creation is done. Usually an empty target.

createConstant

public static List<Element> createConstant(Map<String,Object> params)

Creates a constant element. Takes a mapping of constant-names to constant values, the class-type of the mapped value is added in a class attribute to the constant element.

Returns:

a List of elements

createTargetName

public static Map createTargetName(String name,
                                   String propid,
                                   Map collect)

Creates a document fragment with a DTDConstants.TARGETNAME element and puts it into the lookup table provided.

Parameters:

name - The target name to be inserted as the text-node child.

collect - A table matching tag names to full document fragments.

Returns:

The input name with a newly creates target-name element.

createTitle

public static Map createTitle(String title,
                              Map collect)

Creates a document fragment with a DTDConstants.FILE element carrying the provided file name in a single text-node child.

Parameters:

file - The xml-file name for the target.

collect - A table matching tag names to full document fragments.

createAbstract

public static Map createAbstract(String text,
                                 Map collect)

Creates a document fragment with a DTDConstants.ABSTRACT element carrying the provided text in a single text-node child.

Parameters:

abstract - The abstract description of the target.

collect - A table matching tag names to full document fragments

createFile

public static Map createFile(String file,
                             Map collect)

Creates a document fragment with a DTDConstants.FILE element carrying the provided file name in a single text-node child.

Parameters:

file - The xml-file name for the target.

collect - A table matching tag names to full document fragments.

createUser

public static Map createUser(String user,
                             Map collect)

Creates a document fragment with a DTDConstants.USER element carrying the provided user name in a single text-node child.

Parameters:

user - The xml-file name for the target.

collect - A table matching tag names to full document fragments.

createEmail

public static Map createEmail(Collection<? extends javax.mail.Address> address,
                              Collection<UserProfile.Notifies> notify,
                              Map collect)

Creates a document fragment with an DTDConstants.EMAIL element carrying The e-mail address of the user plus additional notification elements. The e-mail address is handed over as a string, while the possible notification events are provided in a list of strings.

createInstitution

public static Map createInstitution(UserProfile.Affil inst,
                                    Map collect)

Creates a document fragment with a DTDConstants.INSTITUTION element carrying the provided user name in a single text-node child.

Parameters:

inst - The xml-file name for the target.

collect - A table matching tag names to full document fragments.

createTeam

public static Map createTeam(List<String> team,
                             Map collect)

Creates a document fragment with a DTDConstants.TEAM element carrying the provided user names in a variable-length User fassion.

Parameters:

inst - The xml-file name for the target.

collect - A table matching tag names to full document fragments.

createHistory

public static Map createHistory(Map collect)

Creates an empty histroy element.

createException

public static Map createException(String forwhom,
                                  List block,
                                  int delaymax,
                                  long delaytime,
                                  List delay,
                                  List abort,
                                  int retrymax,
                                  List retry,
                                  List ignore,
                                  Map collect)

Creates an exception element. The lists are lists of strings giving the individual error messages that should lead to the desired operation. If the delay-count, delay-time or the retry-count are zero, the default values are used. Exceptions are alway created for the specified type, if this string is null, 'this' is used.

createSelect

public static Map createSelect(String requires,
                               List constraints,
                               List gains,
                               List timeslots,
                               Map collect)

Creates the select section. This nedda a requires string, a list of constraints and a list of timeslots and gain merits, which are lists of elements, constructed using the createMerit(java.lang.String, java.lang.String, java.lang.String, java.util.Map) method, which, in turn uses the createConstant(java.util.Map<java.lang.String, java.lang.Object>) method. If either of the timeslots and gains list is null, no merit section is produced.

Parameters:

requires - A parable boolean expression.

constraints - A list of ParsedTarget.Constraint.

gains - A list of elements describing a merit.

timeslots - A list of elements describing a merit.

createRate

public static Map createRate(String requires,
                             List constraints,
                             Map collect)

Creates the select section. This nedda a requires string, a list of constraints and a list of timeslots and gain merits, which are lists of elements, constructed using the createMerit(java.lang.String, java.lang.String, java.lang.String, java.util.Map) method, which, in turn uses the createConstant(java.util.Map<java.lang.String, java.lang.Object>) method. If either of the timeslots and gains list is null, no merit section is produced.

Parameters:

requires - A parable boolean expression.

constraints - A list of ParsedTarget.Constraint.

createMerit

public static Element createMerit(String tag,
                                  String classname,
                                  String init,
                                  Map params)

Creates an element that contains everything that builds up a merit. If init is null, no init section is added to the merit-element. If the paramters are null, the constant section is spared.

createDuration

public static Map createDuration(Number dur,
                                 Map collect)

Creates a document fragment with a DTDConstants.DURATION element carrying the provided user name in a single text-node child.

Parameters:

inst - The xml-file name for the target.

collect - A table matching tag names to full document fragments.

createSuccessor

public static Map createSuccessor(String suc,
                                  Map collect)

Creates a document fragment with a DTDConstants.SUCCESSOR element carrying the provided successor file name in a single text-node child.

Parameters:

inst - The xml-file name for the target.

collect - A table matching tag names to full document fragments.

createDaughter

public static Map createDaughter(List dau,
                                 Map collect)

Creates a document fragment with DTDConstants.DAUGHTER elements enclosing the provided daughter target names.

Parameters:

dau - A list of strings.

collect - A table matching tag names to full document fragments.

createSetup

public static Map createSetup(String id,
                              String instrument,
                              List cons,
                              Map collect)

Creates a setup element using an setup-id, an instrument description as a string and a constant element.

createFitsHeader

public static Map createFitsHeader(String id,
                                   List fits,
                                   Map collect)

Creates a single fits-header element from an id and a list of DTDConstants.INTERN elements.

See Also:

createInternFitsHeader(java.lang.String, java.lang.String, java.lang.String)

createInternFitsHeader

public static Element createInternFitsHeader(String key,
                                             String var,
                                             String remark)

Creates a single intern fits-header element with the given key and variable name. If the comment is null, no DTDConstants.COMMENT element is added to the fits-header entry.

createObject

public static Map createObject(Star main,
                               String id,
                               List fov,
                               Map collect)

Creates the object entry. The first SimpleStar points to the main target, while the list provided is a list of SimpleStar s pointing to the field of view. The order of the list is preserved in the xml-document, thus the first list entry is the guide star.

createTargetFromMap

public static Document createTargetFromMap(String access,
                                           String type,
                                           Map docfrag)

Uses a map of essential STELLA-xml top-level elements to pre-created document fragments and puts them together into a single document. The right usage of this method is:

1. Create a new, empty document with the DocumentParser.createEmptyDocument() method. The document obtained is also stored in a static field of the target factory, so the document returned from this method needs not to be copied.
2. Starting with an empty map, add at least all the required elements to the map with the appropriate create... methods. The top-element, DTDConstants.TARGET must not be created. The essential objects are:
   • DTDConstants.TARGETNAME, provide a user-freindly, but SIMBAD resolvable target name.
   • DTDConstants.ABSTRACT, provide a short abstract description. In the TargetHelper class, a standard abstract is included.
   • DTDConstants.USER, provide the user's name.
   • DTDConstants.EMAIL, provide a string array of well-formatted email addresses the notifications should be sent to and a list of notification events. Again, in the target helper class, a standard e-mail notifiaction specification is included.
   • DTDConstants.HISTORY, as this class is for defining new targets, this elements has to be created without specifications.
   • DTDConstants.SELECT, here, a string that is a run-time parsable boolean expression must be specified. Additionally, a list of ParsedTarget.Constraint elements must be given. Scheduling is done by adding lists of Meriting instances. For all these selection criteria, the TargetHelper provides some default settings deduced from the target type.
   • DTDConstants.SETUP, here an id-string, an instrument specification and a list of constants must be given. Again, the standard setup can be constructed with the TargetHelper class, providing the name of the telescope and the exposure time of the target is given.
   Beside these required mappings, the following optional elements (as defined in the target DTD) are supported. At least some of them should not be neglected for standard targets (note importance scale at the end of the descriptions for each element)
   • DTDConstants.FILE, provide a file-name for storing the current xml-target (low importance).
   • DTDConstants.INSTITUTION, used for correct accounting of observing time. The TargetHelper knows some users (medium importance).
   • DTDConstants.EXCEPTION, provide target-depending error handling. The TargetHelper supplies standard setting for these (high importance).
   • DTDConstants.DURATION, provide an estimated duration of one observation of this target as a string, time in ms (low importance).
   • DTDConstants.SUCCESSOR, provide the target-name of a needed successor target. Does not apply to standard targets.
   • DTDConstants.OBJECT, provides the astrometric data of the object and of field-stars, including the guiding stars. Can be resolved with the TargetHelper class if the object name can be resolved by SIMBAD. High importance.
   • DTDConstants.FITSHEADER, give some additional variables you want to be recorded in your fits headers. Low importance
3. After adding all elements to the mapping, call this method. The document returned is now the previously constructed, empty document, appended are the previously created sub-elements. This document has to be copied (e.g. use a ParsedTarget, as it will be deleted in the next step
4. Continue creating new targets as above, by starting with the creation of an empty document.

If one of the essential elements is missing, null is returned. Otherwise, the document returned will be a valid document under the view of the (current) target dtd.

Parameters:

access - enabled or disabled.

type - The sequence type linked to this object.

docfrag - A mapping of top-level elements to document fragments.

Returns:

Null or a valid document.

addList

private static void addList(Element father,
                            List children)

Adds a list of document fragments as childs to the main element.

createElementWithSingleText

private static Map createElementWithSingleText(String tag,
                                               String text,
                                               Map collect)

Creates a document fragment, adds an element with the given tag name to it as the first child and creates a text node that is appended to the new element as a single child.

addTextList

private static Node addTextList(Node father,
                                String type,
                                List text)

Adds errors in the specified section.

appendConstraints

protected static Element appendConstraints(Element select,
                                           List constrain)

Appends a list of non-bull constraints to an element. If a requires section is present, this must already be added prior to this call.

constraintChoice

private static Element constraintChoice(Element c,
                                        Object border)

Takes a comparable object and adds attributes to the element plus the parsable conatraint text.