HiRISE

HiRISE.HiPlan.IO
Class Observation_ID_Accumulator

java.lang.Object
  extended by HiRISE.HiPlan.IO.Observation_ID_Accumulator

public class Observation_ID_Accumulator
extends Object

A mechanism for accumulating observation IDs from a variety of input sources.

The accumulator recognizes six different source types: the payload target file (PTF), the unformatted text source, an orbit range, a predict time range, a last update time range, an SCMF specification, a general database where-clause, and a raw observation ID token.

When obtaining observation IDs from a source, the accumulator can be set to require that all such IDs be formal HiRISE observation IDs, i.e., those that conform to the Observation_ID format. By default, this requirement is enforced. An "informal" ID is any string token; because the database does not itself enforce the formal HiRISE observation ID standard, any string token can be used as an ID in its OBSERVATION_ID fields.

PTF Source

A PTF source is a file or URL source whose first line matches the following regular expression:

        ^#\s*FILE_TYPE:.*PTF

Such a source is presumed be a PTF, following the format outlined in the PTF SIS, consisting of one or more PTF records. The team database ID field of each HiRISE record in the PTF is added to the accumulator's list. A HiRISE record is a PTF record whose instrument set field value starts with the character H.

Unformatted Text Source

An unformatted text source is a file or URL source whose first line does not match the aforementioned regular expression. Each line of such a source is a whitespace- and/or comma-separated list of observation IDs. A # character marks a comment; all text following on that line is ignored.

Orbit Range Source

An orbit range source is of the following form:

        o[rbit]:START_ORBIT[,STOP_ORBIT][/d]

The orbit range source selects IDs from the database described by the Configuration used in the construction of the accumulator. The source yields the IDs of those observations whose orbit number is within the indicated orbit range. START_ORBIT and the optional STOP_ORBIT are integers; if STOP_ORBIT is not supplied, the source yields the IDs for those observations on the START_ORBIT only.

By default, observations whose STATUS is DEFUNCT are not returned. If the optional /d switch is supplied, however, defunct observations are included in the results for this source only.

If the accumulator is constructed without a database configuration, this source yields no IDs.

Predict Time Range Source

A predict time range source is of the following form:

        p[redict]:START_TIME[,STOP_TIME][/d]

The predict time range source selects IDs from the database described by the Configuration used in the construction of the accumulator. The source yields the IDs of those observations whose predict time is within the indicated predict time range. START_TIME and the optional STOP_TIME are of the form yyyy[-DDD[THH:mm[:ss]]] (as per the SimpleDateFormat codes). If the time component is not supplied, 00:00:00 is used; if the seconds are not supplied, :00 is assumed. If the day-of-year component is not supplied, 001 is used. If the STOP_TIME is not supplied, the START_TIME is incremented by one year, one day, or one hour, depending on the precision of the START_TIME.

START_TIME and STOP_TIME may also be expressed as a number of days relative to today (UTC). In this case, they are of the form [+/-]ddd. If STOP_TIME is not supplied, only the relative start day is used.

As an example of using relative predict times, suppose today is day-of-year 175. The the source identifier predict:-1,1 will cover yesterday (DOY 174) through tomorrow (DOY 176), inclusive. predict:-1 will cover tomorrow only (DOY 174), and predict:0 will refer to today alone.

By default, observations whose STATUS is DEFUNCT are not returned. If the optional /d switch is supplied, however, defunct observations are included in the results for this source only.

If the accumulator is constructed without a database configuration, this source yields no IDs.

Last Update Time Range Source

A last update time range source is of the following form:

        l[ast[_update]]:START_TIME[,STOP_TIME][/d]

