Package io.axoniq.dataprotection.api

## Class FieldEncrypter

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

-     public final class FieldEncrypter
      extends Object

  This class can take an object and encrypt and decrypt its fields, including the fields of any objects deeper in the object tree, according to the configuration of the various Axon Data Protection Module annotations. To accomplish this, it needs the capabilities of a `CryptoEngine`.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FieldEncrypter​(CryptoEngine cryptoEngine)` | Deprecated. in favor of using the `FieldEncrypter(CryptoEngine, Serializer)` to construct an instance using a configured `Serializer` instance.
    `FieldEncrypter​(CryptoEngine cryptoEngine, ReplacementValueProvider replacementValueProvider)` | Deprecated. in favor of using the `FieldEncrypter(CryptoEngine, Serializer, ReplacementValueProvider)` to construct an instance using a configured `Serializer` instance.
    `FieldEncrypter​(CryptoEngine cryptoEngine, Serializer serializer)` | Instantiates a FieldEncrypter with the default rules for value replacement but a custom `Serializer`.
    `FieldEncrypter​(CryptoEngine cryptoEngine, Serializer serializer, ReplacementValueProvider replacementValueProvider)` | Instantiates a FieldEncrypter with a custom `ReplacementValueProvider` and a custom `Serializer`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `decrypt​(Object obj)` | Decrypts the fields of the object.
    `void` | `decrypt​(Object obj, String keyId)` | Decrypts the fields of the object.
    `void` | `decrypt​(Object obj, String keyId, Set<String> groups)` | Decrypts the fields of the object, restricting to certain groups.
    `void` | `decrypt​(Object obj, Map<String,​String> keyIds)` | Decrypts the fields of the object.
    `void` | `decrypt​(Object obj, Map<String,​String> keyIds, Set<String> groups)` | Decrypts the fields of the object, restricting to certain groups.
    `void` | `decrypt​(Object obj, Set<String> groups)` | Decrypts the fields of the object, restricting to certain groups.
    `void` | `encrypt​(Object obj)` | Encrypts the fields of the object.
    `void` | `encrypt​(Object obj, String keyId)` | Encrypts the fields of the object.
    `void` | `encrypt​(Object obj, String keyId, Set<String> groups)` | Encrypts the fields of the object, restricting to certain groups.
    `void` | `encrypt​(Object obj, Map<String,​String> keyIds)` | Encrypts the fields of the object.
    `void` | `encrypt​(Object obj, Map<String,​String> keyIds, Set<String> groups)` | Encrypts the fields of the object, restricting to certain groups.
    `void` | `encrypt​(Object obj, Set<String> groups)` | Encrypts the fields of the object, restricting to certain groups.
    `Set<String>` | `getGroups()` | Read accessor for the groups property.
    `boolean` | `isModifyImmutableCollections()` | Read accessor for the modifyImmutableCollections property.
    `void` | `replace​(Object obj)` | Directly replaces the values of the fields of the object by the value they would get if they would get crypto-deleted, without doing actual encryption or decryption.
    `void` | `replace​(Object obj, Set<String> groups)` | Directly replaces the values of the fields of the object by the value they would get if they would get crypto-deleted, without doing actual encryption or decryption.
    `void` | `setGroups​(Set<String> groups)` | Write accessor for the groups property.
    `void` | `setModifyImmutableCollections​(boolean value)` | Write accessor for the modifyImmutableCollections property.
    `boolean` | `willProcess​(Object obj)` | Examines whether object may change under encryption/decryption.

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

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

- - ### Constructor Detail

    - #### FieldEncrypter

          @Deprecated
          public FieldEncrypter​(CryptoEngine cryptoEngine)

      Deprecated.
      in favor of using the `FieldEncrypter(CryptoEngine, Serializer)` to construct an instance using a configured `Serializer` instance. 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.
      Instantiates a FieldEncrypter with the default rules for value replacement and an `XStreamSerializer`.
      Parameters:
        `cryptoEngine` - the `CryptoEngine` to be used

    - #### FieldEncrypter

          @Deprecated
          public FieldEncrypter​(CryptoEngine cryptoEngine,
                                ReplacementValueProvider replacementValueProvider)

      Deprecated.
      in favor of using the `FieldEncrypter(CryptoEngine, Serializer, ReplacementValueProvider)` to construct an instance using a configured `Serializer` instance. 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.
      Instantiates a FieldEncrypter with a custom `ReplacementValueProvider` and a default `XStreamSerializer`.
      Parameters:
        `cryptoEngine` - the `CryptoEngine` to be used
        `replacementValueProvider` - a (custom) replacement value provider

    - #### FieldEncrypter

          public FieldEncrypter​(CryptoEngine cryptoEngine,
                                Serializer serializer)

      Instantiates a FieldEncrypter with the default rules for value replacement but a custom `Serializer`.
      Parameters:
        `cryptoEngine` - the `CryptoEngine` to be used
        `serializer` - the `Serializer` to be used

    - #### FieldEncrypter

          public FieldEncrypter​(CryptoEngine cryptoEngine,
                                Serializer serializer,
                                ReplacementValueProvider replacementValueProvider)

      Instantiates a FieldEncrypter with a custom `ReplacementValueProvider` and a custom `Serializer`.
      Parameters:
        `cryptoEngine` - the `CryptoEngine` to be used
        `serializer` - the `Serializer` to be used
        `replacementValueProvider` - a (custom) replacement value provider

  - ### Method Detail

    - #### encrypt

          public void encrypt​(Object obj)

      Encrypts the fields of the object.
      Parameters:
        `obj` - the object to encrypt

    - #### encrypt

          public void encrypt​(Object obj,
                              String keyId)

      Encrypts the fields of the object.
      Parameters:
        `obj` - the object to encrypt
        `keyId` - the id of key to be preloaded in the encryption context with default group

    - #### encrypt

          public void encrypt​(Object obj,
                              Map<String,​String> keyIds)

      Encrypts the fields of the object.
      Parameters:
        `obj` - the object to encrypt
        `keyIds` - a map of group/keyId pairs defining keys to be preloaded into the encryption context

    - #### encrypt

          public void encrypt​(Object obj,
                              Set<String> groups)

      Encrypts the fields of the object, restricting to certain groups.
      Parameters:
        `obj` - the object to encrypt
        `groups` - the field groups to process. This override the 'groups' property of the FieldEncrypter object.

    - #### encrypt

          public void encrypt​(Object obj,
                              String keyId,
                              Set<String> groups)

      Encrypts the fields of the object, restricting to certain groups.
      Parameters:
        `obj` - the object to encrypt
        `keyId` - the id of key to be preloaded in the encryption context with default group
        `groups` - the field groups to process. This override the 'groups' property of the FieldEncrypter object.

    - #### encrypt

          public void encrypt​(Object obj,
                              Map<String,​String> keyIds,
                              Set<String> groups)

      Encrypts the fields of the object, restricting to certain groups.
      Parameters:
        `obj` - the object to encrypt
        `keyIds` - a map of group/keyId pairs defining keys to be preloaded into the encryption context
        `groups` - the field groups to process. This override the 'groups' property of the FieldEncrypter object.

    - #### decrypt

          public void decrypt​(Object obj)

      Decrypts the fields of the object.
      Parameters:
        `obj` - the object to decrypt

    - #### decrypt

          public void decrypt​(Object obj,
                              String keyId)

      Decrypts the fields of the object.
      Parameters:
        `obj` - the object to decrypt
        `keyId` - the id of key to be preloaded in the decryption context with default group

    - #### decrypt

          public void decrypt​(Object obj,
                              Map<String,​String> keyIds)

      Decrypts the fields of the object.
      Parameters:
        `obj` - the object to decrypt
        `keyIds` - a map of group/keyId pairs defining keys to be preloaded into the decryption context

    - #### decrypt

          public void decrypt​(Object obj,
                              Set<String> groups)

      Decrypts the fields of the object, restricting to certain groups.
      Parameters:
        `obj` - the object to decrypt
        `groups` - the field groups to process. This override the 'groups' property of the FieldEncrypter object.

    - #### decrypt

          public void decrypt​(Object obj,
                              String keyId,
                              Set<String> groups)

      Decrypts the fields of the object, restricting to certain groups.
      Parameters:
        `obj` - the object to decrypt
        `keyId` - the id of key to be preloaded in the decryption context with default group
        `groups` - the field groups to process. This override the 'groups' property of the FieldEncrypter object.

    - #### decrypt

          public void decrypt​(Object obj,
                              Map<String,​String> keyIds,
                              Set<String> groups)

      Decrypts the fields of the object, restricting to certain groups.
      Parameters:
        `obj` - the object to decrypt
        `keyIds` - a map of group/keyId pairs defining keys to be preloaded into the decryption context
        `groups` - the field groups to process. This override the 'groups' property of the FieldEncrypter object.

    - #### replace

          public void replace​(Object obj)

      Directly replaces the values of the fields of the object by the value they would get if they would get crypto-deleted, without doing actual encryption or decryption.
      Parameters:
        `obj` - the object to replace

    - #### replace

          public void replace​(Object obj,
                              Set<String> groups)

      Directly replaces the values of the fields of the object by the value they would get if they would get crypto-deleted, without doing actual encryption or decryption.
      Parameters:
        `obj` - the object to replace
        `groups` - the field groups to process. This override the 'groups' property of the FieldEncrypter object.

    - #### willProcess

          public boolean willProcess​(Object obj)

      Examines whether object may change under encryption/decryption. This is the case if the argument is non-`null` and the object's class (or superclass) has one or more Axon Data Protection Module annotations.
      Parameters:
        `obj` - the object to examine
      Returns:
        `true` if the object may get encrypted

    - #### isModifyImmutableCollections

          public boolean isModifyImmutableCollections()

      Read accessor for the modifyImmutableCollections property. This property determines whether the module will attempt to modify immutable collections such as those returned by `Collections.unmodifiableList(List)`. `true` by default.
      Returns:
        the current modifyImmutableCollections setting

    - #### setModifyImmutableCollections

          public void setModifyImmutableCollections​(boolean value)

      Write accessor for the modifyImmutableCollections property. This property determines whether the module will attempt to modify immutable collections such as those returned by `Collections.unmodifiableList(List)`. `true` by default.
      Parameters:
        `value` - the new value of the property

    - #### getGroups

          public Set<String> getGroups()

      Read accessor for the groups property. This property determines which field groups will be processed by default by the encrypt/decrypt methods. Initially, this value is `null` which means that all groups will be processed.
      Returns:
        the current value of the groups property. Reference is copied directly, no defensive cloning or immutable wrapping.

    - #### setGroups

          public void setGroups​(Set<String> groups)

      Write accessor for the groups property. This property determines which field groups will be processed by default by the encrypt/decrypt methods. Initially, this value is `null` which means that all groups will be processed.
      Parameters:
        `groups` - the new value of the groups property. Reference is copied directly, no defensive cloning.