HiRISE

HiRISE.HiPlan.Utilities
Class Utilities

java.lang.Object
  extended by HiRISE.HiPlan.Utilities.Utilities

public class Utilities
extends Object

A collection of utility methods for HiPlan and other applications.

Version:
1.62
Author:
Christian Schaller - UA/PIRL

Field Summary
static String CLASS_ID_REGEX
          The pattern defining the conventional PIRL/HiROC class ID.
static String ID
          Class identification name with source code version and date.
static String PASSWORD_MASK
          The text used to mask a password from unintended display.
 
Method Summary
static int getBinningIndex(int binning)
          Gets the index of the binning factor in the HiRISE binning factor list.
static int getCcdNameIndex(String ccdName)
          Gets the index of the CCD name in the HiRISE CCD name list.
static DateFormat getDatabaseDateFormat()
          Gets the database date format.
static DateFormat getDoyFormat()
          Gets the day-of-year format.
static String getExceptionMessage(Throwable t)
          Gets the exception message of a Throwable.
static String getExceptionMessage(Throwable t, boolean sanitizePasswords)
          Gets the exception message of a Throwable.
static DateFormat getShortDoyFormat()
          Gets the short day-of-year format.
static int getStatusIndex(String status)
          Gets the index of the status in the observation status list.
static int getTargetNameIndex(String targetName)
          Gets the index of the target name in the observation target names list.
static int getTdiIndex(int tdi)
          Gets the index of the TDU length in the HiRISE TDI length list.
static boolean isBundleFilename(String filename)
           
static boolean isDlinkFilename(String filename)
           
static boolean isFormalId(String id)
          Determines whether a piece of text is a valid, formal observation ID.
static boolean isMac()
          Determines whether the Java VM is running on a Macintosh computer.
static boolean isPtfFilename(String filename)
           
static boolean isSasfFilename(String filename)
           
static boolean isSatfFilename(String filename)
           
static boolean isStateFilename(String filename)
           
static boolean isValidBinning(int binning)
          Tests if the given binning factor is a valid HiRISE binning factor.
static boolean isValidCcdName(String ccdName)
          Tests if the given CCD name is a valid HiRISE CCD name.
static boolean isValidStatus(String status)
          Tests if the given status is a valid HiRISE observation status.
static boolean isValidTargetName(String targetName)
          Tests if the given target name is a valid HiRISE observation target name.
static boolean isValidTdi(int tdi)
          Tests if the given TDI length is a valid HiRISE TDI length.
static Date j2000()
          Gets the J2000 epoch.
static
<T> String
listToString(List<T> list)
          Creates a nice, English-language string from the elements of a list.
static
<T> String
listToString(List<T> list, String sep)
          Creates a nice, English-language string from the elements of a list.
static
<K extends Comparable<? super K>,V>
List<K>
makeSortedKeyList(Map<? extends K,V> map)
           
static void openUrl(String url, ClipboardOwner clipboardOwner)
          Attempts to open an HTTP URL in an external browser.
static void openUrl(URL url, ClipboardOwner clipboardOwner)
          Attempts to open an HTTP URL in an external browser.
static Date parseDate(String text)
          Parses an input piece of text as a date.
static double planetocentric_latitude(double planetographic_latitude)
          Convert Martian planetographic latitude to planetocentric latitude.
static double planetographic_latitude(double planetocentric_latitude)
          Convert Martian planetocentric latitude to planetographic latitude.
static void printBlue(PrintStream s, String t)
          Prints the indicated text to the indicated print stream formatted with a blue color.
static void printBold(PrintStream s, String t)
          Prints the indicated text to the indicated print stream formatted with a bold, black color.
static void printGreen(PrintStream s, String t)
          Prints the indicated text to the indicated print stream formatted with a green color.
static void printOrange(PrintStream s, String t)
          Prints the indicated text to the indicated print stream formatted with a orange color.
static void printRed(PrintStream s, String t)
          Prints the indicated text to the indicated print stream formatted with a red color.
static void printUsage(PrintStream stream, String id, String usage, String... messages)
           
static String sanitizePasswords(String text)
          Replaces password values in the input text with a mask.
