Module iu.util
Package edu.iu

Class IuObject

java.lang.Object
edu.iu.IuObject
public final class IuObject extends Object
Simplifies building efficient Object.equals(Object), Object.hashCode(), and Comparable.compareTo(Object) methods on plain Java objects.

The use of this utility is preferred, following the examples below, over other methods of generating these methods. When following these examples, the implements can be expected to follow the expected contracts in a null-safe and type-safe manner without undue object creation.

Top level object:
 @Override
 public int hashCode() {
        return ObjectUtil.hashCode(val1, val2);
 }
 
 @Override
 public boolean equals(Object obj) {
        if (!ObjectUtil.typeCheck(this, obj))
                return false;
        MyClass other = (MyClass) obj;
        return ObjectUtil.equals(this.val1, other.val1) && ObjectUtil.equals(this.val2, other.val2);
 }
 
 @Override
 public int compareTo(T o) {
        Integer rv = ObjectUtil.compareNullCheck(this, o);
        if (rv != null)
                return rv;
 
        rv = ObjectUtil.compareTo(this.val1, o.val1);
        if (rv != 0)
                return rv;
 
        return ObjectUtil.compareTo(this.val2, o.val2);
 }
Subclass object:
 @Override
 public int hashCode() {
        return ObjectUtil.hashCodeSuper(super.hashCode(), val1, val2);
 }
 
 @Override
 public boolean equals(Object obj) {
        if (!ObjectUtil.typeCheck(this, obj))
                return false;
        MyClass other = (MyClass) obj;
        return super.equals(obj) && ObjectUtil.equals(this.val1, other.val1) && ObjectUtil.equals(this.val2, other.val2);
 }
 
 @Override
 public int compareTo(T o) {
        Integer rv = ObjectUtil.compareNullCheck(this, o);
        if (rv != null)
                return rv;
 
        rv = ObjectUtil.compareTo(this.val1, o.val1);
        if (rv != 0)
                return rv;
 
        rv = ObjectUtil.compareTo(this.val2, o.val2);
        if (rv != 0)
                return rv;
 
        return super.compareTo(o);
 }
