org.apache.commons.lang3

## Class ObjectUtils

- java.lang.Object
- - org.apache.commons.lang3.ObjectUtils

-     public class ObjectUtils
      extends Object

  Operations on `Object`.

  This class tries to handle `null` input gracefully. An exception will generally not be thrown for a `null` input. Each method documents its behaviour in more detail.

  #ThreadSafe#

  Since:
    1.0
  Version:
    $Id: ObjectUtils.java 1552678 2013-12-20 13:59:31Z britter $

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ObjectUtils.Null` Class used as a null placeholder where `null` has another meaning.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static ObjectUtils.Null` | `NULL` Singleton used as a `null` placeholder where `null` has another meaning.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ObjectUtils()` `ObjectUtils` instances should NOT be constructed in standard programming.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> T` | `clone(T obj)` Clone an object.
    `static <T> T` | `cloneIfPossible(T obj)` Clone an object if possible.
    `static <T extends Comparable<? super T>> int` | `compare(T c1, T c2)` Null safe comparison of Comparables.
    `static <T extends Comparable<? super T>> int` | `compare(T c1, T c2, boolean nullGreater)` Null safe comparison of Comparables.
    `static byte` | `CONST_BYTE(int v)` This method returns the provided value unchanged.
    `static short` | `CONST_SHORT(int v)` This method returns the provided value unchanged.
    `static boolean` | `CONST(boolean v)` This method returns the provided value unchanged.
    `static byte` | `CONST(byte v)` This method returns the provided value unchanged.
    `static char` | `CONST(char v)` This method returns the provided value unchanged.
    `static double` | `CONST(double v)` This method returns the provided value unchanged.
    `static float` | `CONST(float v)` This method returns the provided value unchanged.
    `static int` | `CONST(int v)` This method returns the provided value unchanged.
    `static long` | `CONST(long v)` This method returns the provided value unchanged.
    `static short` | `CONST(short v)` This method returns the provided value unchanged.
    `static <T> T` | `CONST(T v)` This method returns the provided value unchanged.
    `static <T> T` | `defaultIfNull(T object, T defaultValue)` Returns a default value if the object passed is `null`.
    `static boolean` | `equals(Object object1, Object object2)` Deprecated. this method has been replaced by `java.util.Objects.equals(Object, Object)` in Java 7 and will be removed from future releases.
    `static <T> T` | `firstNonNull(T... values)` Returns the first value in the array which is not `null`.
    `static int` | `hashCode(Object obj)` Deprecated. this method has been replaced by `java.util.Objects.hashCode(Object)` in Java 7 and will be removed in future releases
    `static int` | `hashCodeMulti(Object... objects)` Deprecated. this method has been replaced by `java.util.Objects.hash(Object...)` in Java 7 an will be removed in future releases.
    `static void` | `identityToString(Appendable appendable, Object object)` Appends the toString that would be produced by `Object` if a class did not override toString itself.
    `static String` | `identityToString(Object object)` Gets the toString that would be produced by `Object` if a class did not override toString itself.
    `static void` | `identityToString(StrBuilder builder, Object object)` Appends the toString that would be produced by `Object` if a class did not override toString itself.
    `static void` | `identityToString(StringBuffer buffer, Object object)` Appends the toString that would be produced by `Object` if a class did not override toString itself.
    `static void` | `identityToString(StringBuilder builder, Object object)` Appends the toString that would be produced by `Object` if a class did not override toString itself.
    `static <T extends Comparable<? super T>> T` | `max(T... values)` Null safe comparison of Comparables.
    `static <T> T` | `median(Comparator<T> comparator, T... items)` Find the "best guess" middle value among comparables.
    `static <T extends Comparable<? super T>> T` | `median(T... items)` Find the "best guess" middle value among comparables.
    `static <T extends Comparable<? super T>> T` | `min(T... values)` Null safe comparison of Comparables.
    `static <T> T` | `mode(T... items)` Find the most frequently occurring item.
    `static boolean` | `notEqual(Object object1, Object object2)` Compares two objects for inequality, where either one or both objects may be `null`.
    `static String` | `toString(Object obj)` Deprecated. this method has been replaced by `java.util.Objects.toString(Object)` in Java 7 and will be removed in future releases. Note however that said method will return "null" for null references, while this method returns and empty String. To preserve behavior use `java.util.Objects.toString(myObject, "")`
    `static String` | `toString(Object obj, String nullStr)` Deprecated. this method has been replaced by `java.util.Objects.toString(Object, String)` in Java 7 and will be removed in future releases.

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

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