static void setBlue(PrintStream s)
          Sets the indicated print stream to format text with a bold, blue color.
static void setBold(PrintStream s)
          Sets the indicated print stream to format text with a bold, black color.
static void setGreen(PrintStream s)
          Sets the indicated print stream to format text with a bold, green color.
static void setNormal(PrintStream s)
          Sets the indicated print stream to format text with its normal style.
static void setOrange(PrintStream s)
          Sets the indicated print stream to format text with a bold, orange color.
static void setRed(PrintStream s)
          Sets the indicated print stream to format text with a bold, red color.
static String[] split(String text)
          Splits a string into substrings using the comma as a delimiter.
static String stripClassId(String text)
          Strips the initial class ID from the input text if present.
static boolean testBrowserLauncher()
          Tests whether a browser launcher utility is available.
static boolean testLs(Double min, Double max, Double val)
          Tests a given Ls value to determine whether it falls within the given Ls range.
static List<String> trimQuotes(List<String> list)
          Trims matched leading and trailing quotes from each element of the input list.
static String trimQuotes(String text)
          Trims matched leading and trailing quotes from the input text.
static void updateMacKeyBindings()
          Updates the key bindings for text components on a Mac when the Java or Nimbus look and feel is in use.
 
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

PASSWORD_MASK

public static final String PASSWORD_MASK
The text used to mask a password from unintended display.

See Also:
Constant Field Values

CLASS_ID_REGEX

public static final String CLASS_ID_REGEX
The pattern defining the conventional PIRL/HiROC class ID.

See Also:
Constant Field Values
Method Detail

testBrowserLauncher

public static boolean testBrowserLauncher()
Tests whether a browser launcher utility is available.

Returns:
true if a browser launcher utility is available, false otherwise.

openUrl

public static void openUrl(URL url,
                           ClipboardOwner clipboardOwner)
Attempts to open an HTTP URL in an external browser. The browser launcher utility class included in JMARS is user for this process. Other launchers can be added to a set of mechanisms for doing so.

Parameters:
url - the URL.

openUrl

public static void openUrl(String url,
                           ClipboardOwner clipboardOwner)
Attempts to open an HTTP URL in an external browser. The browser launcher utility class included in JMARS is user for this process. Other launchers can be added to a set of mechanisms for doing so.

Parameters:
url - the URL text.

getExceptionMessage

public static String getExceptionMessage(Throwable t,
                                         boolean sanitizePasswords)
Gets the exception message of a Throwable. The exception messages of chained exceptions, if any, are appended to the message. This method acts recursively through an exception chain.

If sanitizePasswords is true, the final exception message will be sanitized of exposed passwords where possible.

Parameters:
t - the throwable from which to extract message text.
sanitizePasswords - if true, sanitizes the final message of exposed passwords.
Returns:
the message text and all chained exception message text, conditionally sanitized of exposed passwords.

getExceptionMessage

public static String getExceptionMessage(Throwable t)
Gets the exception message of a Throwable. The exception messages of chained exceptions, if any, are appended to the message. This method acts recursively through an exception chain.

An effort is made to sanitize the final exception message of exposed passwords.

Parameters:
t - the throwable from which to extract message text.
Returns:
the message text and all chained exception message text, sanitized of exposed passwords.

sanitizePasswords

public static String sanitizePasswords(String text)
Replaces password values in the input text with a mask.

Parameters:
text - the input text to sanitize.
Returns:
the sanitized text.
See Also:
PASSWORD_MASK

stripClassId

public static String stripClassId(String text)
Strips the initial class ID from the input text if present.

Prepending exception messages with the class ID is a PIRL/HiROC convention designed to make bug tracing easier for the developer, but the ID itself can create a potentially muddled error message for the operator.

The convention's pattern is to start the exception message with the class ID of the class from which the exception was thrown, followed by a newline character. This method uses the CLASS_ID_REGEX to find this initial class ID.

Parameters:
text - the input text to strip.
Returns:
the text with the initial class ID and newline removed.

isValidCcdName

public static boolean isValidCcdName(String ccdName)
Tests if the given CCD name is a valid HiRISE CCD name. The test is case-sensitive.

