Package io.axoniq.dataprotection.api

## Class FieldEncryptingSerializer

- java.lang.Object
- - io.axoniq.dataprotection.api.FieldEncryptingSerializer

- All Implemented Interfaces:
    `Serializer`

      public final class FieldEncryptingSerializer
      extends Object
      implements Serializer

  Implementation of `Serializer` which wraps a delegate `Serializer`, but performs encryption before serializing and decryption after deserializing, using a `FieldEncrypter`. The delegate `Serializer` may support multiple expected representations, but must support `byte[]`. This serializer will then support any representation supported by the delegate serializer.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FieldEncryptingSerializer​(FieldEncrypter fieldEncrypter, Serializer delegateSerializer)` | Constructs a `FieldEncryptingSerializer` for a given `FieldEncrypter` and `Serializer`.
    `FieldEncryptingSerializer​(CryptoEngine cryptoEngine, ReplacementValueProvider replacementValueProvider, Serializer delegateSerializer)` | Deprecated. in favor of using the `FieldEncryptingSerializer(CryptoEngine, Serializer, ReplacementValueProvider, Serializer)` to construct an instance using a configured `Serializer` instances.
    `FieldEncryptingSerializer​(CryptoEngine cryptoEngine, Serializer delegateSerializer)` | Deprecated. in favor of using the `FieldEncryptingSerializer(CryptoEngine, Serializer, Serializer)` to construct an instance using a configured `Serializer` instances.
    `FieldEncryptingSerializer​(CryptoEngine cryptoEngine, Serializer personalDataSerializer, ReplacementValueProvider replacementValueProvider, Serializer delegateSerializer)` | Constructs a `FieldEncryptingSerializer` using a given `CryptoEngine`, `ReplacementValueProvider` and `Serializer`.
    `FieldEncryptingSerializer​(CryptoEngine cryptoEngine, Serializer personalDataSerializer, Serializer delegateSerializer)` | Constructs a `FieldEncryptingSerializer` using a given `CryptoEngine` and `Serializer`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `<T> boolean` | `canSerializeTo​(Class<T> expectedRepresentation)` | Indicates whether this Serializer is capable of serializing to the given `expectedRepresentation`.
    `Class` | `classForType​(SerializedType type)` | Returns the class for the given type identifier.
    `protected Object` | `clone​(Object object)` | Clones the object.
    `<S,​T> T` | `deserialize​(SerializedObject<S> serializedObject)` | Deserializes the first object read from the given `bytes`.
    `ConverterFactory` | `getConverterFactory()` | Returns the `Converter` used by this Serializer to convert between serialized representations.
    `<T> SerializedObject<T>` | `serialize​(Object object, Class<T> expectedRepresentation)` | Serialize the given `object` into a Serialized Object containing the given `expectedRepresentation`.
    `SerializedType` | `typeForClass​(Class type)` | Returns the type identifier for the given class.

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

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

- - ### Constructor Detail

    - #### FieldEncryptingSerializer

          public FieldEncryptingSerializer​(FieldEncrypter fieldEncrypter,
                                           Serializer delegateSerializer)

      Constructs a `FieldEncryptingSerializer` for a given `FieldEncrypter` and `Serializer`. This version of the constructor gives maximum control over the `FieldEncrypter`.
      Parameters:
        `fieldEncrypter` - the `FieldEncrypter` to be used
        `delegateSerializer` - the `Serializer` to wrap

    - #### FieldEncryptingSerializer

          @Deprecated
          public FieldEncryptingSerializer​(CryptoEngine cryptoEngine,
                                           Serializer delegateSerializer)

      Deprecated.
      in favor of using the `FieldEncryptingSerializer(CryptoEngine, Serializer, Serializer)` to construct an instance using a configured `Serializer` instances. Using this shorthand still works, but will use an `XStream` instance that allows everything. Although this works, XStream expects the types or wildcards for the types to be defined to ensure the application stays secure. As such, it is highly recommended to follow their recommended approach.
      Constructs a `FieldEncryptingSerializer` using a given `CryptoEngine` and `Serializer`. A `FieldEncrypter` will be constructed using the `CryptoEngine` and using the delegate serializer also as the serializer for the `FieldEncrypter`. The `FieldEncrypter` will use the default `ReplacementValueProvider`.
      Parameters:
        `cryptoEngine` - the `CryptoEngine` to be used
        `delegateSerializer` - the `Serializer` to wrap

    - #### FieldEncryptingSerializer

          @Deprecated
          public FieldEncryptingSerializer​(CryptoEngine cryptoEngine,
                                           ReplacementValueProvider replacementValueProvider,
                                           Serializer delegateSerializer)

      Deprecated.
      in favor of using the `FieldEncryptingSerializer(CryptoEngine, Serializer, ReplacementValueProvider, Serializer)` to construct an instance using a configured `Serializer` instances. Using this shorthand still works, but will use an `XStream` instance that allows everything. Although this works, XStream expects the types or wildcards for the types to be defined to ensure the application stays secure. As such, it is highly recommended to follow their recommended approach.
      Constructs a `FieldEncryptingSerializer` using a given `CryptoEngine`, `ReplacementValueProvider` and `Serializer`. A `FieldEncrypter` will be constructed using the `CryptoEngine` and `ReplacementValueProvider`, using the delegate serializer also as the serializer for the `FieldEncrypter`.
      Parameters:
        `cryptoEngine` - the `CryptoEngine` to be used
        `replacementValueProvider` - the `ReplacementValueProvider` to use
        `delegateSerializer` - the `Serializer` to wrap

    - #### FieldEncryptingSerializer

          public FieldEncryptingSerializer​(CryptoEngine cryptoEngine,
                                           Serializer personalDataSerializer,
                                           Serializer delegateSerializer)

      Constructs a `FieldEncryptingSerializer` using a given `CryptoEngine` and `Serializer`. A `FieldEncrypter` will be constructed using the `CryptoEngine` and using the delegate serializer also as the serializer for the `FieldEncrypter`. The `FieldEncrypter` will use the default `ReplacementValueProvider`.
      Parameters:
        `cryptoEngine` - the `CryptoEngine` to be used
        `personalDataSerializer` - the `Serializer` to be used internally to serialize personal data to a string for encryption
        `delegateSerializer` - the `Serializer` to wrap

    - #### FieldEncryptingSerializer

          public FieldEncryptingSerializer​(CryptoEngine cryptoEngine,
                                           Serializer personalDataSerializer,
                                           ReplacementValueProvider replacementValueProvider,
                                           Serializer delegateSerializer)

      Constructs a `FieldEncryptingSerializer` using a given `CryptoEngine`, `ReplacementValueProvider` and `Serializer`. A `FieldEncrypter` will be constructed using the `CryptoEngine` and `ReplacementValueProvider`, using the delegate serializer also as the serializer for the `FieldEncrypter`.
      Parameters:
        `cryptoEngine` - the `CryptoEngine` to be used
        `personalDataSerializer` - the `Serializer` to be used internally to serialize personal data to a string for encryption
        `replacementValueProvider` - the `ReplacementValueProvider` to use
        `delegateSerializer` - the `Serializer` to wrap

  - ### Method Detail

    - #### clone

          protected Object clone​(Object object)

      Clones the object. Will be invoked prior to encryption if `skipCloning` is `true`. The default implementation performs cloning by serializing and deserializing, using `byte[]` as the expected intermediate representation. Application may create their own version of this class with a different cloning mechanism.
      Parameters:
        `object` - the object to clone
      Returns:
        the cloned object

    - #### serialize

          public <T> SerializedObject<T> serialize​(Object object,
                                                   Class<T> expectedRepresentation)

      Serialize the given `object` into a Serialized Object containing the given `expectedRepresentation`. Performs encryption prior to serialization, and optional cloning before encryption. Use `canSerializeTo(Class)` to detect whether the `expectedRepresentation` is supported by this serializer. `byte[]` is always supported.
      Specified by:
        `serialize` in interface `Serializer`
      Type Parameters:
        `T` - The expected data type representing the serialized object
      Parameters:
        `object` - The object to serialize
        `expectedRepresentation` - The expected data type representing the serialized object
      Returns:
        the instance representing the serialized object.

    - #### canSerializeTo

          public <T> boolean canSerializeTo​(Class<T> expectedRepresentation)

      Indicates whether this Serializer is capable of serializing to the given `expectedRepresentation`. Will return whatever value is returned by the delegate. Will always return `true` for `byte[].class`. When `true`, this does *not* guarantee that the serialization and (optional) conversion will also succeed when executed. For example, when a serializer produces a `byte[]` containing JSON, trying to convert to a Dom4J Document will fail, even though this serializer has a converter to convert `byte[]` to Dom4J instances.
      Specified by:
        `canSerializeTo` in interface `Serializer`
      Type Parameters:
        `T` - The type of data a Serialized Object should contain
      Parameters:
        `expectedRepresentation` - The type of data a Serialized Object should contain
      Returns:
        `true` if the `expectedRepresentation` is supported, otherwise `false`.

    - #### deserialize

          public <S,​T> T deserialize​(SerializedObject<S> serializedObject)

      Deserializes the first object read from the given `bytes`. The `bytes` are not consumed from the array or modified in any way. The resulting object instance is cast to the expected type. After that, decryption takes place.
      Specified by:
        `deserialize` in interface `Serializer`
      Type Parameters:
        `S` - The data type of the serialized object
        `T` - The expected deserialized type
      Parameters:
        `serializedObject` - the instance describing the type of object and the bytes providing the serialized data
      Returns:
        the serialized object, cast to the expected type
      Throws:
        `ClassCastException` - if the first object in the stream is not an instance of <T>.

    - #### classForType

          public Class classForType​(SerializedType type)

      Returns the class for the given type identifier. The result of this method must guarantee that the deserialized SerializedObject with the given `type` is an instance of the returned Class. This method will be executed by the delegate. If a class cannot be resolved (i.e. because the class is not available on this JVM's classpath) this method throws UnknownSerializedTypeException (not on Axon 4).
      Specified by:
        `classForType` in interface `Serializer`
      Parameters:
        `type` - The type identifier of the object
      Returns:
        the Class representing the type of the serialized Object

    - #### typeForClass

          public SerializedType typeForClass​(Class type)

      Returns the type identifier for the given class. This is the type identifier of the Serialized object as returned by `serialize(Object, Class)`. This method will be executed by the delegate.
      Specified by:
        `typeForClass` in interface `Serializer`
      Parameters:
        `type` - Class representing the type of the serializable Object.
      Returns:
        The type identifier of the object

    - #### getConverterFactory

          public ConverterFactory getConverterFactory()

      Returns the `Converter` used by this Serializer to convert between serialized representations. Generally, this Converter depends on the type of data the serializer serializes to. This method will be executed by the delegate.
      Specified by:
        `getConverterFactory` in interface `Serializer`
      Returns:
        the converter used by this Serializer