Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.flexdock.util
Class Utilities

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

    public class Utilities

extends Object

Author:
  Christopher Butler

Field Summary
`static boolean` | `JAVA_1_4` A constant representing the Java version.
`static boolean` | `JAVA_1_5` A constant representing the Java version.
`static String` | `VERSION` A String representing the flexdock version.

Method Summary
`static Object` | `createInstance(String className)` Creates and returns an instance of the specified class name using `Class.newInstance()`.
`static Object` | `createInstance(String className, boolean failSilent)` Creates and returns an instance of the specified class name using `Class.newInstance()`.
`static Object` | `createInstance(String className, Class superType)` Creates and returns an instance of the specified class name using `Class.newInstance()`.
`static Object` | `createInstance(String className, Class superType, boolean failSilent)` Creates and returns an instance of the specified class name using `Class.newInstance()`.
`static float` | `getFloat(String data, float defaultValue)` Returns a `float` value for the specified `String`.
`static Object` | `getInstance(String className)` Returns an instance of the specified class name.
`static Object` | `getInstance(String className, boolean failSilent)` Returns an instance of the specified class name.
`static int` | `getInt(String data)` Returns an `int` value for the specified `String`.
`static int` | `getInt(String data, int defaultValue)` Returns an `int` value for the specified `String`.
`static Object` | `getValue(Object obj, String fieldName)` Returns the value of the specified `fieldName` within the specified `Object`.
`static boolean` | `isChanged(Object oldObj, Object newObj)` Checks for inequality between the two specified `Objects`.
`static boolean` | `isEmpty(String data)` Returns `true` if the specified `String` is `null` or contains only whitespace.
`static boolean` | `isEqual(Object obj1, Object obj2)` Checks for equality between the two specified `Objects`.
`static void` | `put(Map map, Object key, Object value)` Puts the supplied `value` into the specified `Map` using the specified `key`.
`static boolean` | `setValue(Object obj, String fieldName, 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(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 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(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(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(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(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 Object getInstance(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 Object getInstance(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 Object createInstance(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 Object createInstance(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 Object createInstance(String className,
                                        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 Object createInstance(String className,
                                        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(Object obj1,
                                  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(Object oldObj,
                                    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(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(Map map,
                           Object key,
                           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(Object obj,
                                   String fieldName,
                                   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 Object getValue(Object obj,
                                  String fieldName)
                           throws 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:
    `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)`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD