Package io.permazen

Enum Class UpgradeConversionPolicy

java.lang.Object
java.lang.Enum<UpgradeConversionPolicy>
io.permazen.UpgradeConversionPolicy
All Implemented Interfaces:
Serializable, Comparable<UpgradeConversionPolicy>, Constable
public enum UpgradeConversionPolicy extends Enum<UpgradeConversionPolicy>
Policies to apply when a simple or counter field's type changes during a schema change.

Type Changes

Permazen fields are identified by name. Therefore, it's possible for the "same" field to have two different types in two different schemas. When migrating an object's schema, Permazen can automatically perform certain conversions of simple field values from the old type to the new type. For example, an int field value 1234 can be automatically converted into String field value "1234".

See Encoding.convert(io.permazen.encoding.Encoding<S>, S) for details about supported conversions between simple encodings. In addition, Counter fields can be converted to/from any numeric Java primitive (or primitive wrapper) type.

This class is used to specify whether such automatic conversion should occur when a simple field's type changes, and if so, whether the conversion must always succeed.

References and Enums

Permazen considers Enum types with different identifier lists as different types. However, automatic conversion of Enum values in simple fields will work if the existing value's name (enum identifier) is valid for the new Enum type.

Automatic conversion of reference fields works as long as the referenced object's type is assignable to the field's new Java type; otherwise, the field is unreferenced, i.e., set to null (if a simple field) or removed (if an element in a complex field).

Conversion Policies

With RESET, no automatic conversion is attempted: the field is always reset to the default value of the new type. With ATTEMPT and REQUIRE, automatic conversion of field values is attempted.

For some types and/or field values, conversion is not possible. In this case, REQUIRE generates a UpgradeConversionException, while ATTEMPT just reverts to the behavior of RESET.

Note that arbitrary conversion logic is always possible using @OnSchemaChange.

See Also:

  • Enum Constant Details

    • RESET

      public static final UpgradeConversionPolicy RESET
      Do not attempt to automatically convert values to the new type.

      Instead, during a schema change, the field will be reset to the default value of the field's new type.

    • ATTEMPT

      public static final UpgradeConversionPolicy ATTEMPT
      Attempt automatic conversion of field values to the new type, and if automatic conversion fails, set the value to the new type's default value as would RESET.

    • REQUIRE

      public static final UpgradeConversionPolicy REQUIRE
      Attempt automatic conversion of field values to the new type, and if automatic conversion fails, throw a UpgradeConversionException.

  • Method Details

    • values

      public static UpgradeConversionPolicy[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static UpgradeConversionPolicy valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • isConvertsValues

      public boolean isConvertsValues()
      Determine whether this policy should attempt to convert field values from the old type to the new type.

      If this is false, the field's value will be set to the new type's default value. If this is true, the field's old value will be converted to the field's new type if possible; if the conversion fails, the behavior depends on isRequireConversion().

      Returns:
      true if under this policy conversion should be attempted

    • isRequireConversion

      public boolean isRequireConversion()
      Determine whether failed attempts to convert a field's value from the old type to the new type should be fatal.

      If this is true, a failed conversion attempt results in a UpgradeConversionException being thrown. If this is false, a failed conversion attempt results in the field being set to the new type's default value.

      Returns:
      true if under this policy conversion is mandatory