- - ### Field Detail

    - #### NULL

          public static final ObjectUtils.Null NULL

      Singleton used as a `null` placeholder where `null` has another meaning.

      For example, in a `HashMap` the `HashMap.get(java.lang.Object)` method returns `null` if the `Map` contains `null` or if there is no matching key. The `Null` placeholder can be used to distinguish between these two cases.

      Another example is `Hashtable`, where `null` cannot be stored.

      This instance is Serializable.

  - ### Constructor Detail

    - #### ObjectUtils

          public ObjectUtils()

      `ObjectUtils` instances should NOT be constructed in standard programming. Instead, the static methods on the class should be used, such as `ObjectUtils.defaultIfNull("a","b");`.

      This constructor is public to permit tools that require a JavaBean instance to operate.

  - ### Method Detail

    - #### defaultIfNull

          public static <T> T defaultIfNull(T object,
                            T defaultValue)

      Returns a default value if the object passed is `null`.

           ObjectUtils.defaultIfNull(null, null)      = null
           ObjectUtils.defaultIfNull(null, "")        = ""
           ObjectUtils.defaultIfNull(null, "zz")      = "zz"
           ObjectUtils.defaultIfNull("abc", *)        = "abc"
           ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE

      Type Parameters:
        `T` - the type of the object
      Parameters:
        `object` - the `Object` to test, may be `null`
        `defaultValue` - the default value to return, may be `null`
      Returns:
        `object` if it is not `null`, defaultValue otherwise

    - #### firstNonNull

          public static <T> T firstNonNull(T... values)

      Returns the first value in the array which is not `null`. If all the values are `null` or the array is `null` or empty then `null` is returned.

           ObjectUtils.firstNonNull(null, null)      = null
           ObjectUtils.firstNonNull(null, "")        = ""
           ObjectUtils.firstNonNull(null, null, "")  = ""
           ObjectUtils.firstNonNull(null, "zz")      = "zz"
           ObjectUtils.firstNonNull("abc", *)        = "abc"
           ObjectUtils.firstNonNull(null, "xyz", *)  = "xyz"
           ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE
           ObjectUtils.firstNonNull()                = null

      Type Parameters:
        `T` - the component type of the array
      Parameters:
        `values` - the values to test, may be `null` or empty
      Returns:
        the first value from `values` which is not `null`, or `null` if there are no non-null values
      Since:
        3.0

    - #### equals

          public static boolean equals(Object object1,
                       Object object2)

      Deprecated. this method has been replaced by `java.util.Objects.equals(Object, Object)` in Java 7 and will be removed from future releases.

      Compares two objects for equality, where either one or both objects may be `null`.

           ObjectUtils.equals(null, null)                  = true
           ObjectUtils.equals(null, "")                    = false
           ObjectUtils.equals("", null)                    = false
           ObjectUtils.equals("", "")                      = true
           ObjectUtils.equals(Boolean.TRUE, null)          = false
           ObjectUtils.equals(Boolean.TRUE, "true")        = false
           ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE)  = true
           ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false

      Parameters:
        `object1` - the first object, may be `null`
        `object2` - the second object, may be `null`
      Returns:
        `true` if the values of both objects are the same

    - #### notEqual

          public static boolean notEqual(Object object1,
                         Object object2)

      Compares two objects for inequality, where either one or both objects may be `null`.

           ObjectUtils.notEqual(null, null)                  = false
           ObjectUtils.notEqual(null, "")                    = true
           ObjectUtils.notEqual("", null)                    = true
           ObjectUtils.notEqual("", "")                      = false
           ObjectUtils.notEqual(Boolean.TRUE, null)          = true
           ObjectUtils.notEqual(Boolean.TRUE, "true")        = true
           ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE)  = false
           ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true

      Parameters:
        `object1` - the first object, may be `null`
        `object2` - the second object, may be `null`
      Returns:
        `false` if the values of both objects are the same

    - #### hashCode

          public static int hashCode(Object obj)

      Deprecated. this method has been replaced by `java.util.Objects.hashCode(Object)` in Java 7 and will be removed in future releases

      Gets the hash code of an object returning zero when the object is `null`.

           ObjectUtils.hashCode(null)   = 0
           ObjectUtils.hashCode(obj)    = obj.hashCode()

      Parameters:
        `obj` - the object to obtain the hash code of, may be `null`
      Returns:
        the hash code of the object, or zero if null
      Since:
        2.1

    - #### hashCodeMulti

          public static int hashCodeMulti(Object... objects)

      Deprecated. this method has been replaced by `java.util.Objects.hash(Object...)` in Java 7 an will be removed in future releases.

      Gets the hash code for multiple objects.

      This allows a hash code to be rapidly calculated for a number of objects. The hash code for a single object is the not same as `hashCode(Object)`. The hash code for multiple objects is the same as that calculated by an `ArrayList` containing the specified objects.

           ObjectUtils.hashCodeMulti()                 = 1
           ObjectUtils.hashCodeMulti((Object[]) null)  = 1
           ObjectUtils.hashCodeMulti(a)                = 31 + a.hashCode()
           ObjectUtils.hashCodeMulti(a,b)              = (31 + a.hashCode()) * 31 + b.hashCode()
           ObjectUtils.hashCodeMulti(a,b,c)            = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode()

      Parameters:
        `objects` - the objects to obtain the hash code of, may be `null`
      Returns:
        the hash code of the objects, or zero if null
      Since:
        3.0

    - #### identityToString

          public static String identityToString(Object object)

      Gets the toString that would be produced by `Object` if a class did not override toString itself. `null` will return `null`.

           ObjectUtils.identityToString(null)         = null
           ObjectUtils.identityToString("")           = "java.lang.String@1e23"
           ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa"

      Parameters:
        `object` - the object to create a toString for, may be `null`
      Returns:
        the default toString text, or `null` if `null` passed in

    - #### identityToString

          public static void identityToString(Appendable appendable,
                              Object object)
                                       throws IOException

      Appends the toString that would be produced by `Object` if a class did not override toString itself. `null` will throw a NullPointerException for either of the two parameters.

           ObjectUtils.identityToString(appendable, "")            = appendable.append("java.lang.String@1e23"
           ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa"
           ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa")

      Parameters:
        `appendable` - the appendable to append to
        `object` - the object to create a toString for
      Throws:
        `IOException`
      Since:
        3.2

    - #### identityToString

          public static void identityToString(StrBuilder builder,
                              Object object)

      Appends the toString that would be produced by `Object` if a class did not override toString itself. `null` will throw a NullPointerException for either of the two parameters.

           ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23"
           ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
           ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")

      Parameters:
        `builder` - the builder to append to
        `object` - the object to create a toString for
      Since:
        3.2

    - #### identityToString

          public static void identityToString(StringBuffer buffer,
                              Object object)

      Appends the toString that would be produced by `Object` if a class did not override toString itself. `null` will throw a NullPointerException for either of the two parameters.

           ObjectUtils.identityToString(buf, "")            = buf.append("java.lang.String@1e23"
           ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa"
           ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa")

      Parameters:
        `buffer` - the buffer to append to
        `object` - the object to create a toString for
      Since:
        2.4

    - #### identityToString

          public static void identityToString(StringBuilder builder,
                              Object object)

      Appends the toString that would be produced by `Object` if a class did not override toString itself. `null` will throw a NullPointerException for either of the two parameters.

           ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23"
           ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
           ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")

      Parameters:
        `builder` - the builder to append to
        `object` - the object to create a toString for
      Since:
        3.2

    - #### toString

          public static String toString(Object obj)

      Deprecated. this method has been replaced by `java.util.Objects.toString(Object)` in Java 7 and will be removed in future releases. Note however that said method will return "null" for null references, while this method returns and empty String. To preserve behavior use `java.util.Objects.toString(myObject, "")`

      Gets the `toString` of an `Object` returning an empty string ("") if `null` input.

           ObjectUtils.toString(null)         = ""
           ObjectUtils.toString("")           = ""
           ObjectUtils.toString("bat")        = "bat"
           ObjectUtils.toString(Boolean.TRUE) = "true"

      Parameters:
        `obj` - the Object to `toString`, may be null
      Returns:
        the passed in Object's toString, or `""` if `null` input
      Since:
        2.0
      See Also:
        `StringUtils.defaultString(String)`, `String.valueOf(Object)`

    - #### toString

          public static String toString(Object obj,
                        String nullStr)

      Deprecated. this method has been replaced by `java.util.Objects.toString(Object, String)` in Java 7 and will be removed in future releases.

      Gets the `toString` of an `Object` returning a specified text if `null` input.

           ObjectUtils.toString(null, null)           = null
           ObjectUtils.toString(null, "null")         = "null"
           ObjectUtils.toString("", "null")           = ""
           ObjectUtils.toString("bat", "null")        = "bat"
           ObjectUtils.toString(Boolean.TRUE, "null") = "true"

      Parameters:
        `obj` - the Object to `toString`, may be null
        `nullStr` - the String to return if `null` input, may be null
      Returns:
        the passed in Object's toString, or `nullStr` if `null` input
      Since:
        2.0
      See Also:
        `StringUtils.defaultString(String,String)`, `String.valueOf(Object)`

    - #### min

          public static <T extends Comparable<? super T>> T min(T... values)

      Null safe comparison of Comparables.

      Type Parameters:
        `T` - type of the values processed by this method
      Parameters:
        `values` - the set of comparable values, may be null
      Returns:
        - If any objects are non-null and unequal, the lesser object.
        - If all objects are non-null and equal, the first.
        - If any of the comparables are null, the lesser of the non-null objects.
        - If all the comparables are null, null is returned.

    - #### max

          public static <T extends Comparable<? super T>> T max(T... values)

      Null safe comparison of Comparables.

      Type Parameters:
        `T` - type of the values processed by this method
      Parameters:
        `values` - the set of comparable values, may be null
      Returns:
        - If any objects are non-null and unequal, the greater object.
        - If all objects are non-null and equal, the first.
        - If any of the comparables are null, the greater of the non-null objects.
        - If all the comparables are null, null is returned.

    - #### compare

          public static <T extends Comparable<? super T>> int compare(T c1,
                                                      T c2)

      Null safe comparison of Comparables. `null` is assumed to be less than a non-`null` value.

      Type Parameters:
        `T` - type of the values processed by this method
      Parameters:
        `c1` - the first comparable, may be null
        `c2` - the second comparable, may be null
      Returns:
        a negative value if c1 < c2, zero if c1 = c2 and a positive value if c1 > c2

    - #### compare

          public static <T extends Comparable<? super T>> int compare(T c1,
                                                      T c2,
                                                      boolean nullGreater)

      Null safe comparison of Comparables.

      Type Parameters:
        `T` - type of the values processed by this method
      Parameters:
        `c1` - the first comparable, may be null
        `c2` - the second comparable, may be null
        `nullGreater` - if true `null` is considered greater than a non-`null` value or if false `null` is considered less than a Non-`null` value
      Returns:
        a negative value if c1 < c2, zero if c1 = c2 and a positive value if c1 > c2
      See Also:
        `Comparator.compare(Object, Object)`

    - #### median

          public static <T extends Comparable<? super T>> T median(T... items)

      Find the "best guess" middle value among comparables. If there is an even number of total values, the lower of the two middle values will be returned.
      Type Parameters:
        `T` - type of values processed by this method
      Parameters:
        `items` - to compare
      Returns:
        T at middle position
      Throws:
        `NullPointerException` - if items is `null`
        `IllegalArgumentException` - if items is empty or contains `null` values
      Since:
        3.0.1

    - #### median

          public static <T> T median(Comparator<T> comparator,
                     T... items)

      Find the "best guess" middle value among comparables. If there is an even number of total values, the lower of the two middle values will be returned.
      Type Parameters:
        `T` - type of values processed by this method
      Parameters:
        `comparator` - to use for comparisons
        `items` - to compare
      Returns:
        T at middle position
      Throws:
        `NullPointerException` - if items or comparator is `null`
        `IllegalArgumentException` - if items is empty or contains `null` values
      Since:
        3.0.1

    - #### mode

          public static <T> T mode(T... items)

      Find the most frequently occurring item.
      Type Parameters:
        `T` - type of values processed by this method
      Parameters:
        `items` - to check
      Returns:
        most populous T, `null` if non-unique or no items supplied
      Since:
        3.0.1

    - #### clone

          public static <T> T clone(T obj)

      Clone an object.

      Type Parameters:
        `T` - the type of the object
      Parameters:
        `obj` - the object to clone, null returns null
      Returns:
        the clone if the object implements `Cloneable` otherwise `null`
      Throws:
        `CloneFailedException` - if the object is cloneable and the clone operation fails
      Since:
        3.0

    - #### cloneIfPossible

          public static <T> T cloneIfPossible(T obj)

      Clone an object if possible.

      This method is similar to `clone(Object)`, but will return the provided instance as the return value instead of `null` if the instance is not cloneable. This is more convenient if the caller uses different implementations (e.g. of a service) and some of the implementations do not allow concurrent processing or have state. In such cases the implementation can simply provide a proper clone implementation and the caller's code does not have to change.

      Type Parameters:
        `T` - the type of the object
      Parameters:
        `obj` - the object to clone, null returns null
      Returns:
        the clone if the object implements `Cloneable` otherwise the object itself
      Throws:
        `CloneFailedException` - if the object is cloneable and the clone operation fails
      Since:
        3.0

    - #### CONST

          public static boolean CONST(boolean v)

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true);

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Parameters:
        `v` - the boolean value to return
      Returns:
        the boolean v, unchanged
      Since:
        3.2

    - #### CONST

          public static byte CONST(byte v)

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127);

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Parameters:
        `v` - the byte value to return
      Returns:
        the byte v, unchanged
      Since:
        3.2

    - #### CONST_BYTE

          public static byte CONST_BYTE(int v)
                                 throws IllegalArgumentException

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127);

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Parameters:
        `v` - the byte literal (as an int) value to return
      Returns:
        the byte v, unchanged
      Throws:
        `IllegalArgumentException` - if the value passed to v is larger than a byte, that is, smaller than -128 or larger than 127.
      Since:
        3.2

    - #### CONST

          public static char CONST(char v)

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static char MAGIC_CHAR = ObjectUtils.CONST('a');

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Parameters:
        `v` - the char value to return
      Returns:
        the char v, unchanged
      Since:
        3.2

    - #### CONST

          public static short CONST(short v)

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123);

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Parameters:
        `v` - the short value to return
      Returns:
        the short v, unchanged
      Since:
        3.2

    - #### CONST_SHORT

          public static short CONST_SHORT(int v)
                                   throws IllegalArgumentException

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127);

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Parameters:
        `v` - the short literal (as an int) value to return
      Returns:
        the byte v, unchanged
      Throws:
        `IllegalArgumentException` - if the value passed to v is larger than a short, that is, smaller than -32768 or larger than 32767.
      Since:
        3.2

    - #### CONST

          public static int CONST(int v)

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static int MAGIC_INT = ObjectUtils.CONST(123);

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Parameters:
        `v` - the int value to return
      Returns:
        the int v, unchanged
      Since:
        3.2

    - #### CONST

          public static long CONST(long v)

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static long MAGIC_LONG = ObjectUtils.CONST(123L);

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Parameters:
        `v` - the long value to return
      Returns:
        the long v, unchanged
      Since:
        3.2

    - #### CONST

          public static float CONST(float v)

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f);

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Parameters:
        `v` - the float value to return
      Returns:
        the float v, unchanged
      Since:
        3.2

    - #### CONST

          public static double CONST(double v)

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0);

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Parameters:
        `v` - the double value to return
      Returns:
        the double v, unchanged
      Since:
        3.2

    - #### CONST

          public static <T> T CONST(T v)

      This method returns the provided value unchanged. This can prevent javac from inlining a constant field, e.g.,

               public final static String MAGIC_STRING = ObjectUtils.CONST("abc");

      This way any jars that refer to this field do not have to recompile themselves if the field's value changes at some future date.
      Type Parameters:
        `T` - the Object type
      Parameters:
        `v` - the genericized Object value to return (typically a String).
      Returns:
        the genericized Object v, unchanged (typically a String).
      Since:
        3.2

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.