Objects
Date: 2016-05-24

com.google.common.base

## Class Objects

- java.lang.Object
- - com.google.common.base.Objects

-     @GwtCompatible
      public final class Objects
      extends java.lang.Object

  Helper functions that can operate on any `Object`.

  See the Guava User Guide on writing `Object` methods with `Objects`.

  Since:
    2.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Objects.ToStringHelper` Deprecated. Use `MoreObjects.ToStringHelper` instead. This class is scheduled for removal in June 2016.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `equal(java.lang.Object a, java.lang.Object b)` Determines whether two possibly-null objects are equal.
    `static <T> T` | `firstNonNull(T first, T second)` Deprecated. Use `MoreObjects.firstNonNull(T, T)` instead. This method is scheduled for removal in June 2016.
    `static int` | `hashCode(java.lang.Object... objects)` Generates a hash code for multiple values.
    `static Objects.ToStringHelper` | `toStringHelper(java.lang.Class<?> clazz)` Deprecated. Use `MoreObjects.toStringHelper(Class)` instead. This method is scheduled for removal in June 2016.
    `static Objects.ToStringHelper` | `toStringHelper(java.lang.Object self)` Deprecated. Use `MoreObjects.toStringHelper(Object)` instead. This method is scheduled for removal in June 2016.
    `static Objects.ToStringHelper` | `toStringHelper(java.lang.String className)` Deprecated. Use `MoreObjects.toStringHelper(String)` instead. This method is scheduled for removal in June 2016.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### equal

          @CheckReturnValue
          public static boolean equal(@Nullable
                                       java.lang.Object a,
                                       @Nullable
                                       java.lang.Object b)

      Determines whether two possibly-null objects are equal. Returns:
      - `true` if `a` and `b` are both null.
      - `true` if `a` and `b` are both non-null and they are equal according to `Object.equals(Object)`.
      - `false` in all other situations.

      This assumes that any non-null objects passed to this function conform to the `equals()` contract.

      Note for Java 7 and later: This method should be treated as deprecated; use `Objects.equals(java.lang.Object, java.lang.Object)` instead.

    - #### hashCode

          @CheckReturnValue
          public static int hashCode(@Nullable
                                      java.lang.Object... objects)

      Generates a hash code for multiple values. The hash code is generated by calling `Arrays.hashCode(Object[])`. Note that array arguments to this method, with the exception of a single Object array, do not get any special handling; their hash codes are based on identity and not contents.

      This is useful for implementing `Object.hashCode()`. For example, in an object that has three properties, `x`, `y`, and `z`, one could write:

             public int hashCode() {
               return Objects.hashCode(getX(), getY(), getZ());
             }

      Warning: When a single object is supplied, the returned hash code does not equal the hash code of that object.

      Note for Java 7 and later: This method should be treated as deprecated; use `Objects.hash(java.lang.Object...)` instead.

    - #### toStringHelper

          @CheckReturnValue
          @Deprecated
          public static Objects.ToStringHelper toStringHelper(java.lang.Object self)

      Deprecated. Use `MoreObjects.toStringHelper(Object)` instead. This method is scheduled for removal in June 2016.
      Creates an instance of `Objects.ToStringHelper`.

      This is helpful for implementing `Object.toString()`. Specification by example:

             // Returns "ClassName{}"
             Objects.toStringHelper(this)
                 .toString();

             // Returns "ClassName{x=1}"
             Objects.toStringHelper(this)
                 .add("x", 1)
                 .toString();

             // Returns "MyObject{x=1}"
             Objects.toStringHelper("MyObject")
                 .add("x", 1)
                 .toString();

             // Returns "ClassName{x=1, y=foo}"
             Objects.toStringHelper(this)
                 .add("x", 1)
                 .add("y", "foo")
                 .toString();

             // Returns "ClassName{x=1}"
             Objects.toStringHelper(this)
                 .omitNullValues()
                 .add("x", 1)
                 .add("y", null)
                 .toString();
             }

      Note that in GWT, class names are often obfuscated.

      Parameters:
        `self` - the object to generate the string for (typically `this`), used only for its class name
      Since:
        2.0

    - #### toStringHelper

          @CheckReturnValue
          @Deprecated
          public static Objects.ToStringHelper toStringHelper(java.lang.Class<?> clazz)

      Deprecated. Use `MoreObjects.toStringHelper(Class)` instead. This method is scheduled for removal in June 2016.
      Creates an instance of `Objects.ToStringHelper` in the same manner as `toStringHelper(Object)`, but using the name of `clazz` instead of using an instance's `Object.getClass()`.

      Note that in GWT, class names are often obfuscated.

      Parameters:
        `clazz` - the `Class` of the instance
      Since:
        7.0 (source-compatible since 2.0)

    - #### toStringHelper

          @CheckReturnValue
          @Deprecated
          public static Objects.ToStringHelper toStringHelper(java.lang.String className)

      Deprecated. Use `MoreObjects.toStringHelper(String)` instead. This method is scheduled for removal in June 2016.
      Creates an instance of `Objects.ToStringHelper` in the same manner as `toStringHelper(Object)`, but using `className` instead of using an instance's `Object.getClass()`.
      Parameters:
        `className` - the name of the instance type
      Since:
        7.0 (source-compatible since 2.0)

    - #### firstNonNull

          @CheckReturnValue
          @Deprecated
          public static <T> T firstNonNull(@Nullable
                                                       T first,
                                                       @Nullable
                                                       T second)

      Deprecated. Use `MoreObjects.firstNonNull(T, T)` instead. This method is scheduled for removal in June 2016.
      Returns the first of two given parameters that is not `null`, if either is, or otherwise throws a `NullPointerException`.

      Note: if `first` is represented as an `Optional`, this can be accomplished with first.or(second). That approach also allows for lazy evaluation of the fallback instance, using first.or(Supplier).

      Returns:
        `first` if `first` is not `null`, or `second` if `first` is `null` and `second` is not `null`
      Throws:
        `java.lang.NullPointerException` - if both `first` and `second` were `null`
      Since:
        3.0