public class Observation_ID_Accumulator
extends java.lang.Object
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.
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.
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.
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.
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.
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.
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.
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.
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.
Modifier and Type | Field and Description |
---|---|
static int |
FAILURE
Exit status for an unsuccessful operation.
|
static java.lang.String |
ID
Class identification name with source code version and date.
|
static java.util.regex.Pattern |
LAST_UPDATE_TEST_PATTERN |
static java.util.regex.Pattern |
ORBIT_RANGE_TEST_PATTERN |
static java.util.regex.Pattern |
PREDICT_TIME_TEST_PATTERN |
static java.util.regex.Pattern |
RAW_SCMF_TEST_PATTERN |
static java.util.regex.Pattern |
SCMF_TEST_PATTERN |
static int |
SUCCESS
Exit status for a successful operation.
|
static java.util.regex.Pattern |
WHERE_CLAUSE_TEST_PATTERN |
Constructor and Description |
---|
Observation_ID_Accumulator()
Creates a new accumulator.
|
Observation_ID_Accumulator(PIRL.Configuration.Configuration configuration)
Creates a new accumulator with the indicated database configuration.
|
Observation_ID_Accumulator(PIRL.Configuration.Configuration configuration,
java.util.List<java.lang.String> sources)
Creates a new accumulator with the indicated database configuration and
initial source list.
|
Observation_ID_Accumulator(PIRL.Configuration.Configuration configuration,
java.util.List<java.lang.String> sources,
boolean requireFormalIds)
Creates a new accumulator with the indicated database configuration, initial
source list, and formal ID requirement.
|
Observation_ID_Accumulator(java.util.List<java.lang.String> sources)
Creates a new accumulator with the inidicated initial source list.
|
Observation_ID_Accumulator(java.util.List<java.lang.String> sources,
boolean requireFormalIds)
Creates a new accumulator with the indicated initial source list and formal
ID requriement.
|
Modifier and Type | Method and Description |
---|---|
void |
addLastUpdateSourceFrom(java.lang.String table,
java.lang.String source,
boolean requireFormalIds)
Adds a last-update source of observation IDs to the accumulator.
|
void |
addSource(java.lang.String source)
Adds a source of observation IDs to the accumulator.
|
void |
addSource(java.lang.String source,
boolean requireFormalIds)
Adds a source of observation IDs to the accumulator.
|
void |
addSources(java.util.List<java.lang.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.
|
java.util.List<java.lang.String> |
getObservationIds()
Gets the accumulator's list of accumulated observation IDs.
|
java.util.List<java.lang.String> |
getRejectedIds()
Gets the accumulator's list of accumulated rejected IDs.
|
java.util.List<java.lang.String> |
getSourceList()
Gets the accumulator's list of sources.
|
static boolean |
isIdSource(java.lang.String text)
Tests whether a text item is a database-style observation ID source.
|
static boolean |
isLastUpdateSource(java.lang.String text)
Tests whether a text item is a last-update observation ID source.
|
static void |
main(java.lang.String[] args)
Invokes a test stub for exercising the accumulator.
|
static java.lang.String |
makeLastUpdateSource()
Creates a last-update ID source covering yesterday and today.
|
static java.lang.String |
makeLastUpdateSource(int deltaStart,
int deltaStop)
Creates a last-update ID source covering the indicated range of days
relative to today.
|
static java.lang.String |
makePredictTimeSource()
Creates a predict-time ID source covering yesterday, today, and tomorrow.
|
static java.lang.String |
makePredictTimeSource(int deltaStart,
int deltaStop)
Creates a predict-time ID source covering the indicated range of days
relative to today.
|
public static final java.lang.String ID
public static final java.util.regex.Pattern ORBIT_RANGE_TEST_PATTERN
public static final java.util.regex.Pattern PREDICT_TIME_TEST_PATTERN
public static final java.util.regex.Pattern LAST_UPDATE_TEST_PATTERN
public static final java.util.regex.Pattern SCMF_TEST_PATTERN
public static final java.util.regex.Pattern RAW_SCMF_TEST_PATTERN
public static final java.util.regex.Pattern WHERE_CLAUSE_TEST_PATTERN
public static final int SUCCESS
public static final int FAILURE
public Observation_ID_Accumulator(PIRL.Configuration.Configuration configuration, java.util.List<java.lang.String> sources, boolean requireFormalIds) throws Invalid_Argument_Exception, java.io.IOException
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.
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.Invalid_Argument_Exception
- if the configuration does not correctly
specify a database.java.io.IOException
- if a file or URL source cannot be read.public Observation_ID_Accumulator(java.util.List<java.lang.String> sources, boolean requireFormalIds) throws java.io.IOException
An accumulator created with this constructor will not have database access; orbit range and predict time range sources will therefore yield no IDs.
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.java.io.IOException
- if a file or URL source cannot be read.public Observation_ID_Accumulator(PIRL.Configuration.Configuration configuration, java.util.List<java.lang.String> sources) throws Invalid_Argument_Exception, java.io.IOException
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.
configuration
- the database configuration.sources
- an initial list of observation ID sources.Invalid_Argument_Exception
- if the configuration does not correctly
specify a database.java.io.IOException
- if a file or URL source cannot be read.public Observation_ID_Accumulator(java.util.List<java.lang.String> sources) throws java.io.IOException
An accumulator created with this constructor will not have database access; orbit range and predict time range sources will therefore yield no IDs.
sources
- an initial list of observation ID sources.java.io.IOException
- if a file or URL source cannot be read.public Observation_ID_Accumulator(PIRL.Configuration.Configuration configuration) throws Invalid_Argument_Exception
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.
configuration
- the database configuration.Invalid_Argument_Exception
- if the configuration does not correctly
specify a database.public Observation_ID_Accumulator()
An accumulator created with this constructor will not have database access; orbit range and predict time range sources will therefore yield no IDs.
public java.util.List<java.lang.String> getObservationIds()
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.
public java.util.List<java.lang.String> getRejectedIds()
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.
public java.util.List<java.lang.String> getSourceList()
public void addSources(java.util.List<java.lang.String> sources, boolean requireFormalIds) throws java.io.IOException
sources
- the list of observation ID sources.requireFormalIds
- if true, only formal HiRISE observation
IDs are added to the list.java.io.IOException
- if a PTF or unformatted text source cannot be read.addSource(String,boolean)
public void addSource(java.lang.String source, boolean requireFormalIds) throws java.io.IOException
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.
source
- the source of observation IDs.requireFormalIds
- if true, only formal HiRISE observation
IDs are added to the list.java.io.IOException
public void addSource(java.lang.String source) throws java.io.IOException
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
.
source
- the source of observation IDs.java.io.IOException
- if a PTF or unformatted text source cannot be read.public void clear()
public void addLastUpdateSourceFrom(java.lang.String table, java.lang.String source, boolean requireFormalIds)
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.
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.public static java.lang.String makeLastUpdateSource(int deltaStart, int deltaStop)
Note that a stop value greater than 0 is meaningless except for Time Lords and Jules Verne.
deltaStart
- the start value in days relative to today.deltaStop
- the stop value in days relative to today.public static java.lang.String makeLastUpdateSource()
public static java.lang.String makePredictTimeSource(int deltaStart, int deltaStop)
deltaStart
- the start value in days relative to today.deltaStop
- the stop value in days relative to today.public static java.lang.String makePredictTimeSource()
public static boolean isIdSource(java.lang.String text)
text
- the text in question.public static boolean isLastUpdateSource(java.lang.String text)
text
- the text in question.public static void main(java.lang.String[] args) throws java.lang.Throwable
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.)
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.
Configuration_Helper.getConfiguration(String,String,String...)
for details
on the configuration pathname; if this option is not used, the config source
argument is null.
args
- the command-line arguments.java.lang.Throwable
Copyright \ (C) Arizona Board of Regents on behalf of the \ Planetary Image Research Laboratory, Lunar and \ Planetary Laboratory at the University of Arizona