HiRISE

HiRISE.HiCat.Utilities
Class Retire_Suggestions

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

public class Retire_Suggestions
extends Object

Retire_Suggestions is a utility class which marks HiRISE Suggested Observations as "retired." In this context, retirement means that the DATE_SUCCESS field for the suggestion will be set to the current time, and similarly the RETIRING_OBSERVATION_ID field will be set to the input observation ID. Given a HiRISE Observation ID, this class will retire the parent suggestion of an observation, and then attempt to retire any nearby suggestions which overlap the acquired observation.

Retirement Algorithm

The retirement algorithm consists of several rules:

Parent Suggestion Rule

The parent suggestion of the given observation is always retired. Even if the observation does not overlap the parent suggestion sufficiently to retire the suggestion based on any of the following rules. This must be done to ensure suggestion retirement under circumstances of a delay by, where the observation might get shifted enough to not sufficiently overlap the parent suggestion.

Overlapping Areas Rule

This rule aplies to suggestions that have not been mapped to the input Observation. This rule has two parts:

  1. A Suggestion will be retired if the observation center coordinates fall within the region of interest of the suggested observation. --OR--
  2. A Suggestion will be retired if the suggestion center coordinates fall within the foot print of the acquired observation

Overlapping Seasonals Rule

If a set of seasonal suggestions overlaps an observation, but no member of the seasonal set is mapped to the observation, then only suggestions in the seasonal set with an LS range that contains the LS value of the acquired observation will be retired.

Exclusion Rule

If the parent suggestion is a member of a stereo or seasonal relation, then the other members of this relationship will be excluded from retirement (since these members will always overlap the parent suggestion).

Geometry Issues

Suggestions can be retired as soon as an observation has been planned and mapped to a suggestion. This means that the full geometry information may not yet be available if the observation has not yet been acquired and geometrically processed. When the geometry information is not available, the retirement algorithm will attempt to use the predicted center of the observation from the Planned_Observations table in HiCat. However, since the full geometry information is not available, only suggestions for which the predicted center of the observation falls within the region of interest of the suggestion will be retired. The second overlapping areas test will not be performed because the observation's footprint information is not available.

Version:
1.80 2016/08/25 20:44:32
Author:
Rodney Heyd UA/PIRL
See Also:
Unretire_Suggestions, HiCat Data Dictionary

Nested Class Summary
static class Retire_Suggestions.Messages
          The Messages class is a little data structure used for holding informational and warning messages that might be generated during the process of retiring a Suggested Observation.
 
Field Summary
static String DEBUG_DATES_PROPERTY
           
static String DEBUG_GEOMETRY_PROPERTY
           
static String DEBUG_INIT_PROPERTY
           
static String DEBUG_MAIN_PROPERTY
           
static String DEBUG_METHODS_PROPERTY
           
static String DEBUG_OVERLAP_TEST_PROPERTY
           
static String DEBUG_OVERLAPS_PROPERTY
           
static String DEBUG_RETIREMENT_LIST_PROPERTY
           
static String DEBUG_SEASONAL_TEST_PROPERTY
           
static String DEBUG_TIMING
           
static String DEFAULT_CONFIGURATION_FILENAME
           
static double DEFAULT_COORDINATE_BUFFER
           
static int EXIT_COMMAND_LINE_SYNTAX_ERROR
           
static int EXIT_CONFIGURATION_ERROR
           
static int EXIT_DATABASE_CONNECT_ERROR
           
static int EXIT_DATABASE_ERROR
           
static int EXIT_IO_ERROR
           
static int EXIT_NO_PARENT_SUGGESTION
           
static int EXIT_QUERY_ERROR
           
static int EXIT_SUCCESS
           
static int EXIT_UNDEFINED_OBSERVATION_ID
           
static String ID
           
 
Constructor Summary
Retire_Suggestions(Configuration Configuration)
          Constructs a Retire_Suggestions object with a configuration, all operations will be commited to the database.
Retire_Suggestions(Configuration Configuration, boolean Noop)
          Constructs a new Retire_Suggestions object based on a configuration.
