org.geotools.util
Class Utilities

Object
  extended by Utilities

public final class Utilities
extends Object

Miscellaneous methods, including cnvenience methods for equals and hashCode implementations. Example use case in a class called Car:

 public boolean equals(Object other) {
     if (this == aThat) {
         return true;
     }
     if (other == null || !other.getClass().equals(getClass())) {
         return false;
     }
     Car that = (Car) other;
     return Utilities.equals(this.name,              that.name)       &&
            Utilities.equals(this.numDoors,          that.numDoors)   &&
            Utilities.equals(this.gasMileage,        that.gasMileage) &&
            Utilities.equals(this.color,             that.color)      &&
            Arrays   .equals(this.maintenanceChecks, that.maintenanceChecks);
 }
 
Note the usage of Arrays method for comparing arrays.

This class also provides convenience methods for computing hash code values. All those methods expect a seed argument, which is the hash code value computed for previous fields in a class. For the initial seed (the one for the field for which to compute an hash code), an arbitrary value must be provided. We suggest a different number for different class in order to reduce the risk of collision between "empty" instances of different classes. Serializable classes can use (int) serialVersionUID for example.

Since:
2.5
Author:
Martin Desruisseaux (IRD)
Module:
modules/library/metadata (gt-metadata.jar)

Method Summary
static boolean deepEquals(Object object1, Object object2)
          Convenience method for testing two objects for equality.
static int deepHashCode(Object object)
          Returns a hash code for the specified object, which may be an array.
static String deepToString(Object object)
          Returns a string representation of the specified object, which may be an array.
static
<E> Queue<E>
emptyQueue()
          Returns a queue which is always empty and accepts no element.
static void ensureNonNull(String name, Object object)
          Makes sure that an argument is non-null.
static boolean equals(boolean o1, boolean o2)
          Returns true if the given booleans are equals.
static boolean equals(byte o1, byte o2)
          Returns true if the given bytes are equals.
static boolean equals(char o1, char o2)
          Returns true if the given characters are equals.
static boolean equals(double o1, double o2)
          Returns true if the given doubles are equals.
static boolean equals(float o1, float o2)
          Returns true if the given floats are equals.
static boolean equals(int o1, int o2)
          Returns true if the given integers are equals.
static boolean equals(long o1, long o2)
          Returns true if the given longs are equals.
static boolean equals(Object object1, Object object2)
          Convenience method for testing two objects for equality.
static boolean equals(short o1, short o2)
          Returns true if the given shorts are equals.
static int hash(boolean value, int seed)
          Alters the given seed with the hash code value computed from the given value.
static int hash(char value, int seed)
          Alters the given seed with the hash code value computed from the given value.
static int hash(double value, int seed)
          Alters the given seed with the hash code value computed from the given value.
static int hash(float value, int seed)
          Alters the given seed with the hash code value computed from the given value.
static int hash(int value, int seed)
          Alters the given seed with the hash code value computed from the given value.
static int hash(long value, int seed)
          Alters the given seed with the hash code value computed from the given value.
static int hash(Object value, int seed)
          Alters the given seed with the hash code value computed from the given value.
static String spaces(int length)
          Returns a string of the specified length filled with white spaces.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

equals

public static boolean equals(boolean o1,
                             boolean o2)
Returns true if the given booleans are equals. This overloaded flavor is provided only for allowing developper to invoke equals methods without consideration for the argument type.

Parameters:
o1 - The first value to compare.
o2 - The second value to compare.
Returns:
true if both values are equal.
See Also:
Boolean.equals(java.lang.Object)

equals

public static boolean equals(char o1,
                             char o2)
Returns true if the given characters are equals. This overloaded flavor is provided only for allowing developper to invoke equals methods without consideration for the argument type.

Parameters:
o1 - The first value to compare.
o2 - The second value to compare.
Returns:
true if both values are equal.
See Also:
Character.equals(java.lang.Object)

equals

public static boolean equals(byte o1,
                             byte o2)
Returns true if the given bytes are equals. This overloaded flavor is provided only for allowing developper to invoke equals methods without consideration for the argument type.