Parameters:
ccdName - the test CCD name.
Returns:
true if ccdName is a valid HiRISE CCD name; false if it is not.
See Also:
Instrument.CCD_NAMES

getCcdNameIndex

public static int getCcdNameIndex(String ccdName)
Gets the index of the CCD name in the HiRISE CCD name list. The test is case-sensitive. If ccdName is not a valid HiRISE CCD name, a -1 is returned.

Since these names are organized by CPMM number, this index itself is the CPMM number.

Parameters:
ccdName - the test CCD name.
Returns:
the index of ccdName in the HiRISE CCD name list or -1 if ccdName is not a valid CCD name.
See Also:
Instrument.CCD_NAMES

isValidBinning

public static boolean isValidBinning(int binning)
Tests if the given binning factor is a valid HiRISE binning factor.

Parameters:
binning - the test binning factor.
Returns:
true if binning is a valid HiRISE binning factor; false if it is not.
See Also:
Instrument.BINNING_FACTORS

getBinningIndex

public static int getBinningIndex(int binning)
Gets the index of the binning factor in the HiRISE binning factor list. If binning is not a valid HiRISE binning factor, -1 is returned.

Parameters:
binning - the test binning factor.
Returns:
the index of binning in the HiRISE binning factor list or -1 if binning is not a valid binning factor.
See Also:
Instrument.BINNING_FACTORS

isValidTdi

public static boolean isValidTdi(int tdi)
Tests if the given TDI length is a valid HiRISE TDI length.

Parameters:
tdi - the test TDI length.
Returns:
true if tdi is a valid HiRISE TDI length; false if it is not.
See Also:
Instrument.TDI_STAGES

getTdiIndex

public static int getTdiIndex(int tdi)
Gets the index of the TDU length in the HiRISE TDI length list. If tdi is not a valid HiRISE TDI length, a -1 is returned.

Parameters:
tdi - the test TDI length.
Returns:
the index of tdi in the HiRISE TDI length list or -1 if tdi is not a valid TDI length.
See Also:
Instrument.TDI_STAGES

isValidStatus

public static boolean isValidStatus(String status)
Tests if the given status is a valid HiRISE observation status. The test is case-sensitive.

Parameters:
status - the test status.
Returns:
true if status is a valid observation status; false if it is not.
See Also:
Observation_Fields.STATUSES

getStatusIndex

public static int getStatusIndex(String status)
Gets the index of the status in the observation status list. The test is case-sensitive. If status is not a valid observation status, a -1 is returned.

Parameters:
status - the test status.
Returns:
the index of status in the HiRISE observation status list or -1 if status is not a valid status.
See Also:
Observation_Fields.STATUSES

isValidTargetName

public static boolean isValidTargetName(String targetName)
Tests if the given target name is a valid HiRISE observation target name. The test is case-sensitive.

Parameters:
targetName - the test target name.
Returns:
true if targetName is a valid observation target name; false if it is not.
See Also:
Observation_Fields.TARGET_NAMES

getTargetNameIndex

public static int getTargetNameIndex(String targetName)
Gets the index of the target name in the observation target names list. The test is case-sensitive. If targetName is not a valid observation target name, a -1 is returned.

Parameters:
targetName - the test target name.
Returns:
the index of targetName in the HiRISE observation target names list or -1 if targetName is not a valid target name.
See Also:
Observation_Fields.TARGET_NAMES

planetocentric_latitude

public static double planetocentric_latitude(double planetographic_latitude)
Convert Martian planetographic latitude to planetocentric latitude. This calculation uses the IAU2000 values for the equatorial and polar radii of Mars: equatorial radius = 3396.19 km, polar radius = 3376.2 km.

Parameters:
planetographic_latitude - the planetographic latitude.
Returns:
the planetocentric latitude.

planetographic_latitude

public static double planetographic_latitude(double planetocentric_latitude)
Convert Martian planetocentric latitude to planetographic latitude. This calculation uses the IAU2000 values for the equatorial and polar radii of Mars: equatorial radius = 3396.19 km, polar radius = 3376.2 km.

Parameters:
planetocentric_latitude - the planetocentric latitude.
Returns:
the planetographic latitude.

parseDate

