public class Unretire_Suggestions
extends java.lang.Object
Overlapping Suggestions
If the suggestion in question is an overlap, this class simply resets the DATE_SUCCESS and RETIRING_OBSERVATION_ID fields in the Suggested_Observations table to NULL values. This is all that is required for an overlapping suggestion.
Mapped Suggestions
If the suggestion ID to be unretired is mapped to an acquired observation, the information in the original suggestion must be maintained and matched with the acquired observation. To unretire a mapped suggestion, the following procedure is followed:
Special Case: Unretirement of a first half stereo suggestion with a planned or already acquired second half observation.
During the planning process, suggestions are mapped and retired. However, on occaision, observations may be lost, marked defunct, or the occaisional error can lead to mismapped suggestions. Handling these cases is beyond the current scope of this class, however, the procedure that should be followed is well defined.
If an observation is lost or marked defunct, then the parent suggestion and all overlapping suggestions that may have been retired by the observation will need to be unretired. In these cases, the parent suggestions must be unmapped from the Suggested_Observations_Plannned_Observations_map table prior to instantiating this class and unretiring the suggestions associated with the defunct observation. This ensures that no extraneous suggestion clones will be created when a parent suggestion is unretired.
Similarly, if a suggestion is mismapped, the mismapped parent suggestion should be unmapped and unretired (in that order) prior to mapping and retiring the correct suggestion.
A kind of race condition occurs when a suggestion is unretired before the geometry processing has been completed on the retiring observation ID. This occurs because the second retirement pass is run after the geometry completes, so any suggestion that was retired by an observation, might get re-retired after the geometry completes.
In these cases the UNRETIREMENT_REQUEST_FLAG will be set on the suggestion. When the Retire_Suggestions application encounters a suggestion with the UNRETIREMENT_REQUEST_FLAG set, the suggestion will not be retired, but the flag will be reset.
This class also has a GUI
that can be instantiated, if
needed. The GUI is functional as of this writing but is lacking in some
features. The GUI will be instantianted by the main(String[])
method
if the method is called without arguments on the command line.
Note about database transactions
This class can operate within a transaction context if the constructor is given a jdbc connection which is configured appropriately (ie Connection.setAutoCommit(false)). At the conclusion of the unretirement process, a call to Connection.commit() or Connection.rollback() must be made if AutoCommit is false. Otherwise the class operates in AutoCommit mode.
Retire_Suggestions
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
debugGUIProperty |
static java.lang.String |
debugInitProperty |
static java.lang.String |
debugMainProperty |
static java.lang.String |
debugMethodsProperty |
static java.lang.String |
DEFAULT_CONFIGURATION_FILENAME
The default configuration file for the database class.
|
static java.lang.String |
DO_NOT_UNRETIRE_STRING
This is part of a string appended to the special notes field of a cloned
suggestion.
|
static java.lang.String |
ID
The class identification
|
Constructor and Description |
---|
Unretire_Suggestions(PIRL.Configuration.Configuration configuration)
Instantiate the unretirement class using a configuration.
|
Unretire_Suggestions(java.sql.Connection database_connection)
Instantiates the unretirement class using a jdbc connection object
|
Unretire_Suggestions(PIRL.Database.Database database)
Instantiates the unretirement class using a
Database object |
Modifier and Type | Method and Description |
---|---|
java.lang.String |
Comment()
Get the comment to be appended to the special notes field of the
unretired suggestion.
|
void |
Comment(java.lang.String comment)
Sets the default comment to be appended to the special notes field of
an unretired suggestion.
|
void |
Create_GUI()
Instantiate the Unretirement Graphical User Interface.
|
void |
Create_GUI(boolean noop)
Instantiate the Unretirement GUI in noop mode (no suggestions will be
unretired if noop is true).
|
PIRL.Database.Database |
Database()
Get the database object being used by the class.
|
static void |
main(java.lang.String[] arguments)
Unretire a HiRISE Suggested Observation
|
java.util.Vector<Suggestion> |
Unretire_Observation_ID(java.lang.String observation_id)
This method will find all suggestion retired by the given Observation ID and
unretire all of the suggestions found.
|
java.util.Vector<Suggestion> |
Unretire_Observation_ID(java.lang.String observation_id,
boolean parent_only)
Unretire suggestion id's based on the retiring observation id.
|
java.util.Vector<Suggestion> |
Unretire_Observation_IDs(java.util.Collection<java.lang.String> Observation_IDs)
This method will unretire all suggestions ids that were retired by the
given list observation ids.
|
Suggestion |
Unretire_Suggestion_ID(int suggestion_id,
java.lang.String unretirement_message)
This method does all the heavy lifting of the class, and actually performs
the unretirement procedure.
|
java.util.Vector<Suggestion> |
Unretire_Suggestion_IDs(java.util.Collection<java.lang.Integer> suggestion_ids)
Unretire a collection of Integer Suggestion ID's.
|
java.util.Vector<Suggestion> |
Unretire_Suggestion_List(java.util.Collection<Suggestion> suggestions)
Unretire a Collection of
Suggestion objects. |
static void |
Usage(int exit_status)
Prints command line usage syntax
|
public static final java.lang.String ID
public static final java.lang.String DEFAULT_CONFIGURATION_FILENAME
public static final java.lang.String DO_NOT_UNRETIRE_STRING
public static final java.lang.String debugMainProperty
public static final java.lang.String debugInitProperty
public static final java.lang.String debugMethodsProperty
public static final java.lang.String debugGUIProperty
public Unretire_Suggestions(PIRL.Database.Database database) throws PIRL.Database.Database_Exception, PIRL.Configuration.Configuration_Exception
Database
objectdatabase
- - The Database
object to use for the database connectionPIRL.Configuration.Configuration_Exception
- - if there is a problem with the configuration used to
construct the database object. This shouldn't happen if the provided database
object is already connected to the database.PIRL.Database.Database_Exception
- - if there is a problem establishing a connection to
the database defined in the database object.Database
public Unretire_Suggestions(java.sql.Connection database_connection)
database_connection
- the jdbc connection objectpublic Unretire_Suggestions(PIRL.Configuration.Configuration configuration) throws PIRL.Database.Database_Exception, PIRL.Configuration.Configuration_Exception
configuration
- PIRL.Configuration.Configuration_Exception
- - if there is a problem getting the server and
catalog information from the configuration.PIRL.Database.Database_Exception
- - if there is a problem establishing a connection
to the database defined in the configuration.public java.util.Vector<Suggestion> Unretire_Observation_ID(java.lang.String observation_id, boolean parent_only) throws java.sql.SQLException
observation_id
- the observation id to use to find retired suggestionsparent_only
- only unretire a found suggestion id if it is the parent of
the observation.Suggestion
objects containing information about the unretirement process used for each
suggestion.java.sql.SQLException
- - if any of the underlying database operations failpublic java.util.Vector<Suggestion> Unretire_Observation_ID(java.lang.String observation_id) throws java.sql.SQLException
observation_id
- the observation id to use to find suggestions to retireSuggestion
objects containing information about the unretirement process used for each
suggestion.java.sql.SQLException
- - if any of the underlying database operations fail.Unretire_Observation_ID(String, boolean)
public Suggestion Unretire_Suggestion_ID(int suggestion_id, java.lang.String unretirement_message) throws java.sql.SQLException
suggestion_id
- the suggestion id to be unretired.unretirement_message
- a message to be appended to the special notes
field of the unretired suggestion. If this is null, no message is appended.Suggestion
object
containing status information about the unretirement process.java.sql.SQLException
public java.util.Vector<Suggestion> Unretire_Observation_IDs(java.util.Collection<java.lang.String> Observation_IDs) throws java.sql.SQLException
Suggestion
objects containing information about the results of the unretirement
procedure of each unretired suggestion.java.sql.SQLException
public java.util.Vector<Suggestion> Unretire_Suggestion_IDs(java.util.Collection<java.lang.Integer> suggestion_ids) throws java.sql.SQLException
Note: if an unretirement comment is to be applied to the suggestion, then
the Unretire_Suggestion_List(Collection)
method should be used
instead.
suggestion_ids
- A Collection
of Integer
objects
containing Suggestion ID's to be unretired.Suggestion
objects containing information about the results of the unretirement
procedure of each unretired suggestion.java.sql.SQLException
Unretire_Suggestion_List(Collection)
public java.util.Vector<Suggestion> Unretire_Suggestion_List(java.util.Collection<Suggestion> suggestions) throws java.sql.SQLException
Suggestion
objects.
If the Unretirement Message of the Suggestion
is non-null, then the message will be appended to the Special Notes field in
the
Suggested_Observations
table.suggestions
- - A collection of suggestion objectsSuggestion
objects holding status information about
the unretirement process.java.sql.SQLException
Suggestion
public java.lang.String Comment()
Comment(String)
method or the comment set was an empty string, then
this may be a null value.public PIRL.Database.Database Database()
public void Comment(java.lang.String comment)
comment
- The string to use as an unretirement comment.public void Create_GUI(boolean noop)
noop
- set to true, if no suggestions should be retired.Create_GUI()
public void Create_GUI()
public static void main(java.lang.String[] arguments)
The command line syntax is described by the Usage
method.
Each filename specified will be unretired, some suggestions may need to be cloned rather than simply unretired.
Exit Status Values
0 - Success
1 - Command line syntax problem
2 - An SQL query error occurred
3 - Database Connection Error
4 - No such suggestion id
5 - Configuration Error
6 - Unretirement procedure failed
arguments
- Array of command line argument Strings.Usage(int)
public static void Usage(int exit_status)
Usage: Unretire_Suggestions <Options> Options: - [-Configuration <filename>] [-ID <Suggestion ID>] [-Noop] [-Observation ID <Observation ID>] [-Help]
exit_status
- - the exit status to returnCopyright \ (C) Arizona Board of Regents on behalf of the \ Planetary Image Research Laboratory, Lunar and \ Planetary Laboratory at the University of Arizona