Parameters:
o1 - The first value to compare.
o2 - The second value to compare.
Returns:
true if both values are equal.
See Also:
Byte.equals(java.lang.Object)

equals

public static boolean equals(short o1,
                             short o2)
Returns true if the given shorts are equals. This overloaded flavor is provided only for allowing developper to invoke equals methods without consideration for the argument type.

Parameters:
o1 - The first value to compare.
o2 - The second value to compare.
Returns:
true if both values are equal.
See Also:
Short.equals(java.lang.Object)

equals

public static boolean equals(int o1,
                             int o2)
Returns true if the given integers are equals. This overloaded flavor is provided only for allowing developper to invoke equals methods without consideration for the argument type.

Parameters:
o1 - The first value to compare.
o2 - The second value to compare.
Returns:
true if both values are equal.
See Also:
Integer.equals(java.lang.Object)

equals

public static boolean equals(long o1,
                             long o2)
Returns true if the given longs are equals. This overloaded flavor is provided only for allowing developper to invoke equals methods without consideration for the argument type.

Parameters:
o1 - The first value to compare.
o2 - The second value to compare.
Returns:
true if both values are equal.
See Also:
Long.equals(java.lang.Object)

equals

public static boolean equals(float o1,
                             float o2)
Returns true if the given floats are equals. Positive and negative zero are considered different, while a NaN value is considered equal to other NaN values.

Parameters:
o1 - The first value to compare.
o2 - The second value to compare.
Returns:
true if both values are equal.
See Also:
Float.equals(java.lang.Object)

equals

public static boolean equals(double o1,
                             double o2)
Returns true if the given doubles are equals. Positive and negative zero are considered different, while a NaN value is considered equal to other NaN values.

Parameters:
o1 - The first value to compare.
o2 - The second value to compare.
Returns:
true if both values are equal.
See Also:
Double.equals(java.lang.Object)

equals

public static boolean equals(Object object1,
                             Object object2)
                      throws AssertionError
Convenience method for testing two objects for equality. One or both objects may be null. This method do not iterates recursively in array elements. If array needs to be compared, use one of Arrays method or deepEquals instead.

Note on assertions: There is no way to ensure at compile time that this method is not invoked with array arguments, while doing so would usually be a program error. Performing a systematic argument check would impose a useless overhead for correctly implemented Object.equals(java.lang.Object) methods. As a compromise we perform this check at runtime only if assertions are enabled. Using assertions for argument check in a public API is usually a deprecated practice, but we make an exception for this particular method.

Note on method overloading: This method could be selected by the compiler for comparing primitive types, because the compiler could perform an auto-boxing and get a result assignable to Object. However it should not occur in practice because overloaded (and more efficient) methods are provided for every primitive types. This is true even when the two arguments are different primitive type because of widening conversions. The only exception is when a boolean argument is mixed with a different primitive type.

Parameters:
object1 - The first object to compare, or null.
object2 - The second object to compare, or null.
Returns:
true if both objects are equal.
Throws:
AssertionError - If assertions are enabled and at least one argument is an array.

deepEquals

public static boolean deepEquals(Object object1,
                                 Object object2)
Convenience method for testing two objects for equality. One or both objects may be null. If both are non-null and are arrays, then every array elements will be compared.

This method may be useful when the objects may or may not be array. If they are known to be arrays, consider using Arrays.deepEquals(Object[],Object[]) or one of its primitive counter-part instead.

Rules for choosing an equals or deepEquals method

Parameters:
object1 - The first object to compare, or null.
object2 - The second object to compare, or null.
Returns:
true if both objects are equal.

hash

public static int hash(boolean value,
                       int seed)
Alters the given seed with the hash code value computed from the given value.

Parameters:
value - The value whose hash code to compute.
seed - The hash code value computed so far. If this method is invoked for the first field, then any arbitrary value (preferrably different for each class) is okay.
Returns:
An updated hash code value.

hash

public static int hash(char value,
                       int seed)
Alters the given seed with the hash code value computed from the given value.

