Package com.globalmentor.java

Class Objects

java.lang.Object
com.globalmentor.java.Objects
public class Objects extends Object
Various utilities to manipulate Java objects.
Author:
Garret Wilson

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Object[]
    NO_OBJECTS
    A shared object array that contains no elements.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T, I extends T>
    Function<T,Optional<I>>
    asInstance(Class<I> instanceClass)
    Convenience method that returns a function that casts some object to a given class if and only if it is an instance of that class.
    static <T, I extends T>
    Optional<I>
    asInstance(T object, Class<I> instanceClass)
    Convenience method that returns the given object if and only if it is an instance of the given class.
    static <T, I extends T>
    Function<T,Stream<I>>
    asInstances(Class<I> instanceClass)
    Convenience method that returns a function that casts some object to a given class if and only if it is an instance of that class, returning a potentially empty stream.
    static <T> T
    checkType(Object variable, Class<T> type)
    Checks to see if a given variable is of the correct type and if not, throws a ClassCastException.
    static <T> T
    checkType(Object variable, Class<T> type, String description)
    Checks to see if a given variable is of the correct type and if not, throws a ClassCastException.
    static <T extends CloneSupported>
    T
    clone(T object)
    Clones an object that supports cloning.
    static <T extends Comparable<? super T>>
    int
    compare(T object1, T object2, int nullBias)
    Compares two objects for order, taking into account null.
    static final boolean
    equals(Object object1, Object object2)
    Deprecated.
    to be removed in favor of Objects.equals(Object, Object) from Java 7.
    static int
    getDoubleHashCode(double... values)
    Deprecated.
    static int
    getHashCode(Object... objects)
    Deprecated.
    to be removed in favor of Objects.hash(Object...) from Java 7.
    static <T, C extends T>
    C
    getInstance(Class<C> objectClass, T... objects)
    Returns the first object that is an instance of the given object type.
    static <T> T
    getInstance(T... objects)
    Returns the first object that is an instance of Object (i.e.
    static Class<?>
    getInstanceOf(Object object, Class<?>... classes)
    Determines of which, if any, of the provided classes the given object is an instance.
    static int
    getIntHashCode(int... values)
    Deprecated.
    static int
    getLongHashCode(long... values)
    Deprecated.
    static Object
    getProperty(Object object, String propertyName)
    Returns the property of an object based upon a given property name.
    static int
    getSeededHashCode(int seed, Object... objects)
    Deprecated.
    static boolean
    isInstanceOf(Object object, Class<?>... classes)
    Determines if the object is an instance of any of the provided classes.
    static Object[]
    requireNonNulls(Object... objects)
    Checks to see if the elements are instances of any object, and throws a NullPointerException if any element is null.
    static AutoCloseable
    toAutoCloseable(Object object)
    Converts an object to an AutoCloseable instance so that it can be used with try-with-resources.
    static <T> T
    toInstance(T object, T defaultInstance)
    Returns either and object or a default instance if the object is null.
    static final String
    toString(Object object)
    Returns the string representation of the object or "null".

    Methods inherited from class java.lang.Object

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

  • Field Details

    • NO_OBJECTS

      public static final Object[] NO_OBJECTS
      A shared object array that contains no elements.

  • Method Details

    • checkType

      public static <T> T checkType(Object variable, Class<T> type)
      Checks to see if a given variable is of the correct type and if not, throws a ClassCastException.
      Type Parameters:
      T - The type of variable to check.
      Parameters:
      variable - The variable to check, or null.
      type - The type to verify.
      Returns:
      The given variable.
      Throws:
      ClassCastException - if the given variable is not null and not an instance of type type.

    • checkType

      public static <T> T checkType(Object variable, Class<T> type, String description)
      Checks to see if a given variable is of the correct type and if not, throws a ClassCastException.
      Type Parameters:
      T - The type of variable to check.
      Parameters:
      variable - The variable to check, or null.
      type - The type to verify.
      description - A description of the variable to be used when generating an exception, or null for no description.
      Returns:
      The given variable.
      Throws:
      ClassCastException - if the given variable is not null and not an instance of type type.

    • clone

      public static <T extends CloneSupported> T clone(T object)
      Clones an object that supports cloning.
      Type Parameters:
      T - The type of the object.
      Parameters:
      object - The object that supports cloning through use of the CloneSupported interface.
      Returns:
      The cloned object.
      Throws:
      IllegalStateException - if the object's CloneSupported.clone() method throws a CloneNotSupportedException.
      See Also:

    • compare

      public static <T extends Comparable<? super T>> int compare(T object1, T object2, int nullBias)
      Compares two objects for order, taking into account null. If both objects are null they are considered equal. If only one object is null, comparison will be performed based upon whether null is considered higher or lower. Otherwise, the second object is compared to the first using the first object's Comparable.compareTo(Object) method.
      Type Parameters:
      T - The type of the object.
      Parameters:
      object1 - The first object to be compared.
      object2 - The second object to be compared.
      nullBias - A negative or positive integer indicating if null should be considered less than or greater than non-null objects.
      Returns:
      A negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

    • asInstance

      public static <T, I extends T> Optional<I> asInstance(T object, Class<I> instanceClass)
      Convenience method that returns the given object if and only if it is an instance of the given class. This method is equivalent to object instanceof Type ? Optional.of((Type)object) : Optional.empty();.
      Type Parameters:
      T - The type of object given.
      I - The type of object instance to check for.
      Parameters:
      object - The object to examine.
      instanceClass - The class of which the object may be an instance.
      Returns:
      The object if it is an instance of the given class.
      See Also:

    • asInstance

      public static <T, I extends T> Function<T,Optional<I>> asInstance(Class<I> instanceClass)
      Convenience method that returns a function that casts some object to a given class if and only if it is an instance of that class.
      API Note:
      This method may be used to cast an Optional value using optional.flatMap(asInstance(instanceClass). In this way it is equivalent to optional.filter(instanceClass::isInstance).map(instanceClass::cast).
      Implementation Specification:
      This implementation returns a function that delegates to asInstance(Object, Class).
      Type Parameters:
      T - The type of object given.
      I - The type of object instance to check for.
      Parameters:
      instanceClass - The class of which the object may be an instance.
      Returns:
      The a function that returns the object if it is an instance of the given class; otherwise an empty Optional.
      See Also:

    • asInstances

      public static <T, I extends T> Function<T,Stream<I>> asInstances(Class<I> instanceClass)
      Convenience method that returns a function that casts some object to a given class if and only if it is an instance of that class, returning a potentially empty stream.
      API Note:
      This method may be used to cast Stream values using stream.flatMap(asInstances(instanceClass). In this way it is equivalent to stream.filter(instanceClass::isInstance).map(instanceClass::cast).
      Implementation Specification:
      This implementation returns a function that delegates to asInstance(Object, Class).
      Type Parameters:
      T - The type of object given.
      I - The type of object instance to check for.
      Parameters:
      instanceClass - The class of which the object may be an instance.
      Returns:
      The a function that returns the object if it is an instance of the given class; otherwise an empty Stream.
      See Also:

    • equals

      @Deprecated public static final boolean equals(Object object1, Object object2)
      Deprecated.
      to be removed in favor of Objects.equals(Object, Object) from Java 7.
      Compares two objects to make sure that the objects are equal, or the objects are both set to null. If the first object is not null, it is compared to the second using the first object's Object.equals(Object) method. This is a convenience method to compare two objects using the Object.equals(Object) method when it's not known if one of the objects is null.
      Parameters:
      object1 - The first object to compare.
      object2 - The second object to compare.
      Returns:
      true if the objects are equal according to the first object's Object.equals(Object) method or if both objects are null.
      See Also:

    • getInstance

      @SafeVarargs public static <T> T getInstance(T... objects)
      Returns the first object that is an instance of Object (i.e. that is not null).
      Type Parameters:
      T - The type of the objects.
      Parameters:
      objects - The objects to investigate.
      Returns:
      The first object that is not null, or null if all objects are null.

    • getInstance

      @SafeVarargs public static <T, C extends T> C getInstance(Class<C> objectClass, T... objects)
      Returns the first object that is an instance of the given object type.
      Type Parameters:
      T - The type of the objects.
      C - The subtype of the given objects.
      Parameters:
      objectClass - The class of the type of object to return
      objects - The objects to investigate.
      Returns:
      The first object that is the instance of the given type, or null if no object is an instance of the indicated type.
      Throws:
      NullPointerException - if the given object class is null.

    • toInstance

      public static <T> T toInstance(T object, T defaultInstance)
      Returns either and object or a default instance if the object is null.

      This is equivalent to the JavaScript statement var x = object || defaultInstance;

      Type Parameters:
      T - The type of the object.
      Parameters:
      object - The object to examine.
      defaultInstance - The default instance to return if the object is null.
      Returns:
      The object, or the default instance of the object is null.
      Throws:
      NullPointerException - if the given default instance is null.

    • getProperty

      public static Object getProperty(Object object, String propertyName) throws NoSuchMethodException, InvocationTargetException, IllegalAccessException
      Returns the property of an object based upon a given property name. A property getter in the form "getPropertyName" takes precedence over a property getter in the form "isPropertyName" having a Boolean.TYPE.
      Parameters:
      object - The object the property of which to retrieve.
      propertyName - The name of the property to retrieve.
      Returns:
      The value of the given property.
      Throws:
      NullPointerException - if the given object is null.
      NoSuchMethodException - if the given object has no method with the name "getPropertyName", or the name "isPropertyName" having a Boolean.TYPE.
      IllegalAccessException - if the getter method enforces Java language access control and the getter method is inaccessible.
      InvocationTargetException - if the getter method throws an exception.
      ExceptionInInitializerError - if the initialization provoked by the getter method fails.

    • getHashCode

      @Deprecated public static int getHashCode(Object... objects)
      Deprecated.
      to be removed in favor of Objects.hash(Object...) from Java 7.
      Generates a hash code based upon a series of objects. This method is based upon the algorithm explained in Effective Java (2001) by Joshua Bloch (pp. 38-39) as well as the hash code generation of the Java runtime library. Any or all objects can be null. Arrays are deeply traversed. This methods delegates to getSeededHashCode(int, Object...) with a seed value of 17.
      Parameters:
      objects - The objects to be used in generating a hash code.
      Returns:
      A hash code taking into account the given objects.
      Throws:
      NullPointerException - if the given array of objects is null.

    • getSeededHashCode

      @Deprecated public static int getSeededHashCode(int seed, Object... objects)
      Deprecated.
      Generates a hash code based upon a seed and a series of objects. This method is based upon the algorithm explained in Effective Java (2001) by Joshua Bloch (pp. 38-39) as well as the hash code generation of the Java runtime library. Any or all objects can be null. Arrays are deeply traversed.
      Parameters:
      seed - The seed with which to start.
      objects - The objects to be used in generating a hash code.
      Returns:
      A hash code starting with the given seed and taking into account the given objects.
      Throws:
      NullPointerException - if the given array of objects is null.

    • getIntHashCode

      @Deprecated public static int getIntHashCode(int... values)
      Deprecated.
      Generates a hash code based upon a series of integer values. This is a convenience varargs method that delegates to the Arrays.hashCode(int[]) version.
      Parameters:
      values - The values to be used in generating a hash code.
      Returns:
      A hash code taking into account the given values.
      Throws:
      NullPointerException - if the given array of values is null.
      See Also:

    • getLongHashCode

      @Deprecated public static int getLongHashCode(long... values)
      Deprecated.
      Generates a hash code based upon a series of long values. This is a convenience varargs method that delegates to the Arrays.hashCode(long[]) version.
      Parameters:
      values - The values to be used in generating a hash code.
      Returns:
      A hash code taking into account the given values.
      Throws:
      NullPointerException - if the given array of values is null.
      See Also:

    • getDoubleHashCode

      @Deprecated public static int getDoubleHashCode(double... values)
      Deprecated.
      Generates a hash code based upon a series of integer values. This is a convenience varargs method that delegates to the Arrays.hashCode(double[]) version.
      Parameters:
      values - The values to be used in generating a hash code.
      Returns:
      A hash code taking into account the given values.
      Throws:
      NullPointerException - if the given array of values is null.
      See Also:

    • getInstanceOf

      public static Class<?> getInstanceOf(Object object, Class<?>... classes)
      Determines of which, if any, of the provided classes the given object is an instance.
      Parameters:
      object - The object to check as an instance; may be null.
      classes - The classes of which to check the given object being an instance.
      Returns:
      The first of the listed classes of which the given object is an instance, or null if the object is not an instance of any of the listed classes.

    • isInstanceOf

      public static boolean isInstanceOf(Object object, Class<?>... classes)
      Determines if the object is an instance of any of the provided classes.
      Parameters:
      object - The object to check as an instance; may be null.
      classes - The classes of which to check the given object being an instance.
      Returns:
      true if the object is an instance of one of the listed classes.

    • requireNonNulls

      public static Object[] requireNonNulls(Object... objects)
      Checks to see if the elements are instances of any object, and throws a NullPointerException if any element is null.
      Parameters:
      objects - The objects of which to check.
      Returns:
      The given objects.
      Throws:
      NullPointerException - if any of the given objects are null.

    • toAutoCloseable

      public static AutoCloseable toAutoCloseable(@Nonnull Object object)
      Converts an object to an AutoCloseable instance so that it can be used with try-with-resources.
      API Note:
      The Exception thrown by the AutoCloseable interface may be too broad; the IO.toCloseable(Object) method converts to an interface with more limited exceptions allowed.
      Implementation Specification:
      If the given object is an instance of AutoCloseable, the object itself is returned; otherwise, a no-operation AutoCloseable instance is returned.
      Parameters:
      object - The object to convert to an AutoCloseable.
      Returns:
      An AutoCloseable instance that will ensure the object is closed if it implements AutoCloseable.
      See Also:

    • toString

      public static final String toString(Object object)
      Returns the string representation of the object or "null".
      Parameters:
      object - An object to be represented by a string.
      Returns:
      The string representation of the object or "null" if the object is null.