HiRISE

HiRISE.HiCat.Utilities
Class Unretire_Suggestions

java.lang.Object
  extended by HiRISE.HiCat.Utilities.Unretire_Suggestions

public class Unretire_Suggestions
extends Object

Unretire_Suggestions is a utility class performing the operations needed to "unretire" a HiRISE Suggested_Observation. There are two different cases of unretirement which this class handles:

  1. Unretirement of a suggestion which overlaps an acquired observation, but is not the parent suggestion of the retiring observation.
  2. Unretirement of a suggestion which is the direct parent suggestion of an acquired observation.

Unretirement Procedures

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:

  1. A new suggestion is created that is a clone of the original.
  2. The ID of the clone is substituted into the Suggested_Observations_Planned_Observations_map for the original suggestion ID, this maintains the suggestion information needed for the acquired observation. This operation also unmaps the original suggestion ID.
  3. The original suggestion ID is unretired just like an overlapping suggestion.
  4. Any stereo or seasonal settings that may exist in the clone are reset to make the cloned suggestion a "stand-alone" suggestion independent of any other observations or suggestions.

Special Case: Unretirement of a first half stereo suggestion with a planned or already acquired second half observation.

  1. A new suggestion is created that is a clone of the first half stereo suggestion.
  2. The acquired observation is remapped to the cloned suggestion
  3. The cloned suggestion is set to be nonstereo.
  4. The second half observation is remapped to the first half suggestion.
  5. The second half suggestion is unretired, making it available for planning once again.

Suggestion Unretirement and Observation Planning

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.

Unretiring Suggestions With Incomplete Geometry

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.

Graphical User Interface

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.

TODO

Most of the remaining work to be done is on the GUI:
  1. GUI layout improvements may be needed.
  2. Additional filtering capabilities may be required in the future when the list of retired suggestions becomes so large that performance of the GUI degrades.

Version:
1.62 2017/05/30 21:39:41
Author:
Rodney Heyd UA/PIRL
See Also:
Retire_Suggestions

Field Summary
static String debugGUIProperty
           
static String debugInitProperty
           
static String debugMainProperty
           
static String debugMethodsProperty
           
static String DEFAULT_CONFIGURATION_FILENAME
          The default configuration file for the database class.
static String DO_NOT_UNRETIRE_STRING
          This is part of a string appended to the special notes field of a cloned suggestion.
static String ID
          The class identification
 
Constructor Summary
Unretire_Suggestions(Configuration configuration)
          Instantiate the unretirement class using a configuration.
Unretire_Suggestions(Connection database_connection)
          Instantiates the unretirement class using a jdbc connection object
Unretire_Suggestions(Database database)
          Instantiates the unretirement class using a Database object
 
Method Summary
 String Comment()
          Get the comment to be appended to the special notes field of the unretired suggestion.
 void Comment(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).
 Database Database()
          Get the database object being used by the class.
static void main(String[] arguments)
          Unretire a HiRISE Suggested Observation
 Vector<Suggestion> Unretire_Observation_ID(String observation_id)
          This method will find all suggestion retired by the given Observation ID and unretire all of the suggestions found.
 Vector<Suggestion> Unretire_Observation_ID(String observation_id, boolean parent_only)
          Unretire suggestion id's based on the retiring observation id.
 Vector<Suggestion> Unretire_Observation_IDs(Collection<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, String unretirement_message)
          This method does all the heavy lifting of the class, and actually performs the unretirement procedure.
 Vector<Suggestion> Unretire_Suggestion_IDs(Collection<Integer> suggestion_ids)
          Unretire a collection of Integer Suggestion ID's.
 Vector<Suggestion> Unretire_Suggestion_List(Collection<Suggestion> suggestions)
          Unretire a Collection of Suggestion objects.
static void Usage(int exit_status)
          Prints command line usage syntax
 
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
The class identification

See Also:
Constant Field Values

DEFAULT_CONFIGURATION_FILENAME

public static final String DEFAULT_CONFIGURATION_FILENAME
The default configuration file for the database class.

See Also:
Constant Field Values

DO_NOT_UNRETIRE_STRING

public static final String DO_NOT_UNRETIRE_STRING
This is part of a string appended to the special notes field of a cloned suggestion. The unretirement gui will search the special notes field for this string and will now allow suggestion clones to be unretired.

See Also:
Constant Field Values

debugMainProperty

public static final String debugMainProperty
See Also:
Constant Field Values

debugInitProperty

public static final String debugInitProperty
See Also:
Constant Field Values

debugMethodsProperty

public static final String debugMethodsProperty
See Also:
Constant Field Values

debugGUIProperty

public static final String debugGUIProperty
See Also:
Constant Field Values
Constructor Detail

Unretire_Suggestions

public Unretire_Suggestions(Database database)
                     throws Database_Exception,
                            Configuration_Exception
Instantiates the unretirement class using a Database object

