ErlangValue
Date: 2016-02-29

de.zib.scalaris

## Class ErlangValue

- java.lang.Object
- - de.zib.scalaris.ErlangValue

- All Implemented Interfaces:
    Comparable<ErlangValue>
  Direct Known Subclasses:
    ErlangValueBitString, ErlangValueFastString

      public class ErlangValue
      extends Object
      implements Comparable<ErlangValue>

  Encapsulates a result from a read operation on scalaris. See `ErlangValue(Object)` for a list of compatible types.
  Since:
    3.0
  Version:
    3.19
  Author:
    Nico Kruber, kruber@zib.de

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `ErlangValue.ListElementConverter<T>` Converts list elements to a desired type.
    `static class` | `ErlangValue.StringListElementConverter` Converts list elements to `String`s.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ErlangValue(OtpErlangObject value)` Creates a new object wrapping the given erlang value.
    `ErlangValue(T value)` Creates a new object from a given set of Java types.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `BigInteger` | `bigIntValue()` Returns the Java BigInteger value of the wrapped erlang value.
    `List<byte[]>` | `binaryListValue()` Returns a list of `byte[]` values of the wrapped erlang value.
    `byte[]` | `binaryValue()` Returns the Java byte[] value of the wrapped erlang value.
    `boolean` | `boolValue()` Returns the Java int value of the wrapped erlang value.
    `int` | `compareTo(ErlangValue o)` Compares two erlang values by their string representation (expensive!).
    `static <T> OtpErlangObject` | `convertToErlang(T value)` Converts a (supported) Java type to an `OtpErlangObject`.
    `List<Double>` | `doubleListValue()` Returns a list of `Double` values of the wrapped erlang value.
    `double` | `doubleValue()` Returns the Java double value of the wrapped erlang value.
    `boolean` | `equals(Object obj)`
    `int` | `hashCode()`
    `int` | `intValue()` Returns the Java int value of the wrapped erlang value.
    `<T> List<T>` | `jsonListValue(Class<T> c)` Returns a list of JSON objects (as an instance of the given class) of the wrapped erlang value.
    `Map<String,Object>` | `jsonValue()` Returns a JSON object (as `Map`<String, Object>) of the wrapped erlang value.
    `<T> T` | `jsonValue(Class<T> c)` Returns a JSON object (as an instance of the given class) of the wrapped erlang value.
    `Collection<ErlangValue>` | `listCollectionValue(Class<? extends Collection<ErlangValue>> clazz)` Returns a `Collection` of mixed Java values (wrapped in `ErlangValue` objects) of the wrapped erlang value (internally represented as a list in Erlang).
    `<T> Collection<T>` | `listCollectionValue(Class<? extends Collection<T>> clazz, ErlangValue.ListElementConverter<T> converter)` Returns a `Collection` of mixed Java values of the wrapped erlang value (internally represented as a list in Erlang).
    `List<ErlangValue>` | `listValue()` Returns a list of mixed Java values (wrapped in `ErlangValue` objects) of the wrapped erlang value.
    `<T> List<T>` | `listValue(ErlangValue.ListElementConverter<T> converter)` Returns a list of mixed Java values of the wrapped erlang value.
    `List<Long>` | `longListValue()` Returns a list of `Long` values of the wrapped erlang value.
    `long` | `longValue()` Returns the Java long value of the wrapped erlang value.
    `static OtpErlangList` | `otpObjectToOtpList(OtpErlangObject value)` Converts an `OtpErlangObject` to a `OtpErlangList` taking special care if the OTP library converted a list to an `OtpErlangString`.
    `List<String>` | `stringListValue()` Returns a list of `String` values of the wrapped erlang value.
    `String` | `stringValue()` Returns the Java `String` value of the wrapped erlang value.
    `String` | `toString()`
    `OtpErlangObject` | `value()` Gets the original erlang value.

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

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ErlangValue

          public ErlangValue(OtpErlangObject value)

      Creates a new object wrapping the given erlang value.
      Parameters:
        `value` - a value from erlang

    - #### ErlangValue

          public ErlangValue(T value)
                      throws ClassCastException

      Creates a new object from a given set of Java types. The following types are supported:

      ## native types

      - `Boolean` - `OtpErlangBoolean`
      - `Long` - `OtpErlangLong`
      - `Integer` - `OtpErlangLong`
      - `BigInteger` - `OtpErlangLong`
      - `Double` - `OtpErlangDouble`
      - `String` - `OtpErlangString`
      - `byte[]` - `OtpErlangBinary`

      ## composite types

      - `List`<Object> with one of the native types except `byte[]` or another (supported) list/map - `OtpErlangList`
      - `Collection`<Object> same as `List`<Object> (internally represented as a list)
      - `Map`<String, Object> representing a JSON object - `OtpErlangTuple`

      ## custom types

      - `OtpErlangObject` - an arbitrary erlang value
      - `ErlangValue`
      Type Parameters:
        `T` - the type of the value
      Parameters:
        `value` - the value to convert to an erlang type
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported

  - ### Method Detail

    - #### convertToErlang

          public static <T> OtpErlangObject convertToErlang(T value)
                                                 throws ClassCastException

      Converts a (supported) Java type to an `OtpErlangObject`.
      Type Parameters:
        `T` - the type of the value
      Parameters:
        `value` - the value to convert to an erlang type
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported

    - #### boolValue

          public boolean boolValue()
                            throws ClassCastException

      Returns the Java int value of the wrapped erlang value.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported or the value is too big
      Since:
        3.3

    - #### intValue

          public int intValue()
                       throws ClassCastException

      Returns the Java int value of the wrapped erlang value.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported or the value is too big

    - #### longValue

          public long longValue()
                         throws ClassCastException

      Returns the Java long value of the wrapped erlang value.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported or the value is too big

    - #### bigIntValue

          public BigInteger bigIntValue()
                                 throws ClassCastException

      Returns the Java BigInteger value of the wrapped erlang value.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported

    - #### doubleValue

          public double doubleValue()
                             throws ClassCastException

      Returns the Java double value of the wrapped erlang value.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported

    - #### stringValue

          public String stringValue()
                             throws ClassCastException

      Returns the Java `String` value of the wrapped erlang value.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported

    - #### binaryValue

          public byte[] binaryValue()
                             throws ClassCastException

      Returns the Java byte[] value of the wrapped erlang value.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported

    - #### jsonValue

          public Map<String,Object> jsonValue()
                                       throws ClassCastException

      Returns a JSON object (as `Map`<String, Object>) of the wrapped erlang value.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported

    - #### jsonValue

          public <T> T jsonValue(Class<T> c)
                      throws ClassCastException

      Returns a JSON object (as an instance of the given class) of the wrapped erlang value.
      Type Parameters:
        `T` - the type of the object to create
      Parameters:
        `c` - the class of the created object
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported

    - #### otpObjectToOtpList

          public static OtpErlangList otpObjectToOtpList(OtpErlangObject value)
                                                  throws ClassCastException

      Converts an `OtpErlangObject` to a `OtpErlangList` taking special care if the OTP library converted a list to an `OtpErlangString`.
      Parameters:
        `value` - the value to convert
      Returns:
        the value as a OtpErlangList
      Throws:
        `ClassCastException` - if the conversion fails

    - #### listValue

          public <T> List<T> listValue(ErlangValue.ListElementConverter<T> converter)
                            throws ClassCastException

      Returns a list of mixed Java values of the wrapped erlang value.
      Type Parameters:
        `T` - type of the elements in the list
      Parameters:
        `converter` - object that converts the list value to the desired type
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported

    - #### listCollectionValue

          public <T> Collection<T> listCollectionValue(Class<? extends Collection<T>> clazz,
                                              ErlangValue.ListElementConverter<T> converter)
                                            throws ClassCastException

      Returns a `Collection` of mixed Java values of the wrapped erlang value (internally represented as a list in Erlang).
      Type Parameters:
        `T` - type of the elements in the list
      Parameters:
        `clazz` - class of the result type
        `converter` - object that converts the list value to the desired type
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported
      Since:
        3.19

    - #### listValue

          public List<ErlangValue> listValue()
                                      throws ClassCastException

      Returns a list of mixed Java values (wrapped in `ErlangValue` objects) of the wrapped erlang value.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported

    - #### listCollectionValue

          public Collection<ErlangValue> listCollectionValue(Class<? extends Collection<ErlangValue>> clazz)
                                                      throws ClassCastException

      Returns a `Collection` of mixed Java values (wrapped in `ErlangValue` objects) of the wrapped erlang value (internally represented as a list in Erlang).
      Parameters:
        `clazz` - class of the result type
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported
      Since:
        3.19

    - #### longListValue

          public List<Long> longListValue()
                                   throws ClassCastException

      Returns a list of `Long` values of the wrapped erlang value. Provided for convenience.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported
      See Also:
        `listValue(ListElementConverter)`

    - #### doubleListValue

          public List<Double> doubleListValue()
                                       throws ClassCastException

      Returns a list of `Double` values of the wrapped erlang value. Provided for convenience.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported
      See Also:
        `listValue(ListElementConverter)`

    - #### stringListValue

          public List<String> stringListValue()
                                       throws ClassCastException

      Returns a list of `String` values of the wrapped erlang value. Provided for convenience.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported
      See Also:
        `listValue(ListElementConverter)`

    - #### binaryListValue

          public List<byte[]> binaryListValue()
                                       throws ClassCastException

      Returns a list of `byte[]` values of the wrapped erlang value. Provided for convenience.
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported
      See Also:
        `listValue(ListElementConverter)`

    - #### jsonListValue

          public <T> List<T> jsonListValue(Class<T> c)
                                throws ClassCastException

      Returns a list of JSON objects (as an instance of the given class) of the wrapped erlang value. Provided for convenience.
      Type Parameters:
        `T` - the type of the object to create as a list element
      Parameters:
        `c` - the class of the created object
      Returns:
        the converted value
      Throws:
        `ClassCastException` - if thrown if a conversion is not possible, i.e. the type is not supported
      Since:
        3.5
      See Also:
        `listValue(ListElementConverter)`

    - #### value

          public OtpErlangObject value()

      Gets the original erlang value.
      Returns:
        the value as reported by erlang

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### compareTo

          public int compareTo(ErlangValue o)

      Compares two erlang values by their string representation (expensive!).
      Specified by:
        `compareTo` in interface `Comparable<ErlangValue>`
      Parameters:
        `o` - another erlang value