Package com.isomorphic.util

# Class DataTools

java.lang.Object
com.isomorphic.util.DataTools

public class DataTools extends Object
`DataTools` is a utility class with the following facilities:

- `getProperties()` and `setProperties()`: `getProperties()` allow the properties of any Java object to be extracted as a Map, and `setProperties` allows any Map to be applied to a Java object, calling setter methods named after the keys of the Map. These methods are very useful for going from Java beans to a JavaScript representation and back.
- prettyPrint(), which uses a JSTranslater to output a text summary of arbitrary Java objects, very useful for logging
- many utilities for manipulating Java Collections

See Also:
  - `prettyPrint(Object)`
  - `getProperties(Object)`
  - `setProperties(Map, Object)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static List`
  `addAll(List target, Iterator source)`
  Adds all the elements of an `Iterator` to a `List`.
  `static List`
  `addAll(List target, List source)`
  Adds the contents of one `List` to another.
  `static List`
  `addAsList(List targetList, Object sourceList)`
  Add either a single object or List to another List.
  `static void`
  `addDisjunctionToSet(List one, List two)`
  Adds elements of the second `List` that are missing in the first.
  `static void`
  `addToIntInMap(Map map, Object key, int addition)`
  Add to the value of an Integer instance stored in the map "map" under key "key".
  `static List`
  `arrayToList(Object[] arr)`
  Creates a `List` from an array.
  `static List`
  `arrayToList(Object[] arr, int from, int length)`
  Creates a `List` containing a subset of an array.
  `static <T> T[]`
  `arrayUnion(T[] one, T[] two)`
  Creates a new array containing all the elements of two arrays.
  `static String`
  `bcrypt(String plaintext)`
  Returns the hash of the passed-in string, encrypted using the bcrypt algorithm
  `static <T> List<T>`
  `buildList(T... args)`
  Creates a `List` containing the passed in objects
  `static com.isomorphic.collections.DataTypeMap`
  `buildMap(Object... args)`
  Creates a `Map` of key/value pairs.
  `static Object`
  `castValue(Object value, Class targetType, DataSource ds)`
  Converts specified `value` to `targetType`.
  `static int`
  `checkSize(Object obj)`
  Obtains the size of a `Map`, `List` or `String`.
  `static Object`
  `combineAsLists(Object one, Object two)`
  Combine two single objects or Lists into one new List, or return a single Object if one argument is single and the other argument is null.
  `static boolean`
  `contains(String str, String substr)`
  Tests if the specified substring is present in the specified string.
  `static Object`
  `deepMerge(Object source, Object target, boolean overwrite)`
  Merges one collections data structure into another.
  `static void`
  `deepRemoveEmptyCollections(Object data)`
  Walks a nested Collection-based datastructure and removes all Collections entities that are zero-sized.
  `static void`
  `deepRemoveKey(Object keyToRemove, Object data)`
  Walks a nested Collection-based datastructure and removes all instances of keyToRemove (and its associated value) from any Map objects found in the data structure.
  `static void`
  `deepRemoveNullValues(Object data)`
  Walks a nested Collection-based datastructure and removes all entities that have a null value.
  `static Map`
  `divideMap(Map origMap, List retainKeys)`
  Alters a `Map` so that it retains only the specified keys, returning a `Map` with any keys not retained.
  `static List`
  `enumToList(Iterator i)`
  Converts an `Iterator` to a `List`.
  `static String`
  `fastDateFormat(Date date)`
  Returns a `String` representation of a `Date` object.
  `static Map`
  `find(List rows, Object propertyName, Object value)`
  Given a List of Maps, return the first Map that has a certain value for a key
  `static List`
  `findAll(List rows, Object propertyName, Object value)`
  Given a List of Maps, return all Maps that have a certain value for a key.
  `static List`
  `findAll(List rows, Map properties)`
  Given a List of Maps, return all Maps that have common key/value pairs with another Map.
  `static String`
  `formatDate(String format, Date date)`
  Returns the parameter date formatted according to the parameter format string.
  `static Class`
  `getCachedClass(String className)`
  Returns loaded `Class` object for specified name.
  `static Field[]`
  `getClassFields(Class c)`
  Returns array of all fields declared in specified class and it's supper classes.
  `static Method[]`
  `getClassMethods(Class c)`
  Returns array of all methods declared in specified class and it's supper classes.
  `static int`
  `getIntInMap(Map map, Object key)`
  Get value of an Integer instance stored in the map "map" under key "key", as the primitive type `int`.
  `static Object`
  `getLoggerContext()`
  Returns log4j2 `LoggerContext` instance that was configured from `log4j2.isc.config.xml`.
  `static Object`
  `getLoggerRepository()`
  Deprecated.
  `static Map`
  `getProperties(Object bean)`
  Gets the properties for a JavaBean and returns them as a `Map`.
  `static List`
  `getProperty(List rows, Object column)`
  Given a result set, as a `List` of rows, and a column name, returns the `List` of values for that column.
  `static Map<String,PropertyDescriptor>`
  `getPropertyDescriptors(Class beanClass)`
  Gets the properties for a JavaBean class through introspection and returns them as a `Map`.
  `static Map<String,PropertyDescriptor>`
  `getPropertyDescriptors(Object bean)`
  Gets the property descriptors for a JavaBean and returns them as a `Map`.
  `static Class`
  `getPropertyType(Class c, String propertyName)`
  Returns type of specified property in provided class.
  `static Class`
  `getRealClass(Object bean)`
  Checks if provided bean is a proxy and extracts real class.
  `static Object`
  `getSingle(Object toFetchFrom)`
  Retrieves the element of a single element `List`, or the key of a single key/value pair `Map`.
  `static String`
  `getStackTrace(Throwable t)`
  Returns the stack trace of a `Throwable` object as a `String`.
  `static String`
  `getStackTrace(Throwable t, int lineCount)`
  Returns the stack trace of a `Throwable` object as a `String` shortened to requested number of lines.
  `static String`
  `getterName(Method method)`
  Tests if method is getter and returns property name.
  `static String`
  `hashValue(String plaintext)`
  Returns the hash of the passed-in string, encrypted using the MD5 algorithm
  `static String`
  `hashValue(String plaintext, String algorithm)`
  Returns the hash of the passed-in string, encrypted using the specified algorithm
  `static Map`
  `identityMap(List list)`
  Stores the elements of a `List` as the keys and values of a `Map`.
  `static void`
  `incrementIntInMap(Map map, Object key)`
  Add to the value of an Integer instance stored in the map "map" under key "key".
  `static boolean`
  `isNumberType(Class clazz)`
  Returns `true` if provided class is either assignable to `Number` or represents one of primitive number types `byte, short, int, long, float, double`.
  `static boolean`
  `isTextType(Class clazz)`
  Returns `true` if provided class is either assignable to `Character` or assignable to `String` or represents primitive `char` type.
  `static org.apache.commons.jxpath.JXPathContext`
  `jxPathContext(Object obj)`
  Returns JXPathContext in lenient mode
  `static List`
  `keysAsList(Map map)`
  Creates a `List` of the keys from a `Map`.
  `static List`
  `keysNotPresent(Map map, List keys)`
  Given a `Map` and a `List` of keys, returns the list of keys in the `List` that are not present in the `Map`.
  `static Object[]`
  `listToArray(List list)`
  Creates an `Object` array from a `List`.
  `static String[]`
  `listToStringArray(Collection list)`
  Creates a `String` array from a `List`.
  `static List`
  `makeList(Object element)`
  Creates a `List` containing one element.
  `static List`
  `makeListIfSingle(Object obj)`
  Creates a `List` containing one element if the element is not a `List`.
  `static Map`
  `mapDisjunction(Map one, Map two)`
  Creates a new `Map` containing the key/value pairs whose keys are not present in both `Maps` supplied.
  `static Map`
  `mapIntersection(Map primary, Map secondary)`
  Constructs a `Map` containing the key/value pairs of the primary `Map` whose keys are present in the secondary `Map`.
  `static List`
  `mapIntersectionKeys(Map one, Map two)`
  Returns the list of keys that are present in both `Maps`.
  `static Map`
  `mapMerge(Map source, Map target)`
  Copies the key/value pairs of a `Map` into another `Map`, replacing the key/value pair of the target `Map`.
  `static Map`
  `mapMergeNonNull(Map source, Map target)`
  Copies the key/value pairs of a `Map` into another `Map`, replacing the key/value pair of the target `Map` if the source value is non-null.
  `static Properties`
  `mapToProperties(Map map)`
  Creates a `Properties` object from a `Map`.
  `static Map`
  `mapUnion(Map primary, Map secondary)`
  Constructs a `Map` containing all the key/value pairs of the `Maps` supplied as arguments, with the first `Map` taking precedence.
  `static String`
  `md5(String plaintext)`
  Deprecated.
  Please use `sha256(java.lang.String)` or `sha512(java.lang.String)` instead to generate a secure hash, as MD5 is vulnerable to attackers creating collisions with current technology.
  `static int`
  `mergeRecordsByPrimaryKey(List<Map<String,Object>> data, Map<Object,Map<String,Object>> mergeData, String primaryKeyField)`
  Merges additional field data into a list of records based on primary key matching.
  `static Object`
  `nestedGet(Object struct, String fetch)`
  Retrieves a object from a series of nested `Lists` or `Map`.
  `static LinkedHashMap`
  `orderedMapUnion(Map primary, Map secondary)`
  Does the same as `mapUnion`, but keeps order of key/value pairs.
  `static String`
  `prettyPrint(Object obj)`
  Formats information about an `Object` for viewing or printing as a `String`.
  `static Map`
  `putAllNotPresent(Map target, Map source)`
  Copies the key/value pairs of a `Map` into another `Map`, adding only key/value pairs for which the target `Map` does not already have a mapping (as determined by the `containsKey` method).
  `static Map`
  `putCombinedList(Map map, Object key, Object value)`
  Put a value into a Map, combining with any existing value as though combineAsLists() had been called on the existing value and new value.
  `static Map`
  `putMultiple(Map map, Object key, Object value)`
  Puts a key/value pair into a `Map`, if there is already a value under that key, create a `List` to hold the values.
  `static Map`
  `putMultipleAsList(Map map, Object key, Object value)`
  Works like the `putMultiple` method, but in this case values are always encapsualted in a `List`.
  `static boolean`
  `recursiveFileDelete(File file)`
  Recursively deletes a directory.
  `static void`
  `registerTransformer(Class targetType, com.isomorphic.util.DataTools.Transformer transformer)`
  Register a Transformer.
  `static Map`
  `remapRow(Map row, Map remap)`
  Change the keys used in a `Map` to a new set of keys.
  `static Map`
  `remapRow(Map row, Map remap, boolean keepNonRemapped)`
  Change the keys used in a `Map` to a new set of keys.
  `static List`
  `remapRows(List rows, Map remap)`
  Remap the keys in a `List` of `Maps`.
  `static List`
  `remapRows(List rows, Map remap, boolean keepNonRemapped)`
  Remap the keys in a `List` of `Maps`.
  `static Map`
  `removeEmptyStringValuedKeys(Map map)`
  Removes all keys from the passed-in `map` where the values are empty strings.
  `static Map`
  `removeNullValuedKeys(Map map)`
  Removes all keys from the passed-in `map` where the values are `null`.
  `static Map`
  `reverseMap(Map origMap)`
  Reverses a `Map` so that values point at keys.
  `static List`
  `setDisjunction(Collection one, Collection two)`
  Creates a new `List` containing all elements from the first `Collection` that are not in the second `Collection`.
  `static <T> List<T>`
  `setIntersection(Collection<T> one, Collection<T> two)`
  Creates a new `List` containing the common elements of two `Collections`.
  `static Object`
  `setProperties(Map propertyMap, Object bean)`
  As the three-argument version of this method, but passes a null dataSource
  `static Object`
  `setProperties(Map propertyMap, Object bean, DataSource dataSource)`
  Sets the properties for a JavaBean provided as key-value pairs in a `Map`.
  `static Object`
  `setProperties(Map propertyMap, Object bean, DataSource dataSource, DSRequest dsRequest)`
  This version of setProperties accepts a DSRequest for use as context by the conversion process.
  `static <T> List<T>`
  `setUnion(List<T> one, List<T> two)`
  Creates a new `List` containing all the elements of two `Lists`.
  `static String`
  `sha(String plaintext)`
  Deprecated.
  Please use `sha256(java.lang.String)` or `sha512(java.lang.String)` instead to generate a secure hash, as SHA-1 is vulnerable to attackers creating collisions with current technology.
  `static String`
  `sha256(String plaintext)`
  Returns the hash of the passed-in string, encrypted using the SHA-256 algorithm
  `static String`
  `sha512(String plaintext)`
  Returns the hash of the passed-in string, encrypted using the SHA-512 algorithm
  `static List`
  `subsetByPrefix(List list, String prefix)`
  Returns any strings within `list` which begin with `prefix`.
  `static Map`
  `subsetMap(Map origMap, List keys)`
  Given a `Map` and a `List` of keys, returns a subset of the `Map` containing the key/value pairs as specified by the `List` of keys.
  `static Map`
  `substringKeyMap(String prefix, Map source)`
  Constructs a `Map` of key/value pairs from the source `Map` whose keys start with a specific prefix.
  `static List`
  `toLowerCaseList(List list)`
  Given a `List` of strings, returns a new `List` of lower cased strings.

