org.flexdock.util

## Class Utilities

- java.lang.Object
- - org.flexdock.util.Utilities

-     public class Utilities
      extends java.lang.Object

  Author:
    Christopher Butler

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `JAVA_1_4` A constant representing the Java version.
    `static boolean` | `JAVA_1_5` A constant representing the Java version.
    `static java.lang.String` | `VERSION` A String representing the flexdock version.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.Object` | `createInstance(java.lang.String className)` Creates and returns an instance of the specified class name using `Class.newInstance()`.
    `static java.lang.Object` | `createInstance(java.lang.String className, boolean failSilent)` Creates and returns an instance of the specified class name using `Class.newInstance()`.
    `static java.lang.Object` | `createInstance(java.lang.String className, java.lang.Class superType)` Creates and returns an instance of the specified class name using `Class.newInstance()`.
    `static java.lang.Object` | `createInstance(java.lang.String className, java.lang.Class superType, boolean failSilent)` Creates and returns an instance of the specified class name using `Class.newInstance()`.
    `static float` | `getFloat(java.lang.String data, float defaultValue)` Returns a `float` value for the specified `String`.
    `static java.lang.Object` | `getInstance(java.lang.String className)` Returns an instance of the specified class name.
    `static java.lang.Object` | `getInstance(java.lang.String className, boolean failSilent)` Returns an instance of the specified class name.
    `static int` | `getInt(java.lang.String data)` Returns an `int` value for the specified `String`.
    `static int` | `getInt(java.lang.String data, int defaultValue)` Returns an `int` value for the specified `String`.
    `static java.lang.Object` | `getValue(java.lang.Object obj, java.lang.String fieldName)` Returns the value of the specified `fieldName` within the specified `Object`.
    `static boolean` | `isChanged(java.lang.Object oldObj, java.lang.Object newObj)` Checks for inequality between the two specified `Objects`.
    `static boolean` | `isEmpty(java.lang.String data)` Returns `true` if the specified `String` is `null` or contains only whitespace.
    `static boolean` | `isEqual(java.lang.Object obj1, java.lang.Object obj2)` Checks for equality between the two specified `Objects`.
    `static void` | `put(java.util.Map map, java.lang.Object key, java.lang.Object value)` Puts the supplied `value` into the specified `Map` using the specified `key`.
    `static boolean` | `setValue(java.lang.Object obj, java.lang.String fieldName, java.lang.Object value)` Returns the value of the specified `fieldName` within the specified `Object`.
    `static void` | `sleep(long millis)` Puts the current `Thread` to sleep for the specified timeout.
    `static boolean` | `sysTrue(java.lang.String key)` Deprecated. Use `Boolean.getBoolean(String)`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### JAVA_1_4

          public static final boolean JAVA_1_4

      A constant representing the Java version. This constant is `true` if the version is 1.4.

    - #### JAVA_1_5

          public static final boolean JAVA_1_5

      A constant representing the Java version. This constant is `true` if the version is 1.5.

    - #### VERSION

          public static final java.lang.String VERSION

      A String representing the flexdock version. This constant is a string.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getInt

          public static int getInt(java.lang.String data)

      Returns an `int` value for the specified `String`. This method calls `Integer.parseInt(String s)` and returns the resulting `int` value. If any `Exception` is thrown, this method returns a value of `0`.
      Parameters:
        `data` - a `String` containing the `int` representation to be parsed
      Returns:
        the integer value represented by the argument in decimal
      See Also:
        `getInt(String, int)`, `Integer.parseInt(java.lang.String)`

    - #### getInt

          public static int getInt(java.lang.String data,
                   int defaultValue)

      Returns an `int` value for the specified `String`. This method calls `Integer.parseInt(String s)` and returns the resulting `int` value. If any `Exception` is thrown, this method returns the value supplied by the `defaultValue` parameter.
      Parameters:
        `data` - a `String` containing the `int` representation to be parsed
        `defaultValue` - the value to return if an `Exception` is encountered.
      Returns:
        the integer value represented by the argument in decimal
      See Also:
        `Integer.parseInt(java.lang.String)`

    - #### getFloat

          public static float getFloat(java.lang.String data,
                       float defaultValue)

      Returns a `float` value for the specified `String`. This method calls `Float.parseFloat(String s)` and returns the resulting `float` value. If any `Exception` is thrown by `parseFloat`, this method returns the value supplied by the `defaultValue` parameter.
      Parameters:
        `data` - a `String` containing the `float` representation to be parsed
        `defaultValue` - the value to return if an `Exception` is encountered on the underlying parse mechanism.
      Returns:
        the floating-point value represented by the argument in decimal
      See Also:
        `Float.parseFloat(java.lang.String)`

    - #### isEmpty

          public static boolean isEmpty(java.lang.String data)

      Returns `true` if the specified `String` is `null` or contains only whitespace. Otherwise, returns `false`. The whitespace check is performed by calling `trim()` and checking to see if the trimmed string `length()` is zero.
      Parameters:
        `data` - the `String` to check for non-whitespace content
      Returns:
        `true` if the specified `String` is `null` or contains only whitespace, `false` otherwise.

    - #### getInstance

          public static java.lang.Object getInstance(java.lang.String className)

      Returns an instance of the specified class name. If `className` is `null`, then this method returns a `null` reference.

      This method will try two different means of obtaining an instance of `className`. First, it will attempt to resolve the `Class` of `className` via `Class.forName(String className)`. It will then use reflection to search for a method on the class named `"getInstance()"`. If the method is found, then it is invoked and the object instance is returned.

      If there are any problems encountered while attempting to invoke `getInstance()` on the specified class, the `Throwable` is caught and this method dispatches to `createInstance(String className, boolean failSilent)` with an argument of `false` for `failSilent`. `createInstance(String className, boolean failSilent)` will attempt to invoke `newInstance()` on the `Class` for the specified class name. If any `Throwable` is encountered during this process, the value of `false` for `failSilent` will cause the stack trace to be printed to the `System.err` and a `null` reference will be returned.

      Parameters:
        `className` - the fully qualified name of the desired class.
      Returns:
        an instance of the specified class
      See Also:
        `getInstance(String, boolean)`, `createInstance(String, boolean)`, `Class.forName(java.lang.String)`, `Class.getMethod(java.lang.String, java.lang.Class[])`, `Method.invoke(java.lang.Object, java.lang.Object[])`, `Class.newInstance()`

    - #### getInstance

          public static java.lang.Object getInstance(java.lang.String className,
                                     boolean failSilent)

      Returns an instance of the specified class name. If `className` is `null`, then this method returns a `null` reference.

      This method will try two different means of obtaining an instance of `className`. First, it will attempt to resolve the `Class` of `className` via `Class.forName(String className)`. It will then use reflection to search for a method on the class named `"getInstance()"`. If the method is found, then it is invoked and the object instance is returned.

      If there are any problems encountered while attempting to invoke `getInstance()` on the specified class, the `Throwable` is caught and this method dispatches to `createInstance(String className, boolean failSilent)`, passing the specified value for `failSilent`. `createInstance(String className, boolean failSilent)` will attempt to invoke `newInstance()` on the `Class` for the specified class name. If any `Throwable` is encountered during this process, the value of `failSilent` is checked to determine whether the stack stack trace should be printed to the `System.err`. A `null` reference will be returned if any problems are encountered.

      Parameters:
        `className` - the fully qualified name of the desired class.
        `failSilent` - `true` if the stack trace should not be printed to the `System.err` when a `Throwable` is caught, `false` otherwise.
      Returns:
        an instance of the specified class
      See Also:
        `createInstance(String, boolean)`, `Class.forName(java.lang.String)`, `Class.getMethod(java.lang.String, java.lang.Class[])`, `Method.invoke(java.lang.Object, java.lang.Object[])`, `Class.newInstance()`

    - #### createInstance

          public static java.lang.Object createInstance(java.lang.String className)

      Creates and returns an instance of the specified class name using `Class.newInstance()`. If `className` is `null`, then this method returns a `null` reference. This dispatches to `createInstance(String className, Class superType, boolean failSilent)` with an argument of `null` for `superType` and `false` for `failSilent`.

      This method will attempt to resolve the `Class` of `className` via `Class.forName(String className)`. No class assignability checkes are performed because this method uses a `null` `superType`.

      Once the desired class has been resolved, a new instance of it is created and returned by invoking its `newInstance()` method. If there are any problems encountered during this process, the value of `false` for `failSilent` will ensure the stack stack trace is be printed to the `System.err`. A `null` reference will be returned if any problems are encountered.

      Parameters:
        `className` - the fully qualified name of the desired class.
      Returns:
        an instance of the specified class
      See Also:
        `createInstance(String, Class, boolean)`, `Class.forName(java.lang.String)`, `Class.newInstance()`

    - #### createInstance

          public static java.lang.Object createInstance(java.lang.String className,
                                        boolean failSilent)

      Creates and returns an instance of the specified class name using `Class.newInstance()`. If `className` is `null`, then this method returns a `null` reference. The `failSilent` parameter will determine whether error stack traces should be reported to the `System.err` before this method returns `null`. This method dispatches to `createInstance(String className, Class superType, boolean failSilent)` with an argument of `null` for `superType`.

      This method will attempt to resolve the `Class` of `className` via `Class.forName(String className)`. No class assignability checkes are performed because this method uses a `null` `superType`.

      Once the desired class has been resolved, a new instance of it is created and returned by invoking its `newInstance()` method. If there are any problems encountered during this process, the value of `failSilent` is checked to determine whether the stack stack trace should be printed to the `System.err`. A `null` reference will be returned if any problems are encountered.

      Parameters:
        `className` - the fully qualified name of the desired class.
        `failSilent` - `true` if the stack trace should not be printed to the `System.err` when a `Throwable` is caught, `false` otherwise.
      Returns:
        an instance of the specified class
      See Also:
        `createInstance(String, Class, boolean)`, `Class.forName(java.lang.String)`, `Class.newInstance()`

    - #### createInstance

          public static java.lang.Object createInstance(java.lang.String className,
                                        java.lang.Class superType)

      Creates and returns an instance of the specified class name using `Class.newInstance()`. If `className` is `null`, then this method returns a `null` reference. If `superType` is non-`null`, then this method will enforce polymorphic identity via `Class.isAssignableFrom(Class cls)`. This method dispatches to `createInstance(String className, Class superType, boolean failSilent)` with an argument of `false` for `failSilent`.

      This method will attempt to resolve the `Class` of `className` via `Class.forName(String className)`. If `superType` is non-`null`, then class identity is checked by calling `superType.isAssignableFrom(c)` to ensure the resolved class is an valid equivalent, descendent, or implementation of the specified `className`. If this check fails, then a `ClassCastException` is thrown and caught internally and this method returns `null`. If `superType` is `null`, then no assignability checks are performed on the resolved class.

      Once the desired class has been resolved, a new instance of it is created and returned by invoking its `newInstance()` method. If there are any problems encountered during this process, the value of `false` for `failSilent` will ensure the stack stack trace is be printed to the `System.err`. A `null` reference will be returned if any problems are encountered.

      Parameters:
        `className` - the fully qualified name of the desired class.
        `superType` - optional paramter used as a means of enforcing the inheritance hierarchy
      Returns:
        an instance of the specified class
      See Also:
        `createInstance(String, Class, boolean)`, `Class.forName(java.lang.String)`, `Class.isAssignableFrom(java.lang.Class)`, `Class.newInstance()`

    - #### createInstance

          public static java.lang.Object createInstance(java.lang.String className,
                                        java.lang.Class superType,
                                        boolean failSilent)

      Creates and returns an instance of the specified class name using `Class.newInstance()`. If `className` is `null`, then this method returns a `null` reference. If `superType` is non-`null`, then this method will enforce polymorphic identity via `Class.isAssignableFrom(Class cls)`. The `failSilent` parameter will determine whether error stack traces should be reported to the `System.err` before this method returns `null`.

      This method will attempt to resolve the `Class` of `className` via `Class.forName(String className)`. If `superType` is non-`null`, then class identity is checked by calling `superType.isAssignableFrom(c)` to ensure the resolved class is an valid equivalent, descendent, or implementation of the specified `className`. If this check fails, then a `ClassCastException` is thrown and caught internally and this method returns `null`. If `superType` is `null`, then no assignability checks are performed on the resolved class.

      Once the desired class has been resolved, a new instance of it is created and returned by invoking its `newInstance()` method. If there are any problems encountered during this process, the value of `failSilent` is checked to determine whether the stack stack trace should be printed to the `System.err`. A `null` reference will be returned if any problems are encountered.

      Parameters:
        `className` - the fully qualified name of the desired class.
        `superType` - optional paramter used as a means of enforcing the inheritance hierarchy
        `failSilent` - `true` if the stack trace should not be printed to the `System.err` when a `Throwable` is caught, `false` otherwise.
      Returns:
        an instance of the specified class
      See Also:
        `Class.forName(java.lang.String)`, `Class.isAssignableFrom(java.lang.Class)`, `Class.newInstance()`

    - #### isEqual

          public static boolean isEqual(java.lang.Object obj1,
                        java.lang.Object obj2)

      Checks for equality between the two specified `Objects`. If both arguments are the same `Object` reference using an `==` relationship, then this method returns `true`. Failing that check, if either of the arguments is `null`, then the other must not be and this method returns `false`. Finally, if both arguments are non-`null` with different `Object` references, then this method returns the value of `obj1.equals(obj2)`.

      This method is the exact opposite of `isChanged(Object oldObj, Object newObj)`.

      Parameters:
        `obj1` - the first `Object` to be checked for equality
        `obj2` - the second `Object` to be checked for equality
      Returns:
        `true` if the `Objects` are equal, `false` otherwise.
      See Also:
        `isChanged(Object, Object)`, `Object.equals(java.lang.Object)`

    - #### isChanged

          public static boolean isChanged(java.lang.Object oldObj,
                          java.lang.Object newObj)

      Checks for inequality between the two specified `Objects`. If both arguments are the same `Object` reference using an `==` relationship, then this method returns `false`. Failing that check, if either of the arguments is `null`, then the other must not be and this method returns `true`. Finally, if both arguments are non-`null` with different `Object` references, then this method returns the opposite value of `obj1.equals(obj2)`.

      This method is the exact opposite of `isEqual(Object obj1, Object obj2)`.

      Parameters:
        `oldObj` - the first `Object` to be checked for inequality
        `newObj` - the second `Object` to be checked for inequality
      Returns:
        `false` if the `Objects` are equal, `true` otherwise.
      See Also:
        `isEqual(Object, Object)`, `Object.equals(java.lang.Object)`

    - #### sysTrue

          public static boolean sysTrue(java.lang.String key)

      Deprecated. Use `Boolean.getBoolean(String)`.
      Returns `true` if there is currently a `System` property with the specified `key` whose value is "true". If the `System` property does not exist, or the value is inequal to "true", this method returns `false`. This method returns `false` if the specified `key` parameter is `null`.
      Parameters:
        `key` - the `System` property to test.
      Returns:
        `true` if there is currently a `System` property with the specified `key` whose value is "true".
      See Also:
        `System.getProperty(java.lang.String)`, `String.equals(java.lang.Object)`

    - #### put

          public static void put(java.util.Map map,
                 java.lang.Object key,
                 java.lang.Object value)

      Puts the supplied `value` into the specified `Map` using the specified `key`. This is a convenience method to automate null-checks. A `value` parameter of `null` is interpreted as a removal from the specified `Map` rather than an `put` operation.

      If either `map` or `key` are `null` then this method returns with no action taken. If `value` is `null`, then this method calls `map.remove(key)`. Otherwise, this method calls `map.put(key, value)`.

      Parameters:
        `map` - the `Map` whose contents is to be modified
        `key` - with which the specified value is to be associated.
        `value` - value to be associated with the specified key.
      See Also:
        `Map.put(java.lang.Object, java.lang.Object)`, `Map.remove(java.lang.Object)`

    - #### setValue

          public static boolean setValue(java.lang.Object obj,
                         java.lang.String fieldName,
                         java.lang.Object value)

      Returns the value of the specified `fieldName` within the specified `Object`. This is a convenience method for reflection hacks to retrieve the value of protected, private, or package-private field members while hiding the boilerplate reflection code within a single utility method call. This method will return `true` if the operation was successful and `false` if errors were encountered.

      This method calls `obj.getClass()` to retrieve the `Class` of the specified `Object`. It then retrieves the desired field by calling the classes' `getDeclaredField(String name)` method, passing the specified field name. If the field is deemed inaccessible via it's `isAccessible()` method, then it is made accessible by calling `setAccessible(true)`. The field value is set by invoking the field's `set(Object obj, Object value)` method and passing the original `Object` and `value` parameter as arguments. Before returning, the field's accessibility is reset to its original state.

      If either `obj` or `fieldName` are `null`, then this method returns `false`.

      It should be understood that this method will not function properly for inaccessible fields in the presence of a `SecurityManager`. Nor will it function properly for non-existent fields (if a field called `fieldName` does not exist on the class). All `Throwables` encountered by this method will be caught and eaten and the method will return `false`. This works under the assumption that the operation might likely fail because the method itself is, in reality, a convenience hack. Therefore, specifics of any generated errors on the call stack are discarded and only the final outcome (`true/false` of the operation is deemed relevant. If call stack data is required within the application for any thrown exceptions, then this method should not be used.}

      Parameters:
        `obj` - the object for which the represented field's value is to be modified
        `fieldName` - the name of the field to be set
        `value` - the new value for the field of `obj` being modified
      See Also:
        `Object.getClass()`, `Class.getDeclaredField(java.lang.String)`, `AccessibleObject.isAccessible()`, `AccessibleObject.setAccessible(boolean)`, `Field.set(Object, Object)`

    - #### getValue

          public static java.lang.Object getValue(java.lang.Object obj,
                                  java.lang.String fieldName)
                                           throws java.lang.IllegalAccessException

      Returns the value of the specified `fieldName` within the specified `Object`. This is a convenience method for reflection hacks to retrieve the value of protected, private, or package-private field members while hiding the boilerplate reflection code within a single utility method call.

      This method calls `obj.getClass()` to retrieve the `Class` of the specified `Object`. It then retrieves the desired field by calling the classes' `getDeclaredField(String name)` method, passing the specified field name. If the field is deemed inaccessible via it's `isAccessible()` method, then it is made accessible by calling `setAccessible(true)`. The return value is retrieved by invoking the field's `get(Object obj)` method and passing the original `Object` parameter as an argument. Before returning, the field's accessibility is reset to its original state.

      If either `obj` or `fieldName` are `null`, then this method returns `null`.

      It should be understood that this method will not function properly for inaccessible fields in the presence of a `SecurityManager`. Nor will it function properly for non-existent fields (if a field called `fieldName` does not exist on the class). All `Throwables` encountered by this method will be rethrown as `IllegalAccessException`. For wrapped `Throwables`, the original cause can be accessed via `IllegalAccessException's` `getCause()` method.

      Parameters:
        `obj` - the object from which the represented field's value is to be extracted
        `fieldName` - the name of the field to be checked
      Returns:
        the value of the represented field in object `obj`; primitive values are wrapped in an appropriate object before being returned
      Throws:
        `java.lang.IllegalAccessException`
      See Also:
        `Object.getClass()`, `Class.getDeclaredField(java.lang.String)`, `AccessibleObject.isAccessible()`, `AccessibleObject.setAccessible(boolean)`, `Field.get(java.lang.Object)`, `Throwable.getCause()`

    - #### sleep

          public static void sleep(long millis)

      Puts the current `Thread` to sleep for the specified timeout. This method calls `Thread.sleep(long millis)`, catching any thrown `InterruptedException` and printing a stack trace to the `System.err`.
      Parameters:
        `millis` - the length of time to sleep in milliseconds.
      See Also:
        `Thread.sleep(long)`