The last update time range source selects IDs from the database described by the Configuration used in the construction of the accumulator. The source yields the IDs of those observations whose last update database field is within the indicated time range. START_TIME and the optional STOP_TIME are of the form yyyy[-MM[-dd[ HH:mm:ss]]] (as per the SimpleDateFormat codes; this format is the MySQL database date format, used for the LAST_UPDATE field in HiCat). If the time component is not supplied, 00:00:00 is used. If the day of the month is not supplied, 01 is used. If the month is not supplied, 01 is used. If the STOP_TIME is not supplied, the START_TIME is incremented by one year, one month, one day, or one hour, depending on the precision of the START_TIME. Note that the last update format uses a space between the time and the date components. It will need to be protected on the command line from the user's shell.

START_TIME and STOP_TIME may also be expressed as a number of days relative to today (UTC). In this case, they are of the form [+/-]ddd. If STOP_TIME is not supplied, only the relative start day is used.

As an example of using relative last update times, suppose today is June 24. The the source identifier last_udpate:-1,0 will cover yesterday (June 23) through today (June 24), inclusive. last_update:-1 will cover tomorrow only (June 23), and last_update:0 refers to today alone.

By default, observations whose STATUS is DEFUNCT are not returned. If the optional /d switch is supplied, however, defunct observations are included in the results for this source only.

If the accumulator is constructed without a database configuration, this source yields no IDs.

SCMF Source

A spacecraft command message file source is one of the following forms:

        s[cmf]:VALUE1[,VALUE2[,...]][/d]

        rnNNNNN[/d]

The SCMF source selects IDs from the database described by the Configuration used in the construction of the accumulator. The source yields the IDs of those observations whose SCMF field value matches one of the input values. The SCMF name is generally of the form rnNNNNN, where NNNNN is a four- or five-digit, zero-padded integer. Note that the first form of the source, with the scmf: prefix, does not check the format of the SCMF name, while the second form does. Note also that the first form may include a comma-separated list of SCMFs, while the second is a single SCMF only.

By default, observations whose STATUS is DEFUNCT are not returned. If the optional /d switch is supplied, however, defunct observations are included in the results for this source only.

If the accumulator is constructed without a database configuration, this source yields no IDs.

Where-Clause Source

A where-clause source is of the following form:

        w[here]:SQL_WHERE_CLAUSE

The where-clause source selects IDs from the database described by the Configuration used in the construction of the accumulator. The source yields the IDs of those observations that match the SQL where clause specified. Note that the where-clause does not include the WHERE token, and note also that one's shell may require elements in the where-clause to be escaped.

Observation ID Token Source

An observation ID token is any source that is none of the above; it is presumed to be an observation ID on its own, and it is added to the collection as such.

Version:
1.36
Author:
Drew Davidson, Shawn Wheelock, Michelle Martinez, Christian Schaller - UA/PIRL
See Also:
"Payload Target File and Integrated Payload Target File Software Interface Specification (JPL MRO SEQ032)"

Field Summary
static int FAILURE
          Exit status for an unsuccessful operation.
static String ID
          Class identification name with source code version and date.
static Pattern LAST_UPDATE_TEST_PATTERN
           
static Pattern ORBIT_RANGE_TEST_PATTERN
           
static Pattern PREDICT_TIME_TEST_PATTERN
           
static Pattern RAW_SCMF_TEST_PATTERN
           
static Pattern SCMF_TEST_PATTERN
           
static int SUCCESS
          Exit status for a successful operation.
static Pattern WHERE_CLAUSE_TEST_PATTERN
           
 
Constructor Summary
Observation_ID_Accumulator()
          Creates a new accumulator.
Observation_ID_Accumulator(Configuration configuration)
          Creates a new accumulator with the indicated database configuration.
Observation_ID_Accumulator(Configuration configuration, List<String> sources)
          Creates a new accumulator with the indicated database configuration and initial source list.
Observation_ID_Accumulator(Configuration configuration, List<String> sources, boolean requireFormalIds)
          Creates a new accumulator with the indicated database configuration, initial source list, and formal ID requirement.
Observation_ID_Accumulator(List<String> sources)
          Creates a new accumulator with the inidicated initial source list.
Observation_ID_Accumulator(List<String> sources, boolean requireFormalIds)
          Creates a new accumulator with the indicated initial source list and formal ID requriement.
 
