JAL-3261 tidy up get/set properties in Cache, Javadoc, tests

[jalview.git] / src / jalview / bin / Cache.java

diff --git a/src/jalview/bin/Cache.java b/src/jalview/bin/Cache.java
index 7128ca4..07e346f 100755 (executable)
--- a/src/jalview/bin/Cache.java
+++ b/src/jalview/bin/Cache.java
@@ -206,8 +206,6 @@ import org.apache.log4j.SimpleLayout;
  * panel in web service preferences</li>
  * </ul>
  * 
- * @author $author$
- * @version $Revision$
  */
 public class Cache implements ApplicationSingletonI
 {
@@ -628,29 +626,36 @@ public class Cache implements ApplicationSingletonI
   }
 
   /**
-   * These methods are used when checking if the saved preference is different
-   * to the default setting
+   * Returns the boolean property value for the given property name. If the
+   * value is absent then the default value is returned instead.
+   * 
+   * @param property
+   * @param def
+   * @return
    */
-
-  public static boolean getDefault(String property, boolean def)
+  public static boolean getDefault(String property, final boolean def)
   {
     String string = getProperty(property);
-    if (string != null)
-    {
-      def = Boolean.valueOf(string).booleanValue();
-    }
-
-    return def;
+    return string == null ? def : Boolean.parseBoolean(string);
   }
 
-  public static int getDefault(String property, int def)
+  /**
+   * Returns the integer property value for the given property name. If the
+   * value is absent, or malformed (not an integer), then the default value is
+   * returned instead.
+   * 
+   * @param property
+   * @param def
+   * @return
+   */
+  public static int getDefault(String property, final int def)
   {
     String string = getProperty(property);
     if (string != null)
     {
       try
       {
-        def = Integer.parseInt(string);
+        return Integer.parseInt(string);
       } catch (NumberFormatException e)
       {
         System.out.println("Error parsing int property '" + property
@@ -696,10 +701,14 @@ public class Cache implements ApplicationSingletonI
   }
 
   /**
-   * Answers the value of the given property, or the supplied default value if
+   * Returns the value of the given property, or the supplied default value if
    * the property is not set
+   * 
+   * @param property
+   * @param def
+   * @return
    */
-  public static String getDefault(String property, String def)
+  public static String getDefault(String property, final String def)
   {
     String value = getProperty(property);
     return value == null ? def : value;
@@ -720,11 +729,27 @@ public class Cache implements ApplicationSingletonI
     return getInstance().setPropertyImpl(key, obj, true);
   }
 
+  /**
+   * Sets a property value for the running application, without saving it to the
+   * properties file
+   * 
+   * @param key
+   * @param obj
+   */
   public static void setPropertyNoSave(String key, String obj)
   {
     getInstance().setPropertyImpl(key, obj, false);
   }
 
+  /**
+   * Sets a property value, and optionally also saves the current properties to
+   * file
+   * 
+   * @param key
+   * @param obj
+   * @param andSave
+   * @return
+   */
   private Object setPropertyImpl(String key, String obj, boolean andSave)
   {
     Object oldValue = null;
@@ -746,7 +771,7 @@ public class Cache implements ApplicationSingletonI
   }
 
   /**
-   * remove the specified property from the jalview properties file
+   * Removes the specified property from the jalview properties file
    * 
    * @param key
    */
@@ -755,11 +780,24 @@ public class Cache implements ApplicationSingletonI
     getInstance().removePropertyImpl(key, true);
   }
 
+  /**
+   * Removes the named property for the running application, without saving the
+   * properties file
+   * 
+   * @param key
+   */
   public static void removePropertyNoSave(String key)
   {
     getInstance().removePropertyImpl(key, false);
   }
 
+  /**
+   * Removes the named property, and optionally saves the current properties to
+   * file
+   * 
+   * @param key
+   * @param andSave
+   */
   private void removePropertyImpl(String key, boolean andSave)
   {
     applicationProperties.remove(key);
@@ -769,6 +807,9 @@ public class Cache implements ApplicationSingletonI
     }
   }
 
+  /**
+   * Saves the current properties to file
+   */
   public static void saveProperties()
   {
     getInstance().savePropertiesImpl();
@@ -1012,18 +1053,24 @@ public class Cache implements ApplicationSingletonI
   }
 
   /**
-   * get the user's default colour if available
+   * Returns the Color value of the given property's value, or the supplied
+   * default colour if no property is found, or it cannot be parsed to a colour.
+   * Colours are normally saved as hex rgb values, though other formats may be
+   * parseable.
    * 
    * @param property
-   * @param defcolour
+   * @param defaultColour
    * @return
+   * @see Cache#setColourPropertyNoSave(String, Color)
+   * @see ColorUtils#parseColourString(String)
    */
-  public static Color getDefaultColour(String property, Color defcolour)
+  public static Color getDefaultColour(String property,
+          final Color defaultColour)
   {
     String colprop = getProperty(property);
     if (colprop == null)
     {
-      return defcolour;
+      return defaultColour;
     }
     Color col = ColorUtils.parseColourString(colprop);
     if (col == null)
@@ -1031,22 +1078,24 @@ public class Cache implements ApplicationSingletonI
       log.warn("Couldn't parse '" + colprop + "' as a colour for "
               + property);
     }
-    return (col == null) ? defcolour : col;
+    return (col == null) ? defaultColour : col;
   }
 
   /**
-   * store a colour as a Jalview user default property
+   * Stores a colour as a Jalview property, converted to hex values for rgb.
+   * Properties are not saved to file.
    * 
    * @param property
    * @param colour
    */
-  public static void setColourProperty(String property, Color colour)
+  public static void setColourPropertyNoSave(String property, Color colour)
   {
     setProperty(property, jalview.util.Format.getHexString(colour));
   }
 
   /**
    * Stores a formatted date in a jalview property, using a fixed locale.
+   * Updated properties are written out to the properties file.
    * 
    * @param propertyName
    * @param date