Retire_Suggestions(Database database)
          Constructs a Retire_Suggestions object using a Database, all retirement operations will be committed to the database.
Retire_Suggestions(Database database, boolean Noop)
          Constructs a Retire_Suggestions object from a PIRL.Database object
 
Method Summary
 Vector<Integer> Get_Retired_Suggestions()
          Get the list of suggestion ids retired by the input observation ID.
 String Get_Status_Messages()
          Gets any status messages that were generated during the retirement process.
 Map<Integer,Retire_Suggestions.Messages> Get_Suggestions_To_Retire(Observation_Record observation, boolean includeAllOverlaps)
          Get a list of target suggestions that will be retired by a given HiRISE Observation.
 Map<Integer,Retire_Suggestions.Messages> Get_Suggestions_To_Retire(String Observation_ID)
          This is a wrapper method around the Get_Suggestions_To_Retire(String, boolean) method which only returns suggestions that will be retired by the default retirement rules.
 Map<Integer,Retire_Suggestions.Messages> Get_Suggestions_To_Retire(String Observation_ID, boolean includeAllOverlaps)
          Get a list of target suggestions that may be retired by a given HiRISE Observation ID.
 String Get_Warning_Messages()
          Gets any warning messages that may have been generated during the retirement process.
 boolean getStage2RetirementStatus(String observationID)
           
static void main(String[] arguments)
          Retires Suggested Observations that overlap a planned or acquired Observation.
static ArrayList<Integer> parseSuggestionIds(String id_list)
           
 boolean retire_suggestions(String Observation_ID)
          Retires suggestions that are associated with, or overlap the given Observation ID.
 Map<Integer,Retire_Suggestions.Messages> retireSuggestions(String Observation_ID, Map<Integer,Retire_Suggestions.Messages> suggestionsToForce)
          This method of retiring targets will take the output hash map generated from one of the Get_Suggestions_To_Retire(String) methods and retire the suggestions found in the map based on the return value of the Retire_Suggestions.Messages.willRetire() method (if true the suggestion will be retired, if false, the suggestion will not be retired).
 void Run_Geometry_Retirement(PrintWriter log)
          This is utility method that will scan the Observation_Retirement_Status and Observation_Geometry tables for observations that have not completed the post-geometric processing retirement step, and run the retirement procedure over these suggestions.
 Vector<Vector<String>> Stereo_Pair_Warnings(String observation_id)
          This method checks for pairs of stereo suggestions that have been retired by the same input observation id.
static void Usage(int exit_status)
          Prints the 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
See Also:
Constant Field Values

DEFAULT_CONFIGURATION_FILENAME

public static final String DEFAULT_CONFIGURATION_FILENAME
See Also:
Constant Field Values

EXIT_SUCCESS

public static final int EXIT_SUCCESS
See Also:
Constant Field Values

EXIT_COMMAND_LINE_SYNTAX_ERROR

public static final int EXIT_COMMAND_LINE_SYNTAX_ERROR
See Also:
Constant Field Values

EXIT_NO_PARENT_SUGGESTION

public static final int EXIT_NO_PARENT_SUGGESTION
See Also:
Constant Field Values

EXIT_QUERY_ERROR

public static final int EXIT_QUERY_ERROR
See Also:
Constant Field Values

EXIT_DATABASE_CONNECT_ERROR

public static final int EXIT_DATABASE_CONNECT_ERROR
See Also:
Constant Field Values

EXIT_DATABASE_ERROR

public static final int EXIT_DATABASE_ERROR
See Also:
Constant Field Values

EXIT_UNDEFINED_OBSERVATION_ID

public static final int EXIT_UNDEFINED_OBSERVATION_ID
See Also:
Constant Field Values

EXIT_CONFIGURATION_ERROR

public static final int EXIT_CONFIGURATION_ERROR
See Also:
Constant Field Values

EXIT_IO_ERROR

public static final int EXIT_IO_ERROR
See Also:
Constant Field Values

DEFAULT_COORDINATE_BUFFER

public static final double DEFAULT_COORDINATE_BUFFER
See Also:
Constant Field Values