Method Summary
 void addLastUpdateSourceFrom(String table, String source, boolean requireFormalIds)
          Adds a last-update source of observation IDs to the accumulator.
 void addSource(String source)
          Adds a source of observation IDs to the accumulator.
 void addSource(String source, boolean requireFormalIds)
          Adds a source of observation IDs to the accumulator.
 void addSources(List<String> sources, boolean requireFormalIds)
          Adds each element of a list of observation ID sources to the accumulator.
 void clear()
          Clears the accumulator's list of observation IDs and sources.
 List<String> getObservationIds()
          Gets the accumulator's list of accumulated observation IDs.
 List<String> getRejectedIds()
          Gets the accumulator's list of accumulated rejected IDs.
 List<String> getSourceList()
          Gets the accumulator's list of sources.
static boolean isIdSource(String text)
          Tests whether a text item is a database-style observation ID source.
static boolean isLastUpdateSource(String text)
          Tests whether a text item is a last-update observation ID source.
static void main(String[] args)
          Invokes a test stub for exercising the accumulator.
static String makeLastUpdateSource()
          Creates a last-update ID source covering yesterday and today.
static String makeLastUpdateSource(int deltaStart, int deltaStop)
          Creates a last-update ID source covering the indicated range of days relative to today.
static String makePredictTimeSource()
          Creates a predict-time ID source covering yesterday, today, and tomorrow.
static String makePredictTimeSource(int deltaStart, int deltaStop)
          Creates a predict-time ID source covering the indicated range of days relative to today.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values

ORBIT_RANGE_TEST_PATTERN

public static final Pattern ORBIT_RANGE_TEST_PATTERN

PREDICT_TIME_TEST_PATTERN

public static final Pattern PREDICT_TIME_TEST_PATTERN

LAST_UPDATE_TEST_PATTERN

public static final Pattern LAST_UPDATE_TEST_PATTERN

SCMF_TEST_PATTERN

public static final Pattern SCMF_TEST_PATTERN

RAW_SCMF_TEST_PATTERN

public static final Pattern RAW_SCMF_TEST_PATTERN

WHERE_CLAUSE_TEST_PATTERN

public static final Pattern WHERE_CLAUSE_TEST_PATTERN

SUCCESS

public static final int SUCCESS
Exit status for a successful operation.

See Also:
Constant Field Values

FAILURE

public static final int FAILURE
Exit status for an unsuccessful operation.

See Also:
Constant Field Values
Constructor Detail

Observation_ID_Accumulator

public Observation_ID_Accumulator(Configuration configuration,
                                  List<String> sources,
                                  boolean requireFormalIds)
                           throws Invalid_Argument_Exception,
                                  IOException
Creates a new accumulator with the indicated database configuration, initial source list, and formal ID requirement.

The accumulator's database is obtained via the DatabaseFactory. The database connection is checked prior to all queries. If open, it is left open after the query; if closed, it is opened for the query only and closed again immediately afterward.

Parameters:
configuration - the database configuration.
sources - an initial list of observation ID sources.
requireFormalIds - if true, the IDs obtained from the initial list of sources will be restricted to formal HiRISE observation IDs only.
Throws:
Invalid_Argument_Exception - if the configuration does not correctly specify a database.
IOException - if a file or URL source cannot be read.

Observation_ID_Accumulator

public Observation_ID_Accumulator(List<String> sources,
                                  boolean requireFormalIds)
                           throws IOException
Creates a new accumulator with the indicated initial source list and formal ID requriement.

An accumulator created with this constructor will not have database access; orbit range and predict time range sources will therefore yield no IDs.

Parameters:
sources - an initial list of observation ID sources.
requireFormalIds - if true, the IDs obtained from the initial list of sources will be restricted to formal HiRISE observation IDs only.
Throws:
IOException - if a file or URL source cannot be read.

Observation_ID_Accumulator

public Observation_ID_Accumulator(Configuration configuration,
                                  List<String> sources)
                           throws Invalid_Argument_Exception,
                                  IOException