Parameters:
database - - The Database object to use for the database connection
Throws:
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.
Database_Exception - - if there is a problem establishing a connection to the database defined in the database object.
See Also:
Database

Unretire_Suggestions

public Unretire_Suggestions(Connection database_connection)
Instantiates the unretirement class using a jdbc connection object

Parameters:
database_connection - the jdbc connection object

Unretire_Suggestions

public Unretire_Suggestions(Configuration configuration)
                     throws Database_Exception,
                            Configuration_Exception
Instantiate the unretirement class using a configuration.

Parameters:
configuration -
Throws:
Configuration_Exception - - if there is a problem getting the server and catalog information from the configuration.
Database_Exception - - if there is a problem establishing a connection to the database defined in the configuration.
Method Detail

Unretire_Observation_ID

public Vector<Suggestion> Unretire_Observation_ID(String observation_id,
                                                  boolean parent_only)
                                           throws SQLException
Unretire suggestion id's based on the retiring observation id. This method will search for all suggestions that have been retired by the given observation id, an unretire them.

Parameters:
observation_id - the observation id to use to find retired suggestions
parent_only - only unretire a found suggestion id if it is the parent of the observation.
Returns:
A vector of Suggestion objects containing information about the unretirement process used for each suggestion.
Throws:
SQLException - - if any of the underlying database operations fail

Unretire_Observation_ID

public Vector<Suggestion> Unretire_Observation_ID(String observation_id)
                                           throws SQLException
This method will find all suggestion retired by the given Observation ID and unretire all of the suggestions found.

Parameters:
observation_id - the observation id to use to find suggestions to retire
Returns:
A Vector of Suggestion objects containing information about the unretirement process used for each suggestion.
Throws:
SQLException - - if any of the underlying database operations fail.
See Also:
Unretire_Observation_ID(String, boolean)

Unretire_Suggestion_ID

public Suggestion Unretire_Suggestion_ID(int suggestion_id,
                                         String unretirement_message)
                                  throws SQLException
This method does all the heavy lifting of the class, and actually performs the unretirement procedure.

Parameters:
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.
Returns:
A Suggestion object containing status information about the unretirement process.
Throws:
SQLException

Unretire_Observation_IDs

public Vector<Suggestion> Unretire_Observation_IDs(Collection<String> Observation_IDs)
                                            throws SQLException
This method will unretire all suggestions ids that were retired by the given list observation ids.

Returns:
A vector of Suggestion objects containing information about the results of the unretirement procedure of each unretired suggestion.
Throws:
SQLException

Unretire_Suggestion_IDs

public Vector<Suggestion> Unretire_Suggestion_IDs(Collection<Integer> suggestion_ids)
                                           throws SQLException
Unretire a collection of Integer Suggestion ID's.

Note: if an unretirement comment is to be applied to the suggestion, then the Unretire_Suggestion_List(Collection) method should be used instead.

Parameters:
suggestion_ids - A Collection of Integer objects containing Suggestion ID's to be unretired.
Returns:
A vector of Suggestion objects containing information about the results of the unretirement procedure of each unretired suggestion.
Throws:
SQLException
See Also:
Unretire_Suggestion_List(Collection)

Unretire_Suggestion_List

public Vector<Suggestion> Unretire_Suggestion_List(Collection<Suggestion> suggestions)
                                            throws SQLException
Unretire a Collection of 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.

Parameters:
suggestions - - A collection of suggestion objects
Returns:
- A vector containing Suggestion objects holding status information about the unretirement process.
Throws:
SQLException
See Also:
Suggestion

Comment

public String Comment()
Get the comment to be appended to the special notes field of the unretired suggestion.

Returns:
the comment string. If a comment was not set via the Comment(String) method or the comment set was an empty string, then this may be a null value.

Database

public Database Database()
Get the database object being used by the class.

Returns:
The database object used by the class, null if a jdbc connection object was used to instantiate the class.

Comment

public void Comment(String comment)
Sets the default comment to be appended to the special notes field of an unretired suggestion. No comment will be appended of the comment string is empty or null.

Parameters:
comment - The string to use as an unretirement comment.

Create_GUI

public void Create_GUI(boolean noop)
Instantiate the Unretirement GUI in noop mode (no suggestions will be unretired if noop is true).

Parameters:
noop - set to true, if no suggestions should be retired.
See Also:
Create_GUI()

Create_GUI

public void Create_GUI()
Instantiate the Unretirement Graphical User Interface.


main

public static void main(String[] arguments)
Unretire a HiRISE Suggested Observation

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

Parameters:
arguments - Array of command line argument Strings.
See Also:
Usage(int)

Usage

public static void Usage(int exit_status)
Prints command line usage syntax

Usage: Unretire_Suggestions <Options>
  Options: -
    [-Configuration <filename>]
    [-ID <Suggestion ID>]
    [-Noop]
    [-Observation ID <Observation ID>]
    [-Help]

Parameters:
exit_status - - the exit status to return

HiRISE

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