public static Date parseDate(String text)
Parses an input piece of text as a date. This method tries several formats: getDoyFormat(), the day-of-year format without the milliseconds, getDatabaseDateFormat(), and DateFormat.getInstance(), in that order. The timezone is assumed to be UTC.

If the method cannot parse the text, a null is returned.

Parameters:
text - the input text.
Returns:
the text as a Date object or null if it cannot be parsed.

j2000

public static Date j2000()
Gets the J2000 epoch. This epoch is defined as noon on January 1, 2000.

Returns:
the J2000 epoch.

getDoyFormat

public static DateFormat getDoyFormat()
Gets the day-of-year format. The j2000() epoch in day-of-year format is 2000-001T00:00:00.000.

Returns:
the day-of-year format.

getShortDoyFormat

public static DateFormat getShortDoyFormat()
Gets the short day-of-year format. It differs from the getDoyFormat() by the omission of the milliseconds field. The j2000() epoch in day-of-year format is 2000-001T00:00:00.

Returns:
the short day-of-year format.

getDatabaseDateFormat

public static DateFormat getDatabaseDateFormat()
Gets the database date format. The j2000() epoch in this format is 2000-01-01 12:00:00.

Returns:
the database date format.

isFormalId

public static boolean isFormalId(String id)
Determines whether a piece of text is a valid, formal observation ID.

There are two categories of HiRISE observation ID used in operations. The first is the so-called "formal" ID. It is an ID that can be represented by the Observation_ID class. The second is the so-called "loose" ID, which is any arbitrary piece of text used to identify an observation. In practice, a loose ID is used when an observation's orbit is unknown, which takes place in the early stages of planning.

Parameters:
id - the observation ID; may be null.
Returns:
true if the ID is formal observation ID; false otherwise.

isMac

public static boolean isMac()
Determines whether the Java VM is running on a Macintosh computer.

Returns:
true if the VM is running on a Mac; false otherwise.

updateMacKeyBindings

public static void updateMacKeyBindings()
Updates the key bindings for text components on a Mac when the Java or Nimbus look and feel is in use. The Java and Nimbus looks and feels use the control key for menu shortcuts and related key bindings, but the Mac OS uses the command ("meta") key for the same. This situation can lead to confusion for the operator when presented with a GUI element such as a text component.

This method updates the key binding map for text components such that the Mac command key works for Copy, Cut, Paste, and Select All shortcuts. If the Java VM is not running on a Mac, or if the Java or Nimbus look and feel is not in use, this method does nothing.


split

public static String[] split(String text)
Splits a string into substrings using the comma as a delimiter. Commas may be escaped with a backslash character; backslashes may also be escaped. Delimiters are not included in the returned split text.

Parameters:
text - the text to split.
Returns:
the split text; delimiters are never included.

listToString

public static <T> String listToString(List<T> list,
                                      String sep)
Creates a nice, English-language string from the elements of a list. The Object.toString() method is called on each element of the list, and the input sep sequence is used to separate elements of the list. The list uses the Oxford comma (or semicolon or, more accurately, sep, whatever sep is).

For a list containing no elements, an empty string is returned.

For a list containing a single element, that element is returned.

For a list of two elements, e0 and e1, the returned text is e0 and e1.

For a list of three or more elements, the returned text is of the form e0, e1, ..., and eN.

If sep is null, the empty string, or simply whitespace, no separator character will be used. The "and" will not appear before the final element. Thus, a list of two elements becomes e0 e1, and list of three or more elements becomes e0 e1 ... eN.

Parameters:
list - a list of elements to be converted to a string.
sep - the separator to use; if null or an empty string or simply whitespace, a single space will be used as the separator, and "and" will not appear before the last element.
Returns:
a string containing the elements of the list.

listToString

public static <T> String listToString(List<T> list)
Creates a nice, English-language string from the elements of a list. The Object.toString() method is called on each element of the list, and the list includes the Oxford comma.

For a list containing no elements, an empty string is returned.

For a list containing a single element, that element is returned.

For a list of two elements, e0 and e1, the returned text is e0 and e1.

For a list of three or more elements, the returned text is of the form e0, e1, ..., and eN.

Parameters:
list - a list of elements to be converted to a string.
Returns:
a string containing the elements of the list.
See Also:
listToString(List,String)

