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
`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
`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)`