- ## Method Details

  - ### keysNotPresent

    public static List keysNotPresent(Map map, List keys)
    Given a `Map` and a `List` of keys, returns the list of keys in the `List` that are not present in the `Map`.

    Parameters:
      `map` - the `Map`
      `keys` - the `List` of keys
    Returns:
      the list of keys in the supplied `List` that are not present in the `Map`

  - ### subsetMap

    public static Map subsetMap(Map origMap, List keys)
    Given a `Map` and a `List` of keys, returns a subset of the `Map` containing the key/value pairs as specified by the `List` of keys.

    Parameters:
      `origMap` - the original `Map`
      `keys` - the keys denoting the key/value pairs that should be included in the result `Map`
    Returns:
      the subset of the original `Map` containing only the key/value pairs corresponding to the supplied `List` of keys

  - ### subsetByPrefix

    public static List subsetByPrefix(List list, String prefix)
    Returns any strings within `list` which begin with `prefix`. Non-string members of `list` are ignored.

    Parameters:
      `list` - the list of strings
      `prefix` - strings in the list with this prefix will be returned
    Returns:
      a list of the strings in the supplied list that begin with the specified prefix

  - ### removeNullValuedKeys

    public static Map removeNullValuedKeys(Map map)
    Removes all keys from the passed-in `map` where the values are `null`.

    Parameters:
      `map` - the `Map` on which to operate

  - ### removeEmptyStringValuedKeys

    public static Map removeEmptyStringValuedKeys(Map map)
    Removes all keys from the passed-in `map` where the values are empty strings.

    Parameters:
      `map` - the `Map` on which to operate

  - ### divideMap

    public static Map divideMap(Map origMap, List retainKeys)
    Alters a `Map` so that it retains only the specified keys, returning a `Map` with any keys not retained.

    Parameters:
      `origMap` - the original `Map`
      `retainKeys` - the `List` of keys corresponding to the key/value pairs that should be retained
    Returns:
      a `Map` containing the key/value pairs that were not retained

  - ### mapUnion

    public static Map mapUnion(Map primary, Map secondary)
    Constructs a `Map` containing all the key/value pairs of the `Maps` supplied as arguments, with the first `Map` taking precedence. If the same key is present in both `Maps`, the returned `Map` will contain the key/value pair of the first `Map`.

    Parameters:
      `primary` - the first `Map`
      `secondary` - the second `Map`
    Returns:
      the union of the two `Maps`

  - ### orderedMapUnion

    public static LinkedHashMap orderedMapUnion(Map primary, Map secondary)
    Does the same as `mapUnion`, but keeps order of key/value pairs. Key/value pairs of primary `Map` will go first, then key/value pairs from secondary `Map` ignoring dublicates. Consider using `LinkedHashMap` for primary and secondary maps to get full value from this method.

    Parameters:
      `primary` - the first `Map`
      `secondary` - the second `Map`
    Returns:
      the union of the two `Maps`

  - ### deepMerge

    public static Object deepMerge(Object source, Object target, boolean overwrite) throws Exception
    Merges one collections data structure into another. Any nodes/items not present in the target get created. Those that are present are merged. Note that the initial source and target must be of the same type and their data must not contain conflicting types.
    Parameters:
      `source` - the `Object` to be copied from
      `target` - the `Object` to be copied into
      `overwrite` - controls how non-collection/non-map collisions are resolved. If true, target values are overwritten with source values. If false, target values are not overwritten.
    Returns:
      the merged `Object`
    Throws:
      `Exception`

  - ### deepRemoveKey

    public static void deepRemoveKey(Object keyToRemove, Object data) throws Exception
    Walks a nested Collection-based datastructure and removes all instances of keyToRemove (and its associated value) from any Map objects found in the data structure.
    Parameters:
      `keyToRemove` - the key to remove
      `data` - the nested data structure to walk
    Throws:
      `Exception`

  - ### deepRemoveNullValues

    public static void deepRemoveNullValues(Object data) throws Exception
    Walks a nested Collection-based datastructure and removes all entities that have a null value. For Maps this means the removal of keys with a value of null, for Collections this means the removel of null elements.
    Parameters:
      `data` - the nested data structure to walk
    Throws:
      `Exception`

  - ### deepRemoveEmptyCollections

    public static void deepRemoveEmptyCollections(Object data) throws Exception
    Walks a nested Collection-based datastructure and removes all Collections entities that are zero-sized.
    Parameters:
      `data` - the nested data structure to walk
    Throws:
      `Exception`

  - ### mapMerge

    public static Map mapMerge(Map source, Map target)
    Copies the key/value pairs of a `Map` into another `Map`, replacing the key/value pair of the target `Map`.

    Parameters:
      `source` - the `Map` to be copied from
      `target` - the `Map` to be copied into
    Returns:
      the merged `Map`

  - ### mapMergeNonNull

    public static Map mapMergeNonNull(Map source, Map target)
    Copies the key/value pairs of a `Map` into another `Map`, replacing the key/value pair of the target `Map` if the source value is non-null.

    Parameters:
      `source` - the `Map` to be copied from
      `target` - the `Map` to be copied into
    Returns:
      the merged `Map`

  - ### putAllNotPresent

    public static Map putAllNotPresent(Map target, Map source)
    Copies the key/value pairs of a `Map` into another `Map`, adding only key/value pairs for which the target `Map` does not already have a mapping (as determined by the `containsKey` method).

    Parameters:
      `source` - the `Map` to be copied from
      `target` - the `Map` to be copied into
    Returns:
      the merged `Map`

  - ### mapIntersection

    public static Map mapIntersection(Map primary, Map secondary)
    Constructs a `Map` containing the key/value pairs of the primary `Map` whose keys are present in the secondary `Map`.

    Parameters:
      `primary` - the primary `Map`
      `secondary` - the secondary `Map`
    Returns:
      the intersection of the two `Map`

  - ### mapIntersectionKeys

    public static List mapIntersectionKeys(Map one, Map two)
    Returns the list of keys that are present in both `Maps`.

    Parameters:
      `one` - the first `Map`
      `two` - the second `Map`
    Returns:
      the list of keys that is the intersection of the `Maps`

  - ### substringKeyMap

    public static Map substringKeyMap(String prefix, Map source)
    Constructs a `Map` of key/value pairs from the source `Map` whose keys start with a specific prefix. The new `Map`'s keys are the origin keys without the prefix.

    Parameters:
      `prefix` - the prefix to be matched with the keys
      `source` - the source `Map`
    Returns:
      the new `Map`

  - ### identityMap

    public static Map identityMap(List list)
    Stores the elements of a `List` as the keys and values of a `Map`. This can serve as a `HashSet` which disallows duplicates and can quickly determine whether a set has a given member.

    Parameters:
      `list` - the `List` to be stored
    Returns:
      the `Map` containing the uniques elements of the list

  - ### reverseMap

    public static Map reverseMap(Map origMap)
    Reverses a `Map` so that values point at keys. If more than one value in the original `Map` has the same key (where "same" is determined by `hashcode`), the multiple keys are placed into a `List` in the reversed `Map`.

    Note: If in the original `Map`, `Lists` are mapped to values, and more than one `List` maps to the same value, this method will work incorrectly since it won't be able to tell `Lists` it created for multiple values from `Lists` that were keys in the original `Map`.

    Parameters:
      `origMap` - the original `Map`
    Returns:
      the reversed `Map`

  - ### putMultiple

    public static Map putMultiple(Map map, Object key, Object value)
    Puts a key/value pair into a `Map`, if there is already a value under that key, create a `List` to hold the values.

    Parameters:
      `map` - the `Map` to which the key/value pair should be added
      `key` - the key in the key/value pair
      `value` - the value in the key/value pair
    Returns:
      the `Map`, with the key/value pair added to it

  - ### putMultipleAsList

    public static Map putMultipleAsList(Map map, Object key, Object value)
    Works like the `putMultiple` method, but in this case values are always encapsualted in a `List`.

    Parameters:
      `map` - the `Map` to which the key/value pair should be added
      `key` - the key in the key/value pair
      `value` - the value in the key/value pair
    Returns:
      the `Map`, with the key/value pair added to it

  - ### addAll

    public static List addAll(List target, List source)
    Adds the contents of one `List` to another.

    Parameters:
      `target` - the `List` to which the contents of the source `List` should be added
      `source` - the `List` to be added to the target `List`
    Returns:
      the combined `List`

  - ### addAll

    public static List addAll(List target, Iterator source)
    Adds all the elements of an `Iterator` to a `List`.

    Parameters:
      `target` - the `List` to which the contents of the source `List` should be added
      `source` - the `List` to be added to the target `List`
    Returns:
      the combined `List`

  - ### addAsList

    public static List addAsList(List targetList, Object sourceList)
    Add either a single object or List to another List. If `sourceList` is a List, adds its items, if it's an Object, just adds the Object itself. Returns the modified `targetList`.

  - ### combineAsLists

    public static Object combineAsLists(Object one, Object two)
    Combine two single objects or Lists into one new List, or return a single Object if one argument is single and the other argument is null.

  - ### putCombinedList

    public static Map putCombinedList(Map map, Object key, Object value)
    Put a value into a Map, combining with any existing value as though combineAsLists() had been called on the existing value and new value.

  - ### setUnion

    public static <T> List<T> setUnion(List<T> one, List<T> two)
    Creates a new `List` containing all the elements of two `Lists`.

    Parameters:
      `one` - the first `List`
      `two` - the second `List`
    Returns:
      the combined `List`

  - ### addDisjunctionToSet

    public static void addDisjunctionToSet(List one, List two)
    Adds elements of the second `List` that are missing in the first. If the first or second `List` is `null`, the first will be unchanged.

    Parameters:
      `one` - the first `List`
      `two` - the second `List`

  - ### arrayUnion

    public static <T> T[] arrayUnion(T[] one, T[] two)
    Creates a new array containing all the elements of two arrays.

    Parameters:
      `one` - the first array
      `two` - the second array
    Returns:
      the combined array

  - ### setIntersection

    public static <T> List<T> setIntersection(Collection<T> one, Collection<T> two)
    Creates a new `List` containing the common elements of two `Collections`.

    Parameters:
      `one` - the first `Collection`
      `two` - the second `Collection`
    Returns:
      the common elements

  - ### mapDisjunction

    public static Map mapDisjunction(Map one, Map two)
    Creates a new `Map` containing the key/value pairs whose keys are not present in both `Maps` supplied.

    Parameters:
      `one` - the first `Map`
      `two` - the second `Map`
    Returns:
      the `Map` of the disjunction

  - ### setDisjunction

    public static List setDisjunction(Collection one, Collection two)
    Creates a new `List` containing all elements from the first `Collection` that are not in the second `Collection`.

    Parameters:
      `one` - the first `Collection`
      `two` - the second `Collection`
    Returns:
      the `List` of elements present in the first `List` that are not in the second `List`

  - ### enumToList

    public static List enumToList(Iterator i)
    Converts an `Iterator` to a `List`.

    Parameters:
      `i` - the `Iterator`
    Returns:
      the `List` of `Iterator` elements

  - ### arrayToList

    public static List arrayToList(Object[] arr, int from, int length)
    Creates a `List` containing a subset of an array.

    Parameters:
      `arr` - the source array
      `from` - the array index of the first element of the subset
      `length` - the number of elements in the subset
    Returns:
      the `List` of elements from the subset of the source array

  - ### arrayToList

    public static List arrayToList(Object[] arr)
    Creates a `List` from an array.

    Parameters:
      `arr` - the source array
    Returns:
      the `List` of elements from the source array

  - ### listToArray

    public static Object[] listToArray(List list)
    Creates an `Object` array from a `List`.

    Parameters:
      `list` - the source `List`
    Returns:
      the `Object` array containing the elements of the source list

  - ### listToStringArray

    public static String[] listToStringArray(Collection list)
    Creates a `String` array from a `List`.

    Parameters:
      `list` - the source `List`
    Returns:
      the array of `Strings` from the source `List`

  - ### mapToProperties

    public static Properties mapToProperties(Map map)
    Creates a `Properties` object from a `Map`. The keys and values in the map must be strings.

    Parameters:
      `map` - the source `Map`
    Returns:
      the `Properties` object containing the keys/values of the source `Map` as properties

  - ### keysAsList

    public static List keysAsList(Map map)
    Creates a `List` of the keys from a `Map`.

    Parameters:
      `map` - the source `Map`
    Returns:
      the list of keys from the source `Map`

  - ### makeList

    public static List makeList(Object element)
    Creates a `List` containing one element.

    Parameters:
      `element` - the element
    Returns:
      the `List` containing the element

  - ### makeListIfSingle

    public static List makeListIfSingle(Object obj)
    Creates a `List` containing one element if the element is not a `List`.

    Parameters:
      `obj` - the element
    Returns:
      the `List`

  - ### contains

    public static boolean contains(String str, String substr)
    Tests if the specified substring is present in the specified string.

    Parameters:
      `str` - the enclosing string
      `substr` - the substring
    Returns:
      `true` if the substring is contained in the string, `false` otherwise

  - ### jxPathContext

    public static org.apache.commons.jxpath.JXPathContext jxPathContext(Object obj)
    Returns JXPathContext in lenient mode

    Parameters:
      `obj` - the context bean
    Returns:
      JXPathContext instance

  - ### nestedGet

    public static Object nestedGet(Object struct, String fetch)
    Retrieves a object from a series of nested `Lists` or `Map`. The location of the structure is described by a string of `Map` keys or `List` indexes, separated by periods.

    For example, specifying the string `"dog.2"` would retrieve the object with key `"dog"` from the supplied `Map`; this object should be a `List` - the second element of this `List` would be retrieved and returned.

    Parameters:
      `struct` - the enclosing `List` or `Map`
      `fetch` - the string describing the location of the desired object
    Returns:
      the desired object
    Throws:
      `ClassCastException` - if any of the enclosing data structures is neither a `Map` nor a `List`

  - ### buildList

    public static <T> List<T> buildList(T... args)
    Creates a `List` containing the passed in objects
    Parameters:
      `args` - any number of arguments of Objects to add to the returned list
    Returns:
      the `List` containing the passed in args

  - ### buildMap

    public static com.isomorphic.collections.DataTypeMap buildMap(Object... args)
    Creates a `Map` of key/value pairs.
    Parameters:
      `args` - any (even) number of arguments - key then value then key then value etc.
    Returns:
      the `Map` containing the five key/value pairs

  - ### getSingle

    public static Object getSingle(Object toFetchFrom)
    Retrieves the element of a single element `List`, or the key of a single key/value pair `Map`. Returns `null` if the `toFetchFrom` argument is not a `List` or `Map`, or if `toFetchFrom` does not contain a single element.

    Parameters:
      `toFetchFrom` - the source `List` or `Map`
    Returns:
      the single element or key

  - ### checkSize

    public static int checkSize(Object obj)
    Obtains the size of a `Map`, `List` or `String`.

    Parameters:
      `obj` - the `Map`, `List` or `String`
    Returns:
      the size of the `Map`, `List` or `String`, as an `int` or `0` if the object is of another class

  - ### fastDateFormat

    public static String fastDateFormat(Date date)
    Returns a `String` representation of a `Date` object. This method is faster than using the `SimpleDateFormat` methods.

    Parameters:
      `date` - the date to be formatted
    Returns:
      the formatted date as a `String`

  - ### getStackTrace

    public static String getStackTrace(Throwable t, int lineCount)
    Returns the stack trace of a `Throwable` object as a `String` shortened to requested number of lines.

    Parameters:
      `t` - the `Throwable` object
      `lineCount` - number of lines to keep in stack trace `String`
    Returns:
      the stack trace for `t` as a `String`

  - ### getStackTrace

    public static String getStackTrace(Throwable t)
    Returns the stack trace of a `Throwable` object as a `String`.

    Parameters:
      `t` - the `Throwable` object
    Returns:
      the stack trace for `t` as a `String`

  - ### remapRow

    public static Map remapRow(Map row, Map remap, boolean keepNonRemapped)
    Change the keys used in a `Map` to a new set of keys. Given an existing `Map` and a mapping from old keys to new keys, create a new `Map` that uses the new keys.

    Parameters:
      `row` - the row, a `Map`
      `remap` - the map of original to new column names
      `keepNonRemapped` - `boolean` indicating whether to keep data under keys that are not remapped
    Returns:
      the row with remapped keys, or the original row, if `remap` is `null`

  - ### remapRow

    public static Map remapRow(Map row, Map remap)
    Change the keys used in a `Map` to a new set of keys. Given an existing `Map` and a mapping from old keys to new keys, create a new `Map` that uses the new keys. Columns from the original row that were not remapped will be retained.

    Parameters:
      `row` - the row, a `Map`
      `remap` - the `Map` of original to new column names
    Returns:
      the row with remapped keys, or the original row, if `remap` is `null`

  - ### remapRows

    public static List remapRows(List rows, Map remap, boolean keepNonRemapped)
    Remap the keys in a `List` of `Maps`.

    Parameters:
      `rows` - the `List` of rows
      `remap` - the `Map` of original to new column names
      `keepNonRemapped` - `boolean` indicating whether to keep data under keys that are not remapped
    Returns:
      the result set with remapped columns, or the original `List`, if `remap` is `null`

  - ### remapRows

    public static List remapRows(List rows, Map remap)
    Remap the keys in a `List` of `Maps`. Columns from the original row that were not remapped will be retained.

    Parameters:
      `rows` - the `List` of rows
      `remap` - the `Map` of original to new column names
    Returns:
      the result set with remapped columns, or the original `List`, if `remap` is `null`

  - ### getProperty

    public static List getProperty(List rows, Object column)
    Given a result set, as a `List` of rows, and a column name, returns the `List` of values for that column.

    The result set is represented as a `List` of `Map` objects, with each `Map` representing a row of data. The keys and values in each row correspond to the column names and data, respectively.

    For rows that do not have a value for the specified column, no value will be present in the return list, in other words, an empty object will not be added for that row.

    Parameters:
      `rows` - the `List` of rows
      `column` - the column name or key
    Returns:
      the `List` of values for `column`

  - ### find

    public static Map find(List rows, Object propertyName, Object value)
    Given a List of Maps, return the first Map that has a certain value for a key
    Parameters:
      `rows` - the List of Maps
      `propertyName` - the propertyName (key in the Map)
      `value` - expected value of the propertyName (may be null)
    Returns:
      the first matching Map in the List, or null if no matches

  - ### findAll

    public static List findAll(List rows, Object propertyName, Object value)
    Given a List of Maps, return all Maps that have a certain value for a key.
    Parameters:
      `rows` - the List of Maps
      `propertyName` - the propertyName (key in the Map)
      `value` - expected value of the propertyName (may be null)
    Returns:
      a List of matching Maps, or an empty list if no matches

  - ### findAll

    public static List findAll(List rows, Map properties)
    Given a List of Maps, return all Maps that have common key/value pairs with another Map.
    Parameters:
      `rows` - the List of Maps
      `properties` - Map of key/value pairs to match. May not have null values.
    Returns:
      a List of matching Maps, or an empty list if no matches

  - ### toLowerCaseList

    public static List toLowerCaseList(List list)
    Given a `List` of strings, returns a new `List` of lower cased strings.

    Parameters:
      `list` - the `List` of strings
    Returns:
      the `List` of lower cased strings

  - ### prettyPrint

    public static String prettyPrint(Object obj)
    Formats information about an `Object` for viewing or printing as a `String`.

    Parameters:
      `obj` - the `Object` to be formatted for output
    Returns:
      the information `String` to be used for the `Object` in viewing or printing

  - ### addToIntInMap

    public static void addToIntInMap(Map map, Object key, int addition)
    Add to the value of an Integer instance stored in the map "map" under key "key".

    If no Integer is currently stored under "key", creates a new Integer with value 0 before adding to it.

    This method exists because of the horrific chain of typecasts otherwise necessary to achieve this effect.

  - ### incrementIntInMap

    public static void incrementIntInMap(Map map, Object key)
    Add to the value of an Integer instance stored in the map "map" under key "key".

    If no Integer is currently stored under "key", creates a new Integer with value 0 before adding to it.

    This method exists because of the horrific chain of typecasts otherwise necessary to achieve this effect.

  - ### getIntInMap

    public static int getIntInMap(Map map, Object key)
    Get value of an Integer instance stored in the map "map" under key "key", as the primitive type `int`.

    Returns 0 if no Integer is currently stored in the Map.

  - ### getterName

    public static String getterName(Method method)
    Tests if method is getter and returns property name. Returns `null` if provided method is not getter.
    Parameters:
      `method` - `Method` Getter to extract property name.
    Returns:
      `String` Getter property name or `null` if provided method is not getter.

  - ### getClassFields

    public static Field[] getClassFields(Class c)
    Returns array of all fields declared in specified class and it's supper classes. Array contains fields with all modifiers. Returns empty array if provided parameter is `null`.
    Parameters:
      `c` - `Class` to be inspected.
    Returns:
      `Field[]` Array of class fields.

  - ### getClassMethods

    public static Method[] getClassMethods(Class c)
    Returns array of all methods declared in specified class and it's supper classes. Array contains methods with all modifiers as well as overriden methods from super classes. Returns empty array if provided parameter is `null`.
    Parameters:
      `c` - `Class` to be inspected.
    Returns:
      `Method[]` Array of class methods.

  - ### getPropertyType

    public static Class getPropertyType(Class c, String propertyName) throws IntrospectionException
    Returns type of specified property in provided class. Property name can be composed of sub-properties separated by dot for example:
    - property1 - type of property1 will be returned
    - property1.subproperty - type of sub-property will be returned
    Property will be looked up in specified order:
    1. Among fields declared in specified class
    2. Among methods declared in specified class
    3. Among fields declared in all supper classes
    4. Among methods declared in all supper classes
    Only getter methods are tested: method has no parameters and it's name starts with either "get" or "is".
    Throws `NullPointerException` if either of parameters is null.
    Parameters:
      `c` - `Class` to be inspected.
      `propertyName` - `String` Name of property.
    Returns:
      `Class` Type of property.
    Throws:
      `IntrospectionException` - when specified class has no such property.

  - ### getCachedClass

    public static Class getCachedClass(String className)
    Returns loaded `Class` object for specified name. Cached class is returned if exists otherwise class object is loaded and cached. Returns `null` if class can not be loaded (not in class path).
    Parameters:
      `className` - `String` qualified class name to load.
    Returns:
      `Class` object of `null` if class can not be loaded (not in class path).

  - ### getRealClass

    public static Class getRealClass(Object bean)
    Checks if provided bean is a proxy and extracts real class. If bean is not a proxy class then its getClass() is returned. Current implementation checks only for Hibernate proxies. Real class is extracted via `realClass = (Class) ((HibernateProxy) bean).getHibernateLazyInitializer().getPersistentClass();`
    Parameters:
      `bean` - `Object`
    Returns:
      `Class`

  - ### getProperties

    public static Map getProperties(Object bean) throws Exception
    Gets the properties for a JavaBean and returns them as a `Map`.

    Parameters:
      `bean` - the JavaBean object
    Returns:
      the JavaBean properties as a `Map`
    Throws:
      `Exception`

  - ### getPropertyDescriptors

    public static Map<String,PropertyDescriptor> getPropertyDescriptors(Object bean) throws Exception
    Gets the property descriptors for a JavaBean and returns them as a `Map`.

    Parameters:
      `bean` - the JavaBean object
    Returns:
      the JavaBean property descriptors as a `Map`
    Throws:
      `Exception`

  - ### getPropertyDescriptors

    public static Map<String,PropertyDescriptor> getPropertyDescriptors(Class beanClass) throws Exception
    Gets the properties for a JavaBean class through introspection and returns them as a `Map`.

    Removes properties added by byte-code instrumentation:

    - `interceptFieldCallback` property is removed if class implements `net.sf.cglib.transform.impl.InterceptFieldEnabled` interface;
    - `fieldHandler` property is removed if class implements `org.hibernate.bytecode.javassist.FieldHandled` interface;
    Parameters:
      `beanClass` - the JavaBean class
    Returns:
      the JavaBean class's property descriptors as a `Map`
    Throws:
      `Exception`

  - ### setProperties

    public static Object setProperties(Map propertyMap, Object bean) throws Exception
    As the three-argument version of this method, but passes a null dataSource
    Parameters:
      `propertyMap` - a `Map` providing the key-value pairs
      `bean` - the JavaBean object
    Returns:
      the JavaBean properties as a `Map`
    Throws:
      `IllegalArgumentException` - if a value provided in the `Map` cannot be converted to an appropriate type
      `Exception`

  - ### setProperties

    public static Object setProperties(Map propertyMap, Object bean, DataSource dataSource) throws Exception
    Sets the properties for a JavaBean provided as key-value pairs in a `Map`. This method performs automatic type detection and conversion where possible. Conversion is done via standard bean semantics. Additionally, some standard conversions are performed automatically - for example inbound java.util.Date object will be auto-converted to java.sql.Date or java.sql.Timestamp.

    Keys for which conversion fails or for which there are no corresponding Bean properties are ignored.

    For properties that have primitive value on the target bean (eg properties of `int` type), generally, the static "valueOf(String)" method for the primitive type (eg Boolean.valueOf(String)) will be invoked on the result of "toString()" for the Object being assigned to the primitive property.

    As special cases the null string ("") and the `null` value will become 0 when assigned to numeric primitive types (which cannot be null).

    If the null string is assigned to a non-primitive numeric type (eg Long), the property will be assigned `null`.

    If the target bean property is an enum, this method attempts to set an appropriate value by use of the enum translate strategy set by calling setEnumTranslateStrategy() on the dataSource, if one is provided. See `DataSource.setEnumTranslateStrategy(String)`. If there is no DataSource, or it cannot set a value by cleanly using the enumTranslateStrategy, it will attempt to infer a value by considering the incoming value first as a String to match against the enumerated type's value names, and failing that as an integer to match against the enumerated type's values as an ordinal value. If that fails, it sets the target bean property to null.

    If the target bean property is of Joda-Time type (`org.joda.time.DateTime, DateMidnight, LocalDateTime, LocalDate, LocalTime`), then value is passed to the target type constructor taking `Object` parameter. See Joda documentation for supported inputs.

    If the target bean property is of Java 8 Date/Time API type (`java.time.LocalDate, LocalDateTime, LocalTime`), it is created with `ZoneId.systemDefault()` for `Date` input or attempting `<target-type>.parse(input.toString())` for everything else.

    Otherwise, if the type accepted by a setter method on the target bean cannot accept the type of the value in the propertyMap, this method will attempt type conversion by looking for a constructor on the setter method type that accepts instances of the value's type.

    Also, if a Map value is found in the values of the passed in propertyMap, and the recipient field on the bean is not a Map, this method will treat the target field as a bean, attempting to create the bean via newInstance() and populating it via a recursive call to this method. In other words, this method will auto-create and populate inner beans.

    Similarly if a Collection is found in the propertyMap, it will be applied to a target field of Collection type. If the target field is of an abstract Collection type, the default types used are:

    - Map -> LinkedHashMap
    - List or Collection -> ArrayList
    - Set -> HashSet
    - Queue -> LinkedList
    Java Generics declarations will be automatically used to determine the type of each member of any collection. For example, a bean property declared of type List will be populated automatically with instances of SomeBean.

    A DataSource can be optionally passed as the third argument and can modify some of the above behaviors, including choice of concrete type when populating bean properties that declare only an abstract type or base type - See `DataSource.setProperties(Map, Object)` for details.

    Parameters:
      `propertyMap` - a `Map` providing the key-value pairs
      `bean` - the JavaBean object
      `dataSource` - a context DataSource, if applicable. Can be null
    Returns:
      the JavaBean object
    Throws:
      `IllegalArgumentException` - if a value provided in the `Map` cannot be converted to an appropriate type
      `Exception`

  - ### setProperties

    public static Object setProperties(Map propertyMap, Object bean, DataSource dataSource, DSRequest dsRequest) throws Exception
    This version of setProperties accepts a DSRequest for use as context by the conversion process. In particular, the DSRequest is passed to the getDataSource() method of a `DynamicDSGenerator`.
    Parameters:
      `propertyMap` - a `Map` providing the key-value pairs
      `bean` - the JavaBean object
      `dataSource` - a context DataSource, if applicable
      `dsRequest` - a context DSRequest, if applicable
    Returns:
      the JavaBean object
    Throws:
      `IllegalArgumentException` - if a value provided in the `Map` cannot be converted to an appropriate type
      `Exception`

  - ### registerTransformer

    public static void registerTransformer(Class targetType, com.isomorphic.util.DataTools.Transformer transformer)
    Register a Transformer. The Transformer interface specifies a single transform() method. The transform() method must be capable of creating an object of type targetType from the input Object. In a simple case, this could typically be done by making use of Object.toString.
    Parameters:
      `targetType` - the Class that this Transformer is capable of transforming to
      `transformer` - the Transformer object itself

  - ### castValue

    public static Object castValue(Object value, Class targetType, DataSource ds)
    Converts specified `value` to `targetType`.
    Implemented conversion rules:
    - Returns `null` if passed value is `null`
    - If passed value can be cast to `targetType` then same value returned
    - For primitive types returns appropriate object for example:if `targetType` is `Long.TYPE` method returns `Long`
    - If `targetType` is `Boolean` and passed value is instance of `Number` then 0 converted to `false`; any other number converted to `true`
    - If `targetType` is `Boolean` and passed value is instance of `Character` then 'T', 't', 'Y' and 'y' converted to `true`; any other character converted to `false`
    - If `targetType` is `Boolean` and passed value is instance of `String` then "true", "t", "yes" and "y" (ignoring case) converted to `true`; any other string converted to `false`
    - If `targetType` is `Byte` and passed value is instance of `Boolean` then `false` converted to 0; `true` converted to 1
    - If `targetType` is `Byte` and passed value is instance of `Number` then value may be rounded and/or truncated
    - If `targetType` is `Byte` and passed value is instance of `String` then value is parsed with `Byte.valueOf()`
    - If `targetType` is `Short` and passed value is instance of `Boolean` then `false` converted to 0; `true` converted to 1
    - If `targetType` is `Short` and passed value is instance of `Number` then value may be rounded and/or truncated
    - If `targetType` is `Short` and passed value is instance of `String` then value is parsed with `Short.valueOf()`
    - If `targetType` is `Integer` and passed value is instance of `Boolean` then `false` converted to 0; `true` converted to 1
    - If `targetType` is `Integer` and passed value is instance of `Number` then value may be rounded and/or truncated
    - If `targetType` is `Integer` and passed value is instance of `Character` then caracter value is returned
    - If `targetType` is `Integer` and passed value is instance of `String` then value is parsed with `Integer.valueOf()`
    - If `targetType` is `Long` and passed value is instance of `Boolean` then `false` converted to 0; `true` converted to 1
    - If `targetType` is `Long` and passed value is instance of `Number` then value may be rounded and/or truncated
    - If `targetType` is `Long` and passed value is instance of `Character` then caracter value is returned
    - If `targetType` is `Long` and passed value is instance of `String` then value is parsed with `Long.valueOf()`
    - If `targetType` is `Long` and passed value is instance of `Date` then `Date.getTime()` returned
    - If `targetType` is `Float` and passed value is instance of `Boolean` then `false` converted to 0; `true` converted to 1
    - If `targetType` is `Float` and passed value is instance of `Number` then value may be rounded and/or truncated
    - If `targetType` is `Float` and passed value is instance of `Character` then caracter value is returned
    - If `targetType` is `Float` and passed value is instance of `String` then value is parsed with `Float.valueOf()`
    - If `targetType` is `Float` and passed value is instance of `Date` then `Date.getTime()` returned
    - If `targetType` is `Double` and passed value is instance of `Boolean` then `false` converted to 0; `true` converted to 1
    - If `targetType` is `Double` and passed value is instance of `Number` then value may be rounded
    - If `targetType` is `Double` and passed value is instance of `Character` then caracter value is returned
    - If `targetType` is `Double` and passed value is instance of `String` then value is parsed with `Double.valueOf()`
    - If `targetType` is `Double` and passed value is instance of `Date` then `Date.getTime()` returned
    - If `targetType` is `Character` and passed value is instance of `Boolean` then `false` converted to 'f'; `true` converted to 't'
    - If `targetType` is `Character` and passed value is instance of `Number` then character for value code returned (value may be rounded and/or truncated)
    - If `targetType` is `Character` and passed value is instance of `String` then returns first string charater; `(char) 0` returned for empty string
    - If `targetType` is `String` then `value.toString()` returned
    - If `targetType` is `BigInteger` and passed value is instance of `Boolean` then `false` converted to `BigInteger.ZERO`; `true` converted to `BigInteger.ONE`
    - If `targetType` is `BigInteger` and passed value is instance of `Number` then value may be rounded
    - If `targetType` is `BigInteger` and passed value is instance of `Character` then caracter value is returned
    - If `targetType` is `BigInteger` and passed value is instance of `String` then value is parsed
    - If `targetType` is `BigInteger` and passed value is instance of `Date` then `Date.getTime()` returned
    - If `targetType` is `BigDecimal` and passed value is instance of `Boolean` then `false` converted to `BigDecimal.ZERO`; `true` converted to `BigDecimal.ONE`
    - If `targetType` is `BigDecimal` and passed value is instance of `Number` then value converted to `BigDecimal`
    - If `targetType` is `BigDecimal` and passed value is instance of `Character` then caracter value is returned
    - If `targetType` is `BigDecimal` and passed value is instance of `String` then value is parsed
    - If `targetType` is `BigDecimal` and passed value is instance of `Date` then `Date.getTime()` returned
    - If `targetType` is `java.util.Date` and passed value is instance of `Number` then `java.util.Date` created with value as miliseconds (value may be rounded and/or truncated)
    - If `targetType` is `java.util.Date` and passed value is instance of `String` then value is parsed with `DateFormat.getDateTimeInstance()`
    - If `targetType` is `java.sql.Date` and passed value is instance of `Number` then `java.sql.Date` created with value as miliseconds (value may be rounded and/or truncated)
    - If `targetType` is `java.sql.Date` and passed value is instance of `String` then value is parsed with `DateFormat.getDateInstance()`
    - If `targetType` is `java.sql.Date` and passed value is instance of `java.util.Date` then value is converted
    - If `targetType` is `java.sql.Date` and passed value is instance of `java.sql.Time` then value is converted
    - If `targetType` is `java.sql.Date` and passed value is instance of `java.sql.Timestamp` then value is converted
    - If `targetType` is `java.sql.Time` and passed value is instance of `Number` then `java.sql.Time` created with value as miliseconds (value may be rounded and/or truncated)
    - If `targetType` is `java.sql.Time` and passed value is instance of `String` then value is parsed with `DateFormat.getTimeInstance()`
    - If `targetType` is `java.sql.Time` and passed value is instance of `java.util.Date` then value is converted
    - If `targetType` is `java.sql.Time` and passed value is instance of `java.sql.Date` then value is converted
    - If `targetType` is `java.sql.Time` and passed value is instance of `java.sql.Timestamp` then value is converted
    - If `targetType` is `java.sql.Timestamp` and passed value is instance of `Number` then `java.sql.Timestamp` created with value as miliseconds (value may be rounded and/or truncated)
    - If `targetType` is `java.sql.Timestamp` and passed value is instance of `String` then value is parsed with `DateFormat.getDateTimeInstance()`
    - If `targetType` is `java.sql.Timestamp` and passed value is instance of `java.util.Date` then value is converted
    - If `targetType` is `java.sql.Timestamp` and passed value is instance of `java.sql.Date` then value is converted
    - If `targetType` is `java.sql.Timestamp` and passed value is instance of `java.sql.Time` then value is converted
    Parameters:
      `value` - `Object` value to be converted.
      `targetType` - `Class` conversion target type.
      `ds` - `DataSource` initiating conversion.
    Returns:
      `Object` converted value.
    Throws:
      `ClassCastException` - if value can not be converted or parsing exception occurs.

  - ### isTextType

    public static boolean isTextType(Class clazz)
    Returns `true` if provided class is either assignable to `Character` or assignable to `String` or represents primitive `char` type.
    Parameters:
      `clazz` - `Class` for testing.
    Returns:
      `boolean` `true` if specified class represents class for text; `false` - for all other classes.

  - ### isNumberType

    public static boolean isNumberType(Class clazz)
    Returns `true` if provided class is either assignable to `Number` or represents one of primitive number types `byte, short, int, long, float, double`.
    Parameters:
      `clazz` - `Class` for testing.
    Returns:
      `boolean` `true` if specified class represents class for numbers; `false` - for all other classes.

  - ### mergeRecordsByPrimaryKey

    public static int mergeRecordsByPrimaryKey(List<Map<String,Object>> data, Map<Object,Map<String,Object>> mergeData, String primaryKeyField)
    Merges additional field data into a list of records based on primary key matching.

    This utility method is useful for merging metadata from external sources (such as full-text search scores and snippets) into database records based on their primary key.

    The merge operation adds fields from the mergeData map to records in the data list where the primary key values match. Existing fields in the records are not overwritten unless explicitly present in the mergeData.

    Parameters:
      `data` - The list of records to merge into. Each record should be a Map.
      `mergeData` - Map keyed by primary key value, where each value is a Map of field names to values to merge into the matching record.
      `primaryKeyField` - The name of the primary key field used for matching.
    Returns:
      The number of records that were successfully merged.
    See Also:
      - `DSRequest.getMergeData()`
      - `DSRequest.addMergeData(Object, Map)`
      - `DSRequest.mergeNow(DSResponse)`

  - ### recursiveFileDelete

    public static boolean recursiveFileDelete(File file)
    Recursively deletes a directory.
    Parameters:
      `file` - file or directory to delete
    Returns:
      true if successful, false otherwise cannot be converted to an appropriate type

  - ### md5

    public static String md5(String plaintext) throws Exception
    Deprecated.
    Please use `sha256(java.lang.String)` or `sha512(java.lang.String)` instead to generate a secure hash, as MD5 is vulnerable to attackers creating collisions with current technology.
    Returns the hash of the passed-in string, encrypted using the MD5 algorithm
    Parameters:
      `plaintext` - the text to encrypt
    Returns:
      the encrypted (MD5) hash of the supplied plaintext
    Throws:
      `Exception`

  - ### sha

    public static String sha(String plaintext) throws Exception
    Deprecated.
    Please use `sha256(java.lang.String)` or `sha512(java.lang.String)` instead to generate a secure hash, as SHA-1 is vulnerable to attackers creating collisions with current technology.
    Returns the hash of the passed-in string, encrypted using the SHA-1 algorithm
    Parameters:
      `plaintext` - the text to encrypt
    Returns:
      the encrypted (SHA) hash of the supplied plaintext
    Throws:
      `Exception`

  - ### sha256

    public static String sha256(String plaintext) throws Exception
    Returns the hash of the passed-in string, encrypted using the SHA-256 algorithm
    Parameters:
      `plaintext` - the text to encrypt
    Returns:
      the encrypted (SHA-256) hash of the supplied plaintext
    Throws:
      `Exception`

  - ### sha512

    public static String sha512(String plaintext) throws Exception
    Returns the hash of the passed-in string, encrypted using the SHA-512 algorithm
    Parameters:
      `plaintext` - the text to encrypt
    Returns:
      the encrypted (SHA-512) hash of the supplied plaintext
    Throws:
      `Exception`

  - ### bcrypt

    public static String bcrypt(String plaintext) throws Exception
    Returns the hash of the passed-in string, encrypted using the bcrypt algorithm
    Parameters:
      `plaintext` - the text to encrypt
    Returns:
      the encrypted (bcrypt) hash of the supplied plaintext
    Throws:
      `Exception`

  - ### hashValue

    public static String hashValue(String plaintext) throws Exception
    Returns the hash of the passed-in string, encrypted using the MD5 algorithm
    Parameters:
      `plaintext` - the text to encrypt
    Returns:
      the encrypted (MD5) hash of the supplied plaintext
    Throws:
      `Exception`

  - ### hashValue

    public static String hashValue(String plaintext, String algorithm) throws Exception
    Returns the hash of the passed-in string, encrypted using the specified algorithm
    Parameters:
      `plaintext` - the text to encrypt
      `algorithm` - the encryption algorithm to use. Search the client-side documentation for "HashAlgorithm" for details.
    Returns:
      the encrypted hash of the supplied plaintext
    Throws:
      `Exception`

  - ### formatDate

    public static String formatDate(String format, Date date)
    Returns the parameter date formatted according to the parameter format string. This method is trivial - it just creates a SimpleDateFormat object and calls its format() method - but it is useful for formatting dates in Velocity expressions
    Parameters:
      `format` - A valid SimpleDateFormat format string
      `date` - The date to format
    Returns:
      The date formatted according to the format string

  - ### getLoggerRepository

    public static Object getLoggerRepository()
    Deprecated.
    Since Log4j 1.x is no longer directly supported, this returns the Log4j2 `LoggerContext` by calling the new `getLoggerContext()` API.

  - ### getLoggerContext

    public static Object getLoggerContext()
    Returns log4j2 `LoggerContext` instance that was configured from `log4j2.isc.config.xml`. Use this method to access log4j2 loggers for custom categories defined in this file.

    Note: use this method only if log4j2 logging is used.

    Returns:
      log4j2 `LoggerContext` instance if configured, otherwise `null`.

      Note: `Object` return type is used to avoid unnecessary log4j2 dependency if alternative logging system is used.