DEBUG_MAIN_PROPERTY

public static final String DEBUG_MAIN_PROPERTY
See Also:
Constant Field Values

DEBUG_INIT_PROPERTY

public static final String DEBUG_INIT_PROPERTY
See Also:
Constant Field Values

DEBUG_METHODS_PROPERTY

public static final String DEBUG_METHODS_PROPERTY
See Also:
Constant Field Values

DEBUG_DATES_PROPERTY

public static final String DEBUG_DATES_PROPERTY
See Also:
Constant Field Values

DEBUG_OVERLAPS_PROPERTY

public static final String DEBUG_OVERLAPS_PROPERTY
See Also:
Constant Field Values

DEBUG_OVERLAP_TEST_PROPERTY

public static final String DEBUG_OVERLAP_TEST_PROPERTY
See Also:
Constant Field Values

DEBUG_GEOMETRY_PROPERTY

public static final String DEBUG_GEOMETRY_PROPERTY
See Also:
Constant Field Values

DEBUG_RETIREMENT_LIST_PROPERTY

public static final String DEBUG_RETIREMENT_LIST_PROPERTY
See Also:
Constant Field Values

DEBUG_SEASONAL_TEST_PROPERTY

public static final String DEBUG_SEASONAL_TEST_PROPERTY
See Also:
Constant Field Values

DEBUG_TIMING

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

Retire_Suggestions

public Retire_Suggestions(Configuration Configuration,
                          boolean Noop)
                   throws Database_Exception,
                          Configuration_Exception
Constructs a new Retire_Suggestions object based on a configuration.

Parameters:
Configuration - - A Configuration containing database connection parameters
Noop - Do not commit any retirements to the catalog.
Throws:
Database_Exception - - if there is a problem establishing a connection to the database
Configuration_Exception - - if there is a problem reading parameters from the configuration.

Retire_Suggestions

public Retire_Suggestions(Database database,
                          boolean Noop)
                   throws Database_Exception,
                          Configuration_Exception
Constructs a Retire_Suggestions object from a PIRL.Database object

Parameters:
database - the database object
Noop - the no operation flag, if set to true, no retirement operations will be commited to the database.
Throws:
Database_Exception - - if there is a problem establishing a connection to the database, this would only occur if the database object is not already connected to the database.
Configuration_Exception - - if there is a problem reading parameters from the configuration.

Retire_Suggestions

public Retire_Suggestions(Configuration Configuration)
                   throws Database_Exception,
                          Configuration_Exception
Constructs a Retire_Suggestions object with a configuration, all operations will be commited to the database.

Parameters:
Configuration - A Configuration object containing database connection information
Throws:
Database_Exception - - if there is a problem establishing a connection to the database
Configuration_Exception - - if there is a problem reading parameters from the configuration.

Retire_Suggestions

public Retire_Suggestions(Database database)
                   throws Database_Exception,
                          Configuration_Exception
Constructs a Retire_Suggestions object using a Database, all retirement operations will be committed to the database.

Parameters:
database - a Database
Throws:
Database_Exception - - if there is a problem establishing a connection to the database, which would only occur if the database object is not already connected to the database.
Configuration_Exception - - if there is a problem reading parameters from the configuration.
Method Detail

Get_Suggestions_To_Retire

public Map<Integer,Retire_Suggestions.Messages> Get_Suggestions_To_Retire(String Observation_ID)
                                                                   throws Database_Exception,
                                                                          IllegalArgumentException
This is a wrapper method around the Get_Suggestions_To_Retire(String, boolean) method which only returns suggestions that will be retired by the default retirement rules. It calls Get_Suggestions_To_Retire(String, boolean) with the includeAllOverlaps parameter set to false.

Parameters:
Observation_ID - - A HiRISE observation ID
Returns:
a HashMap linking suggestion Ids to a Messages object containing information about the retirement process of the suggestion.
Throws:
Database_Exception - if a database error occurs to the process.
IllegalArgumentException - if the input observation id doesn't exist
See Also:
Get_Suggestions_To_Retire(String, boolean)