Creates a new accumulator with the indicated database configuration and initial source list. IDs are obtained from the initial sources with the requirement that they be formal HiRISE observation IDs; this setting does not affect subsequent sources added via the various addSource methods.

The accumulator's database is obtained via the DatabaseFactory. The database connection is checked prior to all queries. If open, it is left open after the query; if closed, it is opened for the query only and closed again immediately afterward.

Parameters:
configuration - the database configuration.
sources - an initial list of observation ID sources.
Throws:
Invalid_Argument_Exception - if the configuration does not correctly specify a database.
IOException - if a file or URL source cannot be read.

Observation_ID_Accumulator

public Observation_ID_Accumulator(List<String> sources)
                           throws IOException
Creates a new accumulator with the inidicated initial source list. IDs are obtained from the initial sources with the requirement that they be formal HiRISE observation IDs; this setting does not affect subsequent sources added via the various addSource methods.

An accumulator created with this constructor will not have database access; orbit range and predict time range sources will therefore yield no IDs.

Parameters:
sources - an initial list of observation ID sources.
Throws:
IOException - if a file or URL source cannot be read.

Observation_ID_Accumulator

public Observation_ID_Accumulator(Configuration configuration)
                           throws Invalid_Argument_Exception
Creates a new accumulator with the indicated database configuration.

The accumulator's database is obtained via the DatabaseFactory. The database connection is checked prior to all queries. If open, it is left open after the query; if closed, it is opened for the query only and closed again immediately afterward.

Parameters:
configuration - the database configuration.
Throws:
Invalid_Argument_Exception - if the configuration does not correctly specify a database.

Observation_ID_Accumulator

public Observation_ID_Accumulator()
Creates a new accumulator.

An accumulator created with this constructor will not have database access; orbit range and predict time range sources will therefore yield no IDs.

Method Detail

getObservationIds

public List<String> getObservationIds()
Gets the accumulator's list of accumulated observation IDs. The IDs are returned in no particular order.

IDs from a particular source will be formal HiRISE observation IDs if and only if they were required to be so when the source was added.

Returns:
the list of accumulated observation IDs.

getRejectedIds

public List<String> getRejectedIds()
Gets the accumulator's list of accumulated rejected IDs. The IDs are returned in no particular order.

IDs from a particular source are added to this list if and only if the source's IDs were required to be formal HiRISE observation IDs and the particular IDs were not formal.

Returns:
the list of accumulated rejected IDs.

getSourceList

public List<String> getSourceList()
Gets the accumulator's list of sources. The sources are returned in no particular order.

Returns:
the list of ID sources.

addSources

public void addSources(List<String> sources,
                       boolean requireFormalIds)
                throws IOException
Adds each element of a list of observation ID sources to the accumulator.

Parameters:
sources - the list of observation ID sources.
requireFormalIds - if true, only formal HiRISE observation IDs are added to the list.
Throws:
IOException - if a PTF or unformatted text source cannot be read.
See Also:
addSource(String,boolean)

addSource

public void addSource(String source,
                      boolean requireFormalIds)
               throws IOException
Adds a source of observation IDs to the accumulator.

The source is immediately checked for observation IDs and the IDs are immediately added to the accumulated list. If requireFormalIds is true, only formal HiRISE observation IDs are added to the list of IDs; IDs that do not conform are added to the list of rejected IDs. If requireFormalIds is false, all IDs are added to the list of IDs.

Parameters:
source - the source of observation IDs.
requireFormalIds - if true, only formal HiRISE observation IDs are added to the list.
Throws:
IOException

addSource

public void addSource(String source)
               throws IOException
Adds a source of observation IDs to the accumulator.

The source is immediately checked for observation IDs and the IDs are immediately added to the accumulated list. Only formal HiRISE observation IDs are considered, which are added to the list of IDs; IDs that do not confrom are added to the list of rejected IDs.