Since:
4.0

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    assertNotOpen(Class<?> classToCheck)
    Asserts that a class is in a module that is named and part of a package that is not open.
    static Integer
    compareNullCheck(Object o1, Object o2)
    Perform identity and and null check on two objects, returning a valid value for Comparable.compareTo(Object) if any of the checks result in a conclusive result.
    static int
    compareTo(Object o1, Object o2)
    Compares two objects with null checks (see compareNullCheck(Object, Object)) and also consistent sort order based for objects that don't implement Comparable.
    static <S, T> T
    convert(S value, Function<S,T> conversionFunction)
    Passes a value through a conversion function if non-null.
    static boolean
    equals(Object o1, Object o2)
    Determine if two objects are equal, checking first for identity and null.
    static <T> T
    first(T... values)
    Gets the first non-null, after enforces that all remaining values are either null or equal to the first value.
    static <T> T
    first(T current, T value, Supplier<String> messageSupplier)
    Enforces that a value is either not already set or is already set to the same value.
    static int
    hashCode(Object... oa)
    Generates a hash code for a top-level object based on related values (i.e.
    static int
    hashCodeSuper(int superHashCode, Object... oa)
    Generate a hash code for a subclass object based on its parent class' hash code and related values.
    static boolean
    isPlatformName(String name)
    Determines if a name is relative to a package provided by the JDK or JEE platform.
    static <T> T
    once(T current, T value)
    Enforces that either a current or new value is non-null, and that both non-null values are equal.
    static <T> T
    once(T current, T value, String message)
    Enforces that either a current or new value is non-null, and that both non-null values are equal.
    static <T> T
    once(T current, T value, Supplier<String> messageSupplier)
    Enforces that either a current or new value is non-null, and that both non-null values are equal.
    static boolean
    represents(Object a, Object b)
    Determines if either or both objects are null, then if both non-null if both are equals(Object, Object).
    static <T> T
    require(T value, Predicate<T> condition)
    Require a condition to be true for a value.
    static <T> T
    require(T value, Predicate<T> condition, String message)
    Require a condition to be true for a value if non-null.
    static <T> T
    require(T value, Predicate<T> condition, Supplier<String> messageSupplier)
    Require a condition to be true for a value if non-null.
    static Class<?>
    requireFinalImpl(Class<?> type)
    Determines if a class is a final implementation class.
    static <T> T
    requireType(Class<T> type, Object value)
    Require value to be an instance of a specific type or null.
    static <T> boolean
    typeCheck(T o1, T o2)
    Determine if two objects are both non-null instances of the same class.
    static <T> boolean
    typeCheck(T o1, T o2, Class<?> type)
    Determine if two objects are both instances of a specific class, or subclasses of that class.
    static void
    waitFor(Object lock, BooleanSupplier condition, Duration timeout)
    Waits until a condition is met or a timeout interval expires.
    static void
    waitFor(Object lock, BooleanSupplier condition, Duration timeout, Supplier<TimeoutException> timeoutFactory)
    Waits until a condition is met or a timeout interval expires.
    static void
    waitFor(Object lock, BooleanSupplier condition, Instant expires)
    Waits until a condition is met or a timeout interval expires.
    static void
    waitFor(Object lock, BooleanSupplier condition, Instant expires, Supplier<TimeoutException> timeoutFactory)
    Waits until a condition is met or a timeout interval expires.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • isPlatformName

      public static boolean isPlatformName(String name)
      Determines if a name is relative to a package provided by the JDK or JEE platform.
      Parameters:
      name - type name
      Returns:
      true if a platform type; else false

    • assertNotOpen

      public static void assertNotOpen(Class<?> classToCheck) throws IllegalStateException
      Asserts that a class is in a module that is named and part of a package that is not open.
      Parameters:
      classToCheck - Class
      Throws:
      IllegalStateException - if the class is in an open module and/or package

    • requireFinalImpl

      public static Class<?> requireFinalImpl(Class<?> type)
      Determines if a class is a final implementation class.
      Parameters:
      type - type
      Returns:
      true if the class is not an interface and includes the final modifier

    • once

      public static <T> T once(T current, T value)
      Enforces that either a current or new value is non-null, and that both non-null values are equal.
      Type Parameters:
      T - value type
      Parameters:
      current - current value
      value - value to set or enforce as already set
      Returns:
      value
      Throws:
      IllegalArgumentException - if already set to the same value

    • once

      public static <T> T once(T current, T value, String message)
      Enforces that either a current or new value is non-null, and that both non-null values are equal.
      Type Parameters:
      T - value type
      Parameters:
      current - current value
      value - value to set or enforce as already set
      message - message for IllegalArgumentException if current was already set to a different value
      Returns:
      value
      Throws:
      IllegalArgumentException - if already set to the same value

    • once

      public static <T> T once(T current, T value, Supplier<String> messageSupplier)
      Enforces that either a current or new value is non-null, and that both non-null values are equal.
      Type Parameters:
      T - value type
      Parameters:
      current - current value
      value - value to set or enforce as already set
      messageSupplier - provides a message for IllegalArgumentException if current was already set to a different value
      Returns:
      value
      Throws:
      IllegalArgumentException - if already set to the same value

    • first

      @SafeVarargs public static <T> T first(T... values)
      Gets the first non-null, after enforces that all remaining values are either null or equal to the first value.
      Type Parameters:
      T - value type
      Parameters:
      values - values to set or enforce as already set
      Returns:
      first non-null value
      Throws:
      IllegalArgumentException - if any values are non-null and not equal to the returned value

    • first

      public static <T> T first(T current, T value, Supplier<String> messageSupplier)
      Enforces that a value is either not already set or is already set to the same value.
      Type Parameters:
      T - value type
      Parameters:
      current - current value
      value - value to set or enforce as already set
      messageSupplier - provides a message for IllegalArgumentException if current was already set to a different value
      Returns:
      value
      Throws:
      IllegalArgumentException - if already set to the same value

    • represents

      public static boolean represents(Object a, Object b)
      Determines if either or both objects are null, then if both non-null if both are equals(Object, Object).

      This method is the boolean equivalent of first(Object...)

      Parameters:
      a - an object
      b - another object
      Returns:
      true if either object is null or if both are equal; else false

    • requireType

      public static <T> T requireType(Class<T> type, Object value)
      Require value to be an instance of a specific type or null.
      Type Parameters:
      T - required type
      Parameters:
      type - required type
      value - value
      Returns:
      typed value
      Throws:
      IllegalArgumentException - if the types don't match

    • require

      public static <T> T require(T value, Predicate<T> condition)
      Require a condition to be true for a value.
      Type Parameters:
      T - value type
      Parameters:
      value - value
      condition - condition to verify
      Returns:
      value
      Throws:
      IllegalArgumentException - if the types don't match

    • require

      public static <T> T require(T value, Predicate<T> condition, String message)
      Require a condition to be true for a value if non-null.
      Type Parameters:
      T - value type
      Parameters:
      value - value
      condition - condition to verify
      message - provides a message for IllegalArgumentException
      Returns:
      value
      Throws:
      IllegalArgumentException - if the types don't match

    • require

      public static <T> T require(T value, Predicate<T> condition, Supplier<String> messageSupplier)
      Require a condition to be true for a value if non-null.
      Type Parameters:
      T - value type
      Parameters:
      value - value
      condition - condition to verify
      messageSupplier - provides a message for IllegalArgumentException
      Returns:
      value
      Throws:
      IllegalArgumentException - if the types don't match

    • convert

      public static <S, T> T convert(S value, Function<S,T> conversionFunction)
      Passes a value through a conversion function if non-null.
      Type Parameters:
      S - source type
      T - result type
      Parameters:
      value - value
      conversionFunction - conversion function
      Returns:
      converted value

    • compareNullCheck

      public static Integer compareNullCheck(Object o1, Object o2)
      Perform identity and and null check on two objects, returning a valid value for Comparable.compareTo(Object) if any of the checks result in a conclusive result.
      Parameters:
      o1 - any object
      o2 - any object
      Returns:
      0 if o1 == o2, -1 if o1 is null, 1 if o2 is null; otherwise, return null indicating that compareTo should continue to inspect each object's specific data.

    • compareTo

      public static int compareTo(Object o1, Object o2)
      Compares two objects with null checks (see compareNullCheck(Object, Object)) and also consistent sort order based for objects that don't implement Comparable.
      Parameters:
      o1 - any object
      o2 - any object
      Returns:
      Valid Comparator return value enforcing consistent sort order within the same JVM instance.

    • hashCode

      public static int hashCode(Object... oa)
      Generates a hash code for a top-level object based on related values (i.e. field, bean property values, etc).
      Parameters:
      oa - related values
      Returns:
      hash code

    • hashCodeSuper

      public static int hashCodeSuper(int superHashCode, Object... oa)
      Generate a hash code for a subclass object based on its parent class' hash code and related values.
      Parameters:
      superHashCode - parent class hash code
      oa - related values
      Returns:
      hash code

    • typeCheck

      public static <T> boolean typeCheck(T o1, T o2)
      Determine if two objects are both non-null instances of the same class. This method is useful as a null and type safety check when implementing equals. If this returns true, and the type of one of the objects is known, then it is safe to cast the other object to the same type.
      Type Parameters:
      T - object type
      Parameters:
      o1 - any object
      o2 - any object
      Returns:
      True if both objects are not null and instances of the same class.

    • typeCheck

      public static <T> boolean typeCheck(T o1, T o2, Class<?> type)
      Determine if two objects are both instances of a specific class, or subclasses of that class. This method is useful as a null and type safety check when implementing equals. If this returns true, then it is safe to cast the both objects to the type provided.
      Type Parameters:
      T - object type
      Parameters:
      o1 - any object
      o2 - any object
      type - the type to check, may be null for the behavior outlined in typeCheck(Object, Object).
      Returns:
      True if both objects are not null and instances of the given type, or are the same class if type is null.

    • equals

      public static boolean equals(Object o1, Object o2)
      Determine if two objects are equal, checking first for identity and null.
      Parameters:
      o1 - any object
      o2 - any object
      Returns:
      true if o1 and o2 refer to the same object, are both null, or if o1.equals(o2) returns true. Otherwise, return false.

    • waitFor

      public static void waitFor(Object lock, BooleanSupplier condition, Duration timeout) throws InterruptedException, TimeoutException
      Waits until a condition is met or a timeout interval expires.
      Parameters:
      lock - object to synchronize on
      condition - condition to wait for
      timeout - timeout interval
      Throws:
      InterruptedException - if the current thread is interrupted while waiting for the condition to be met
      TimeoutException - if the timeout interval expires before the condition is met

    • waitFor

      public static void waitFor(Object lock, BooleanSupplier condition, Duration timeout, Supplier<TimeoutException> timeoutFactory) throws InterruptedException, TimeoutException
      Waits until a condition is met or a timeout interval expires.
      Parameters:
      lock - object to synchronize on
      condition - condition to wait for
      timeout - timeout interval
      timeoutFactory - creates a timeout exception to be thrown if the condition is not met before the expiration time
      Throws:
      InterruptedException - if the current thread is interrupted while waiting for the condition to be met
      TimeoutException - if the timeout interval expires before the condition is met

    • waitFor

      public static void waitFor(Object lock, BooleanSupplier condition, Instant expires) throws InterruptedException, TimeoutException
      Waits until a condition is met or a timeout interval expires.
      Parameters:
      lock - object to synchronize on to receive status change notifications
      condition - condition to wait for
      expires - timeout interval expiration time
      Throws:
      InterruptedException - if the current thread is interrupted while waiting for the condition to be met
      TimeoutException - if the timeout interval expires before the condition is met

    • waitFor

      public static void waitFor(Object lock, BooleanSupplier condition, Instant expires, Supplier<TimeoutException> timeoutFactory) throws InterruptedException, TimeoutException
      Waits until a condition is met or a timeout interval expires.
      Parameters:
      lock - object to synchronize on to receive status change notifications
      condition - condition to wait for
      expires - timeout interval expiration time
      timeoutFactory - creates a timeout exception to be thrown if the condition is not met before the expiration time
      Throws:
      InterruptedException - if the current thread is interrupted while waiting for the condition to be met
      TimeoutException - if the timeout interval expires before the condition is met