Get_Suggestions_To_Retire

public Map<Integer,Retire_Suggestions.Messages> Get_Suggestions_To_Retire(String Observation_ID,
                                                                          boolean includeAllOverlaps)
                                                                   throws Database_Exception,
                                                                          IllegalArgumentException
Get a list of target suggestions that may be retired by a given HiRISE Observation ID.

Parameters:
Observation_ID - - A HiRISE Observation ID in string form
includeAllOverlaps - - If set to true the returned HashMap will include overlapping suggestions that will *not* be retired by the default set of retirement rules. These suggestions can be optionally included in case an operator determines that the default retirement rules should be overridden.
Returns:
a Map object that maps integer suggestion ids to a message object that may contain various status and warning messages that are generated during the procedure to determine what suggestions will be retired by the input observation.
Throws:
Database_Exception
IllegalArgumentException - if the input observation id does not exist

Get_Suggestions_To_Retire

public Map<Integer,Retire_Suggestions.Messages> Get_Suggestions_To_Retire(Observation_Record observation,
                                                                          boolean includeAllOverlaps)
                                                                   throws Database_Exception,
                                                                          IllegalArgumentException
Get a list of target suggestions that will be retired by a given HiRISE Observation. This method is exactly the same as the Get_Suggestions_To_Retire(String) method except that it takes an Observation_Record as an argument rather than an Observation_ID.

In order to get a complete list of all non-retired, overlapping suggestions, the includeAllOverlaps parameter should be set to true. This setting should also be used in cases where the desire to override the default retirement rules may occur. In such cases, the willRetire() method of the associated Messages object in the map will indicate the default operation to be performed on the returned suggestion. Override the default operation, use the willRetire(boolean) method on the Messages object to change the default setting. The retireSuggestions(String, Map) will retire suggestions based on the setting of the return value of the willRetire() method of a suggestion's associated Messages object.

Parameters:
observation - - An Observation_Record generated from HiPlan
includeAllOverlaps - - if true, all non-retired overlapping suggestions will be returned, if false, only those suggestions that will be retired by the standard retirement rules will be included.
Returns:
a Map object that maps integer suggestion ids to a message object that may contain various status and warning messages that are generated during the procedure to determine what suggestions will be retired by the input observation.
Throws:
Database_Exception
IllegalArgumentException - if the input observation id does not exist

retire_suggestions

public boolean retire_suggestions(String Observation_ID)
                           throws Database_Exception
Retires suggestions that are associated with, or overlap the given Observation ID. If the TARGET_NAME associated with the Observation ID is not Mars, then only the parent suggestion ID of the Observation ID will be retired. In addition, if there is no parent suggestion, then a warning message will be issued, see Get_Warning_Messages() for how to get at the warning messages.

Note: This method will be deprecated in the future. The Get_Suggestions_To_Retire() and retireSuggestions(String,Map) methods should be used instead.

Parameters:
Observation_ID - The Observation ID to use for finding suggestions to retire.
Returns:
true if the retirement was successful, otherwise false.
Throws:
Database_Exception - - if one of the database operations fail while attempting to retire a suggestion.
NullPointerException - - If one of the MIN_LONGITUDE, MAX_LONGITUDE, CENTER_LATITUDE, CENTER_LONGITUDE, or ROI fields is null for a suggestion which overlaps the retiring observation. This would only occur for suggestions which target Mars. It is expected that suggestions which do not target Mars may not have all geometry fields populated.

retireSuggestions

public Map<Integer,Retire_Suggestions.Messages> retireSuggestions(String Observation_ID,
                                                                  Map<Integer,Retire_Suggestions.Messages> suggestionsToForce)
                                                           throws Database_Exception
This method of retiring targets will take the output hash map generated from one of the Get_Suggestions_To_Retire(String) methods and retire the suggestions found in the map based on the return value of the Retire_Suggestions.Messages.willRetire() method (if true the suggestion will be retired, if false, the suggestion will not be retired).