Parameters:
source - the source of observation IDs.
Throws:
IOException - if a PTF or unformatted text source cannot be read.

clear

public void clear()
Clears the accumulator's list of observation IDs and sources. This operation effectively resets the accumulator.


addLastUpdateSourceFrom

public void addLastUpdateSourceFrom(String table,
                                    String source,
                                    boolean requireFormalIds)
Adds a last-update source of observation IDs to the accumulator. The IDs are gathered from the indicated table, rather than from the standard table (Planned_Observations). The last-update source's /d option is ignored.

The source is immediately checked for observation IDs and the IDs are immediately added to the accumulated list. If requireFormalIds is true, only formal HiRISE observation IDs are added to the list of IDs; IDs that do not conform are added to the list of rejected IDs. If requireFormalIds is false, all IDs are added to the list of IDs.

The source is added to the accumulator's list of ID sources.

Note that if the source is not a last-update source, no IDs will be added, but the source itself will still be added to the accumulator's list of sources.

All HiRISE HiCat tables include a LAST_UPDATE field, but not all tables include an OBSERVATION_ID field. If the table has no observation ID field, this method adds no IDs, but the source will still be added to the accumulator's list of sources.

Parameters:
table - the HiCat table from which to gather observation IDs based on the LAST_UPDATE field.
source - the source of observation IDs.
requireFormalIds - if true, only formal HiRISE observation IDs are added to the list.

makeLastUpdateSource

public static String makeLastUpdateSource(int deltaStart,
                                          int deltaStop)
Creates a last-update ID source covering the indicated range of days relative to today. If the stop value is less than the start value, the values are swapped to be in the proper order.

Note that a stop value greater than 0 is meaningless except for Time Lords and Jules Verne.

Parameters:
deltaStart - the start value in days relative to today.
deltaStop - the stop value in days relative to today.
Returns:
last:deltaStart,deltaStop/d.

makeLastUpdateSource

public static String makeLastUpdateSource()
Creates a last-update ID source covering yesterday and today.

Returns:
last:-1,0/d.

makePredictTimeSource

public static String makePredictTimeSource(int deltaStart,
                                           int deltaStop)
Creates a predict-time ID source covering the indicated range of days relative to today. If the stop value is less than the start value, the values are swapped to be in the proper order.

Parameters:
deltaStart - the start value in days relative to today.
deltaStop - the stop value in days relative to today.
Returns:
predict:deltaStart,deltaStop/d.

makePredictTimeSource

public static String makePredictTimeSource()
Creates a predict-time ID source covering yesterday, today, and tomorrow.

Returns:
predict:-1,1/d.

isIdSource

public static boolean isIdSource(String text)
Tests whether a text item is a database-style observation ID source. Such sources refer to the configured database rather than a file (PTF or text) or ID token: orbit range, predict time, last update, SCMF, and general where-clause.

Parameters:
text - the text in question.
Returns:
true if the text can be interpreted as a database ID source; false if not.

isLastUpdateSource

public static boolean isLastUpdateSource(String text)
Tests whether a text item is a last-update observation ID source.

Parameters:
text - the text in question.
Returns:
true if the text can be interpreted as a last-update source; false if it cannot.

main

public static void main(String[] args)
                 throws Throwable
Invokes a test stub for exercising the accumulator.

Get_Observation_IDs is a decent test of the accumulator as well, and it includes a Perl wrapper to handle the proper setting of one's classpath and so forth. (In fact, invoking the application with the --test command-line option will run this test stub instead of the Get_Observation_IDs application.)

Usage

Observation_ID_Accumulator [--configuration configuration_pathname] observation_id_source [...]

Options are not case-sensitive and may be reduced to their shortest unique form. One or two dashes may be used.

Options

--configuration configuration_pathname
Sets the pathname of the configuration file from which to configure the application. See Configuration_Helper.getConfiguration(String,String,String...) for details on the configuration pathname; if this option is not used, the config source argument is null.

Parameters:
args - the command-line arguments.
Throws:
Throwable

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona