org.qi4j.spi.value

## Class ValueDeserializerAdapter<InputType,InputNodeType>

- java.lang.Object
- - org.qi4j.spi.value.ValueDeserializerAdapter<InputType,InputNodeType>

- Type Parameters:
    `InputType` - Implementor pull-parser type
    `InputNodeType` - Implementor tree-parser node type
  All Implemented Interfaces:
    ValueDeserializer
  Direct Known Subclasses:
    JacksonValueDeserializer, OrgJsonValueDeserializer, StaxValueDeserializer

      public abstract class ValueDeserializerAdapter<InputType,InputNodeType>
      extends Object
      implements ValueDeserializer

  Adapter for pull-parsing and tree-parsing capable ValueDeserializers.

  Among Plain values (see `ValueDeserializer`) some are considered primitives to underlying serialization mechanisms and by so handed/come without conversion to/from implementations. Primitive values can be one of:

  - String,
  - Character or char,
  - Boolean or boolean,
  - Integer or int,
  - Long or long,
  - Short or short,
  - Byte or byte,
  - Float or float,
  - Double or double.

  Some other Plain values are expected in given formats:

  - BigInteger and BigDecimal depends on `ValueSerializer.Options`;
  - Date as String in ISO-8601, @millis@ or /Date(..) Microsoft format;
  - DateTime (JodaTime) as a ISO-8601 String with optional timezone offset;
  - LocalDateTime (JodaTime) as whatever `LocalDateTime.LocalDateTime(java.lang.Object)` accept as instant;
  - LocalDate (JodaTime) as whatever `LocalDate.LocalDate(java.lang.Object)` accept as instant;

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `ValueDeserializerAdapter.ComplexDeserializer<T,InputType,InputNodeType>`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ValueDeserializerAdapter(Application application, Module module, Function<Application,Module> valuesModuleFinder)`
    `` | `ValueDeserializerAdapter(Application application, Module module, ServiceReference<ValueDeserializer> serviceRef)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract InputType` | `adaptInput(InputStream input)` This method is always called first, this is a chance to wrap the input type.
    `protected abstract Object` | `asSimpleValue(InputNodeType inputNode)`
    `<T> Function2<ValueType,String,T>` | `deserialize()` Factory method for an untyped deserialize function.
    `<T> T` | `deserialize(Class<?> type, InputStream input)` Deserialize a value from a state.
    `<T> T` | `deserialize(Class<?> type, String input)` Deserialize a value from a state.
    `<T> Function<String,T>` | `deserialize(Class<T> type)` Factory method for a typed deserialize function.
    `<T> Function<String,T>` | `deserialize(ValueType valueType)` Factory method for a typed deserialize function.
    `<T> T` | `deserialize(ValueType valueType, InputStream input)` Deserialize a value from a state.
    `<T> T` | `deserialize(ValueType valueType, String input)` Deserialize a value from a state.
    `protected abstract <T> T` | `getObjectFieldValue(InputNodeType inputNode, String key, Function<InputNodeType,T> valueDeserializer)` Return null if the field do not exists.
    `protected abstract boolean` | `isObjectValue(InputNodeType inputNode)`
    `protected abstract boolean` | `objectHasField(InputNodeType inputNode, String key)`
    `protected void` | `onDeserializationEnd(ValueType valueType, InputType input)` Called by the adapter on deserialization end.
    `protected void` | `onDeserializationStart(ValueType valueType, InputType input)` Called by the adapter on deserialization start, after `adaptInput(java.io.InputStream)`.
    `protected abstract <T> void` | `putArrayNodeInCollection(InputNodeType inputNode, Function<InputNodeType,T> deserializer, Collection<T> collection)`
    `protected abstract <K,V> void` | `putArrayNodeInMap(InputNodeType inputNode, Function<InputNodeType,K> keyDeserializer, Function<InputNodeType,V> valueDeserializer, Map<K,V> map)`
    `protected abstract <V> void` | `putObjectNodeInMap(InputNodeType inputNode, Function<InputNodeType,V> valueDeserializer, Map<String,V> map)`
    `protected abstract <T> Collection<T>` | `readArrayInCollection(InputType input, Function<InputType,T> deserializer, Collection<T> collection)`
    `protected abstract <K,V> Map<K,V>` | `readMapInMap(InputType input, Function<InputType,K> keyDeserializer, Function<InputType,V> valueDeserializer, Map<K,V> map)` A Map<K,V> is serialized in an array of entries objects.
    `protected abstract InputNodeType` | `readObjectTree(InputType input)`
    `protected abstract Object` | `readPlainValue(InputType input)`
    `protected <T> void` | `registerComplexDeserializer(Class<T> type, ValueDeserializerAdapter.ComplexDeserializer<T,InputType,InputNodeType> deserializer)`
    `protected <T> void` | `registerDeserializer(Class<T> type, Function<Object,T> deserializer)` Register a Plain Value type deserialization Function.

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

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

- - ### Constructor Detail

    - #### ValueDeserializerAdapter

          public ValueDeserializerAdapter(@Structure
                                  Application application,
                                  @Structure
                                  Module module,
                                  @Service
                                  ServiceReference<ValueDeserializer> serviceRef)

    - #### ValueDeserializerAdapter

          protected ValueDeserializerAdapter(Application application,
                                  Module module,
                                  Function<Application,Module> valuesModuleFinder)

  - ### Method Detail

    - #### registerDeserializer

          protected final <T> void registerDeserializer(Class<T> type,
                                      Function<Object,T> deserializer)

      Register a Plain Value type deserialization Function.
      Type Parameters:
        `T` - Plain Value parametrized Type
      Parameters:
        `type` - Plain Value Type
        `deserializer` - Deserialization Function

    - #### registerComplexDeserializer

          protected final <T> void registerComplexDeserializer(Class<T> type,
                                             ValueDeserializerAdapter.ComplexDeserializer<T,InputType,InputNodeType> deserializer)

    - #### deserialize

          public <T> Function<String,T> deserialize(Class<T> type)

      Description copied from interface: `ValueDeserializer`
      Factory method for a typed deserialize function.

      The returned Function may throw `ValueSerializationException`.

      Specified by:
        `deserialize` in interface `ValueDeserializer`
      Type Parameters:
        `T` - the parametrized function return type
      Parameters:
        `type` - the value type
      Returns:
        a deserialization function

    - #### deserialize

          public final <T> Function<String,T> deserialize(ValueType valueType)

      Description copied from interface: `ValueDeserializer`
      Factory method for a typed deserialize function.

      The returned Function may throw `ValueSerializationException`.

      Specified by:
        `deserialize` in interface `ValueDeserializer`
      Type Parameters:
        `T` - the parametrized function return type
      Parameters:
        `valueType` - the value type
      Returns:
        a deserialization function

    - #### deserialize

          public final <T> Function2<ValueType,String,T> deserialize()

      Description copied from interface: `ValueDeserializer`
      Factory method for an untyped deserialize function.

      The returned Function may throw `ValueSerializationException`.

      Specified by:
        `deserialize` in interface `ValueDeserializer`
      Type Parameters:
        `T` - the parametrized function return type
      Returns:
        a deserialization function

    - #### deserialize

          public final <T> T deserialize(Class<?> type,
                          String input)
                              throws ValueSerializationException

      Description copied from interface: `ValueDeserializer`
      Deserialize a value from a state.
      Specified by:
        `deserialize` in interface `ValueDeserializer`
      Type Parameters:
        `T` - the parametrized returned type
      Parameters:
        `type` - the value type
        `input` - the state
      Returns:
        the value
      Throws:
        `ValueSerializationException` - if the deserialization failed

    - #### deserialize

          public final <T> T deserialize(ValueType valueType,
                          String input)
                              throws ValueSerializationException

      Description copied from interface: `ValueDeserializer`
      Deserialize a value from a state.
      Specified by:
        `deserialize` in interface `ValueDeserializer`
      Type Parameters:
        `T` - the parametrized returned type
      Parameters:
        `valueType` - the value type
        `input` - the state
      Returns:
        the value
      Throws:
        `ValueSerializationException` - if the deserialization failed

    - #### deserialize

          public final <T> T deserialize(Class<?> type,
                          InputStream input)
                              throws ValueSerializationException

      Description copied from interface: `ValueDeserializer`
      Deserialize a value from a state.
      Specified by:
        `deserialize` in interface `ValueDeserializer`
      Type Parameters:
        `T` - the parametrized returned type
      Parameters:
        `type` - the value type
        `input` - the state stream
      Returns:
        the value
      Throws:
        `ValueSerializationException` - if the deserialization failed

    - #### deserialize

          public final <T> T deserialize(ValueType valueType,
                          InputStream input)
                              throws ValueSerializationException

      Description copied from interface: `ValueDeserializer`
      Deserialize a value from a state.
      Specified by:
        `deserialize` in interface `ValueDeserializer`
      Type Parameters:
        `T` - the parametrized returned type
      Parameters:
        `valueType` - the value type
        `input` - the state stream
      Returns:
        the value
      Throws:
        `ValueSerializationException` - if the deserialization failed

    - #### onDeserializationStart

          protected void onDeserializationStart(ValueType valueType,
                                    InputType input)
                                         throws Exception

      Called by the adapter on deserialization start, after `adaptInput(java.io.InputStream)`.
      Parameters:
        `valueType` - ValueType
        `input` - Input
      Throws:
        `Exception` - that will be wrapped in a `ValueSerializationException`

    - #### onDeserializationEnd

          protected void onDeserializationEnd(ValueType valueType,
                                  InputType input)
                                       throws Exception

      Called by the adapter on deserialization end.
      Parameters:
        `valueType` - ValueType
        `input` - Input
      Throws:
        `Exception` - that will be wrapped in a `ValueSerializationException`

    - #### adaptInput

          protected abstract InputType adaptInput(InputStream input)
                                           throws Exception

      This method is always called first, this is a chance to wrap the input type.
      Parameters:
        `input` - InputStream to adapt
      Returns:
        Adapted input
      Throws:
        `Exception` - that will be wrapped in a `ValueSerializationException`

    - #### readPlainValue

          protected abstract Object readPlainValue(InputType input)
                                            throws Exception

      Parameters:
        `input` - Input
      Returns:
        a Plain Value read from the input
      Throws:
        `Exception` - that will be wrapped in a `ValueSerializationException`

    - #### readArrayInCollection

          protected abstract <T> Collection<T> readArrayInCollection(InputType input,
                                                Function<InputType,T> deserializer,
                                                Collection<T> collection)
                                                          throws Exception

      Type Parameters:
        `T` - Parameterized collection type
      Parameters:
        `input` - Input
        `deserializer` - Deserialization function
        `collection` - Collection
      Returns:
        The filled collection or null if no array
      Throws:
        `Exception` - that will be wrapped in a `ValueSerializationException`

    - #### readMapInMap

          protected abstract <K,V> Map<K,V> readMapInMap(InputType input,
                                    Function<InputType,K> keyDeserializer,
                                    Function<InputType,V> valueDeserializer,
                                    Map<K,V> map)
                                            throws Exception

      A Map<K,V> is serialized in an array of entries objects.

      Here is an example in JSON:

           [
               { "key": "foo",       "value": "bar"   },
               { "key": "cathedral", "value": "bazar" }
           ]

      And an empty Map:

          []

      This allow to use any type as keys and values while keeping the Map order at the cost of having non-predictible order of key/value inside an entry object.

      Type Parameters:
        `K` - Parameterized map key type
        `V` - Parameterized map value type
      Parameters:
        `input` - Input
        `keyDeserializer` - Map key deserialization function
        `valueDeserializer` - Map value deserialization function
        `map` - Map
      Returns:
        The filled map or null if no array
      Throws:
        `Exception` - that will be wrapped in a `ValueSerializationException`

    - #### readObjectTree

          protected abstract InputNodeType readObjectTree(InputType input)
                                                   throws Exception

      Parameters:
        `input` - Input
      Returns:
        an InputNodeType or null if the value was null
      Throws:
        `Exception` - that will be wrapped in a `ValueSerializationException`

    - #### asSimpleValue

          protected abstract Object asSimpleValue(InputNodeType inputNode)
                                           throws Exception

      Throws:
        `Exception`

    - #### isObjectValue

          protected abstract boolean isObjectValue(InputNodeType inputNode)
                                            throws Exception

      Throws:
        `Exception`

    - #### objectHasField

          protected abstract boolean objectHasField(InputNodeType inputNode,
                               String key)
                                             throws Exception

      Throws:
        `Exception`

    - #### getObjectFieldValue

          protected abstract <T> T getObjectFieldValue(InputNodeType inputNode,
                                  String key,
                                  Function<InputNodeType,T> valueDeserializer)
                                            throws Exception

      Return null if the field do not exists.
      Type Parameters:
        `T` - Parameterized object field value type
      Parameters:
        `inputNode` - Input Node
        `key` - Object key
        `valueDeserializer` - Deserialization function
      Returns:
        The value of the field.
      Throws:
        `Exception` - that will be wrapped in a `ValueSerializationException`

    - #### putArrayNodeInCollection

          protected abstract <T> void putArrayNodeInCollection(InputNodeType inputNode,
                                          Function<InputNodeType,T> deserializer,
                                          Collection<T> collection)
                                                    throws Exception

      Throws:
        `Exception`

    - #### putArrayNodeInMap

          protected abstract <K,V> void putArrayNodeInMap(InputNodeType inputNode,
                                     Function<InputNodeType,K> keyDeserializer,
                                     Function<InputNodeType,V> valueDeserializer,
                                     Map<K,V> map)
                                             throws Exception

      Throws:
        `Exception`

    - #### putObjectNodeInMap

          protected abstract <V> void putObjectNodeInMap(InputNodeType inputNode,
                                    Function<InputNodeType,V> valueDeserializer,
                                    Map<String,V> map)
                                              throws Exception

      Throws:
        `Exception`