Resetting the boolean value found in the messages object mapped to a given suggestion id prior to calling this method will over-ride the retirement decision made by the using the automated process. The Retire_Suggestions.Messages.willRetire(boolean) method can be used to override the automatically determined value.

Note: The Map returned by this method is not the same object as the HashMap used in calling this method. They are different instances of a Map<Integer,Messages> map. This is done to better facilitate detection of the before and after retirement state of suggestion list.

Parameters:
Observation_ID -
suggestionsToForce -
Returns:
A HashMap similar to that returned by the Get_Suggestions_To_Retire(String) methods with information about the retirement operation included in the Messages objects.
Throws:
Database_Exception - if an error occurs during the database update process

Get_Retired_Suggestions

public Vector<Integer> Get_Retired_Suggestions()
Get the list of suggestion ids retired by the input observation ID. This method should be called after the call to the retire_suggestions(String) method.

Returns:
a vector of Suggestion ID's retired from this run of the class.

Get_Status_Messages

public String Get_Status_Messages()
Gets any status messages that were generated during the retirement process. This includes a summary of all the suggested observations retired by the given observation.

Returns:
A String containing any status messages generated during the retirement process.

Get_Warning_Messages

public String Get_Warning_Messages()
Gets any warning messages that may have been generated during the retirement process. These messages are not critical but may be of interest if any questions arise about the status of on of the retired suggestions. This should only be called after the call to retire_suggestions(String) has completed.

Returns:
A String containing one or more warning messages

Stereo_Pair_Warnings

public Vector<Vector<String>> Stereo_Pair_Warnings(String observation_id)
                                            throws Database_Exception

This method checks for pairs of stereo suggestions that have been retired by the same input observation id. For example, if suggestions 23 and 24 are a stereo pair and both of them were retired by observation PSP_123456_1234, then this stereo pair would be returned by this method.

Note: A stereo pair returned by this method does not necessarily indicate that the stereo pair was retired in error, it is only meant as a warning, and may indicate that some action should be taken givein additional information.

Parameters:
observation_id - - An observation id to check for retired stereo pairs.
Returns:
A Vector of Vectors of Strings (eg. a Vector<Vector<String>>) The first record will be the column headings. If no stereo pairs were found, then the column headings will be the only entry and the size of the outer vector will be 1. Each "row" in the vector contains the following fields, in this order: First Half Suggestion ID, Second Half Suggestion ID, Suggester's Username, and finally, the STL_Description.
Throws:
Database_Exception - if a problem with the database query this method runs occurs.

Run_Geometry_Retirement

public void Run_Geometry_Retirement(PrintWriter log)
                             throws Database_Exception
This is utility method that will scan the Observation_Retirement_Status and Observation_Geometry tables for observations that have not completed the post-geometric processing retirement step, and run the retirement procedure over these suggestions.

Parameters:
log - The printwriter to send the status messages to.
Throws:
Database_Exception - if one of the database interactions fails

getStage2RetirementStatus

public boolean getStage2RetirementStatus(String observationID)
                                  throws Database_Exception
Throws:
Database_Exception

parseSuggestionIds

public static ArrayList<Integer> parseSuggestionIds(String id_list)

main

public static void main(String[] arguments)
Retires Suggested Observations that overlap a planned or acquired Observation. The command line syntax is described in the Usage method.

Exit Status Values

0 - Success
1 - Command line syntax error
2 - No parent suggestion found
3 - Database Query Error
4 - Database Connect Error
5 - Undefined Observation ID
6 - Configuration Error

Parameters:
arguments - Array of command line arguments

Usage

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

Usage: Retire_Suggestions <Options>
  Options -
    [-All]
    [-Configuration <filename>]
    [-Force]
    [-Geometry]
    [-ID <Suggestion ID>]
    [-Log_file <log file name>]
    [-Reretirement_Test]
    [-Noop]
    [-Observation_ID <Observation ID>]
    [-Show (Same as Noop)]
    [-Help]

Description

The command line retirement utility can be used as a batch retirement tool for non-interactive retirement, or as a means to query what suggestions might be retired by a given observation.

Options

Parameters:
exit_status -

HiRISE

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