Package com.globalmentor.java

Class Objects

java.lang.Object

com.globalmentor.java.Objects

public class Objects
extends java.lang.Object

Various utilities to manipulate Java objects.

Author:

Garret Wilson

Field Summary

Fields

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

Method Summary

Modifier and Type	Method	Description
static <T> java.util.Optional<T>	asInstance(java.lang.Object object, java.lang.Class<T> instanceClass)	Convenience method that returns the given object if and only if it is an instance of the given class.
static <T> T	checkType(java.lang.Object variable, java.lang.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(java.lang.Object variable, java.lang.Class<T> type, java.lang.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 java.lang.Comparable<? super T>> int	compare(T object1, T object2, int nullBias)	Compares two objects for order, taking into account null.
static boolean	equals(java.lang.Object object1, java.lang.Object object2)	Compares two objects to make sure that the objects are equal, or the objects are both set to null.
static int	getDoubleHashCode(double... values)	Deprecated.
static int	getHashCode(java.lang.Object... objects)	Deprecated. Use Objects.hash(Object...) from Java 7 instead.
static <T,C extends T> C	getInstance(java.lang.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 java.lang.Class<?>	getInstanceOf(java.lang.Object object, java.lang.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 java.lang.Object	getProperty(java.lang.Object object, java.lang.String propertyName)	Returns the property of an object based upon a given property name.
static int	getSeededHashCode(int seed, java.lang.Object... objects)	Deprecated.
static boolean	isInstanceOf(java.lang.Object object, java.lang.Class<?>... classes)	Determines if the object is an instance of any of the provided classes.
static java.lang.Object[]	requireNonNulls(java.lang.Object... objects)	Checks to see if the elements are instances of any object, and throws a NullPointerException if any element is null.
static <T> T	toInstance(T object, T defaultInstance)	Returns either and object or a default instance if the object is null.
static java.lang.String	toString(java.lang.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 Detail

NO_OBJECTS

public static final java.lang.Object[] NO_OBJECTS

A shared object array that contains no elements.

Method Detail

checkType

public static <T> T checkType(java.lang.Object variable,
                              java.lang.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:

java.lang.ClassCastException - if the given variable is not null and not an instance of type type.

checkType

public static <T> T checkType(java.lang.Object variable,
                              java.lang.Class<T> type,
                              java.lang.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:

java.lang.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:

java.lang.IllegalStateException - if the object's CloneSupported.clone() method throws a CloneNotSupportedException.

See Also:

CloneSupported.clone()

compare

public static <T extends java.lang.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> java.util.Optional<T> asInstance(java.lang.Object object,
                                                   java.lang.Class<T> 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 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, otherwise null.

equals

public static final boolean equals(java.lang.Object object1,
                                   java.lang.Object object2)

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:

Object.equals(Object)

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(java.lang.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:

java.lang.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:

java.lang.NullPointerException - if the given default instance is null.

getProperty

public static java.lang.Object getProperty(java.lang.Object object,
                                           java.lang.String propertyName)
                                    throws java.lang.NoSuchMethodException,
                                           java.lang.reflect.InvocationTargetException,
                                           java.lang.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:

java.lang.NullPointerException - if the given object is null.

java.lang.NoSuchMethodException - if the given object has no method with the name "getPropertyName", or the name "isPropertyName" having a Boolean.TYPE.

java.lang.IllegalAccessException - if the getter method enforces Java language access control and the getter method is inaccessible.

java.lang.reflect.InvocationTargetException - if the getter method throws an exception.

java.lang.ExceptionInInitializerError - if the initialization provoked by the getter method fails.

getHashCode

@Deprecated
public static int getHashCode(java.lang.Object... objects)

Deprecated.

Use Objects.hash(Object...) from Java 7 instead.

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:

java.lang.NullPointerException - if the given array of objects is null.

getSeededHashCode

@Deprecated
public static int getSeededHashCode(int seed,
                                    java.lang.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:

java.lang.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:

java.lang.NullPointerException - if the given array of values is null.

See Also:

Arrays.hashCode(int[])

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:

java.lang.NullPointerException - if the given array of values is null.

See Also:

Arrays.hashCode(long[])

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:

java.lang.NullPointerException - if the given array of values is null.

See Also:

Arrays.hashCode(double[])

getInstanceOf

public static java.lang.Class<?> getInstanceOf(java.lang.Object object,
                                               java.lang.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(java.lang.Object object,
                                   java.lang.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 java.lang.Object[] requireNonNulls(java.lang.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:

java.lang.NullPointerException - if any of the given objects are null.

toString

public static final java.lang.String toString(java.lang.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.