trimQuotes

public static String trimQuotes(String text)
Trims matched leading and trailing quotes from the input text. The text must be at least two characters, and the type of quote must match at the beginning and end of the text. That is, if it starts with a single-quote, it must end with one as well to be trimmed.

Parameters:
text - the text to trim.
Returns:
the trimmed text.

trimQuotes

public static List<String> trimQuotes(List<String> list)
Trims matched leading and trailing quotes from each element of the input list. For each element, the text must be at least two characters, and the type of quote must match at the beginning and end of the text. That is, if it starts with a single-quote, it must end with one as well to be trimmed.

Parameters:
list - the list of text to trim.
Returns:
the list with each element trimmed.
See Also:
trimQuotes(String)

makeSortedKeyList

public static <K extends Comparable<? super K>,V> List<K> makeSortedKeyList(Map<? extends K,V> map)

setRed

public static void setRed(PrintStream s)
Sets the indicated print stream to format text with a bold, red color. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Sequence: \e[1;31m

Parameters:
s - the output print stream.

setOrange

public static void setOrange(PrintStream s)
Sets the indicated print stream to format text with a bold, orange color. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Sequence: \e[1;33m

Parameters:
s - the output print stream.

setGreen

public static void setGreen(PrintStream s)
Sets the indicated print stream to format text with a bold, green color. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Sequence: \e[1;32m

Parameters:
s - the output print stream.

setBlue

public static void setBlue(PrintStream s)
Sets the indicated print stream to format text with a bold, blue color. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Sequence: \e[1;34m

Parameters:
s - the output print stream.

setBold

public static void setBold(PrintStream s)
Sets the indicated print stream to format text with a bold, black color. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Sequence: \e[1;30m


setNormal

public static void setNormal(PrintStream s)
Sets the indicated print stream to format text with its normal style. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Sequence: \e[0m

Parameters:
s - the output print stream.

printRed

public static void printRed(PrintStream s,
                            String t)
Prints the indicated text to the indicated print stream formatted with a red color. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Parameters:
s - the output print stream.
t - the text.
See Also:
setRed(PrintStream), setNormal(PrintStream)

printOrange

public static void printOrange(PrintStream s,
                               String t)
Prints the indicated text to the indicated print stream formatted with a orange color. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Parameters:
s - the output print stream.
t - the text.
See Also:
setOrange(PrintStream), setNormal(PrintStream)

printGreen

public static void printGreen(PrintStream s,
                              String t)
Prints the indicated text to the indicated print stream formatted with a green color. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Parameters:
s - the output print stream.
t - the text.
See Also:
setGreen(PrintStream), setNormal(PrintStream)

printBlue

public static void printBlue(PrintStream s,
                             String t)
Prints the indicated text to the indicated print stream formatted with a blue color. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Parameters:
s - the output print stream.
t - the text.
See Also:
setBlue(PrintStream), setNormal(PrintStream)

printBold

public static void printBold(PrintStream s,
                             String t)
Prints the indicated text to the indicated print stream formatted with a bold, black color. This method uses ANSI escape codes; if the print stream does not support these, strange control characters will likely print instead.

Parameters:
s - the output print stream.
t - the text.
See Also:
setBold(PrintStream), setNormal(PrintStream)

isStateFilename

public static boolean isStateFilename(String filename)

isDlinkFilename

public static boolean isDlinkFilename(String filename)

isPtfFilename

public static boolean isPtfFilename(String filename)

isSatfFilename

public static boolean isSatfFilename(String filename)

isSasfFilename

public static boolean isSasfFilename(String filename)

isBundleFilename

public static boolean isBundleFilename(String filename)

printUsage

public static void printUsage(PrintStream stream,
                              String id,
                              String usage,
                              String... messages)

testLs

public static boolean testLs(Double min,
                             Double max,
                             Double val)
Tests a given Ls value to determine whether it falls within the given Ls range. Note that because Ls is a circular quantity, it is possible for min to be greater than max.

Parameters:
min - the minimum Ls value.
max - the maximum Ls value.
val - the Ls value to test.
Returns:
true if val is within range defined by min and max; false otherwise or if any value is null.

HiRISE

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