Parameters:
value - The value whose hash code to compute.
seed - The hash code value computed so far. If this method is invoked for the first field, then any arbitrary value (preferably different for each class) is okay.
Returns:
An updated hash code value.

hash

public static int hash(int value,
                       int seed)
Alters the given seed with the hash code value computed from the given value. byte and short primitive types are handled by this method as well through implicit widening conversion.

Parameters:
value - The value whose hash code to compute.
seed - The hash code value computed so far. If this method is invoked for the first field, then any arbitrary value (preferably different for each class) is okay.
Returns:
An updated hash code value.

hash

public static int hash(long value,
                       int seed)
Alters the given seed with the hash code value computed from the given value. byte and short primitive types are handled by this method as well through implicit widening conversion.

Parameters:
value - The value whose hash code to compute.
seed - The hash code value computed so far. If this method is invoked for the first field, then any arbitrary value (preferably different for each class) is okay.
Returns:
An updated hash code value.

hash

public static int hash(float value,
                       int seed)
Alters the given seed with the hash code value computed from the given value.

Parameters:
value - The value whose hash code to compute.
seed - The hash code value computed so far. If this method is invoked for the first field, then any arbitrary value (preferably different for each class) is okay.
Returns:
An updated hash code value.

hash

public static int hash(double value,
                       int seed)
Alters the given seed with the hash code value computed from the given value.

Parameters:
value - The value whose hash code to compute.
seed - The hash code value computed so far. If this method is invoked for the first field, then any arbitrary value (preferably different for each class) is okay.
Returns:
An updated hash code value.

hash

public static int hash(Object value,
                       int seed)
                throws AssertionError
Alters the given seed with the hash code value computed from the given value. The givan object may be null. This method do not iterates recursively in array elements. If array needs to be hashed, use one of Arrays method or deepHashCode instead.

Note on assertions: There is no way to ensure at compile time that this method is not invoked with an array argument, while doing so would usually be a program error. Performing a systematic argument check would impose a useless overhead for correctly implemented Object.hashCode() methods. As a compromise we perform this check at runtime only if assertions are enabled. Using assertions for argument check in a public API is usually a deprecated practice, but we make an exception for this particular method.

Parameters:
value - The value whose hash code to compute, or null.
seed - The hash code value computed so far. If this method is invoked for the first field, then any arbitrary value (preferably different for each class) is okay.
Returns:
An updated hash code value.
Throws:
AssertionError - If assertions are enabled and the given value is an array.

deepHashCode

public static int deepHashCode(Object object)
Returns a hash code for the specified object, which may be an array. This method returns one of the following values:

This method should be invoked only if the object type is declared exactly as Object, not as some subtype like Object[], String or float[]. In the later cases, use the appropriate Arrays method instead.

Parameters:
object - The object to compute hash code. May be null.
Returns:
The hash code of the given object.

deepToString

public static String deepToString(Object object)
Returns a string representation of the specified object, which may be an array. This method returns one of the following values:

This method should be invoked only if the object type is declared exactly as Object, not as some subtype like Object[], Number or float[]. In the later cases, use the appropriate Arrays method instead.

Parameters:
object - The object to format as a string. May be null.
Returns:
A string representation of the given object.

emptyQueue

public static <E> Queue<E> emptyQueue()
Returns a queue which is always empty and accepts no element.

Type Parameters:
E - The type of elements in the empty collection.
Returns:
An empty collection.
See Also:
Collections.emptyList(), Collections.emptySet()

spaces

public static String spaces(int length)
Returns a string of the specified length filled with white spaces. This method tries to return a pre-allocated string if possible.

Parameters:
length - The string length. Negative values are clamped to 0.
Returns:
A string of length length filled with white spaces.

ensureNonNull

public static void ensureNonNull(String name,
                                 Object object)
                          throws NullPointerException
Makes sure that an argument is non-null.

Parameters:
name - Argument name.
object - User argument.
Throws:
NullPointerException - if object is null.


Copyright © 1996-2010 Geotools. All Rights Reserved.