Package org.instancio.settings

Class Keys

java.lang.Object
org.instancio.settings.Keys
public final class Keys extends Object
Defines all keys supported by Instancio.
Since:
1.1.10
See Also:

  • Field Details

    • ASSIGNMENT_TYPE

      @ExperimentalApi public static final SettingKey<AssignmentType> ASSIGNMENT_TYPE
      Specifies whether to assign values using fields or methods; default is AssignmentType.FIELD; property name assignment.type.

      This setting does not apply to fields that are final and record classes, since those cannot have setters.

      Since:
      2.1.0
      See Also:

    • AFTER_GENERATE_HINT

      public static final SettingKey<AfterGenerate> AFTER_GENERATE_HINT
      Specifies the default value of the AfterGenerate hint supplied from custom generators to the engine; default is AfterGenerate.POPULATE_NULLS_AND_DEFAULT_PRIMITIVES; property name hint.after.generate.
      Since:
      2.0.0
      See Also:

    • ARRAY_ELEMENTS_NULLABLE

      public static final SettingKey<Boolean> ARRAY_ELEMENTS_NULLABLE
      Specifies whether a null can be generated for array elements; default is false; property name array.elements.nullable.

    • ARRAY_MIN_LENGTH

      public static final SettingKey<Integer> ARRAY_MIN_LENGTH
      Specifies minimum length for arrays; default is 2; property name array.min.length.

    • ARRAY_MAX_LENGTH

      public static final SettingKey<Integer> ARRAY_MAX_LENGTH
      Specifies maximum length for arrays; default is 6; property name array.max.length.

    • ARRAY_NULLABLE

      public static final SettingKey<Boolean> ARRAY_NULLABLE
      Specifies whether a null can be generated for arrays; default is false; property name array.nullable.

    • BEAN_VALIDATION_ENABLED

      @ExperimentalApi public static final SettingKey<Boolean> BEAN_VALIDATION_ENABLED
      Specifies whether values should be generated based on Jakarta Bean Validation 3.0 annotations, if present; default is false; property name bean.validation.api.enabled.
      Since:
      2.7.0
      See Also:

    • BEAN_VALIDATION_TARGET

      @ExperimentalApi public static final SettingKey<BeanValidationTarget> BEAN_VALIDATION_TARGET
      Specifies whether Bean Validation annotations are declared on fields or getters; default is BeanValidationTarget.FIELD; property name bean.validation.target.
      Since:
      3.4.0
      See Also:

    • BIG_DECIMAL_SCALE

      @ExperimentalApi public static final SettingKey<Integer> BIG_DECIMAL_SCALE
      Specifies the scale for generating BigDecimal; default is 2; property name bigdecimal.scale.
      Since:
      3.3.0

    • BOOLEAN_NULLABLE

      public static final SettingKey<Boolean> BOOLEAN_NULLABLE
      Specifies whether a null can be generated for Boolean type; default is false; property name boolean.nullable.

    • BYTE_MIN

      public static final SettingKey<Byte> BYTE_MIN
      Specifies minimum value for bytes; default is 1; property name byte.min.

    • BYTE_MAX

      public static final SettingKey<Byte> BYTE_MAX
      Specifies maximum value for bytes; default is 127; property name byte.max.

    • BYTE_NULLABLE

      public static final SettingKey<Boolean> BYTE_NULLABLE
      Specifies whether a null can be generated for Byte type; default is false; property name byte.nullable.

    • CHARACTER_NULLABLE

      public static final SettingKey<Boolean> CHARACTER_NULLABLE
      Specifies whether a null can be generated for Character type; default is false; property name character.nullable.

    • COLLECTION_ELEMENTS_NULLABLE

      public static final SettingKey<Boolean> COLLECTION_ELEMENTS_NULLABLE
      Specifies whether a null can be generated for collection elements; default is false; property name collection.elements.nullable.

    • COLLECTION_MIN_SIZE

      public static final SettingKey<Integer> COLLECTION_MIN_SIZE
      Specifies minimum size for collections; default is 2; property name collection.min.size.

    • COLLECTION_MAX_SIZE

      public static final SettingKey<Integer> COLLECTION_MAX_SIZE
      Specifies maximum size for collections; default is 6; property name collection.max.size.

    • COLLECTION_NULLABLE

      public static final SettingKey<Boolean> COLLECTION_NULLABLE
      Specifies whether a null can be generated for collections; default is false; property name collection.nullable.

    • DOUBLE_MIN

      public static final SettingKey<Double> DOUBLE_MIN
      Specifies minimum value for doubles; default is 1; property name double.min.

    • DOUBLE_MAX

      public static final SettingKey<Double> DOUBLE_MAX
      Specifies maximum value for doubles; default is 10000; property name double.max.

    • DOUBLE_NULLABLE

      public static final SettingKey<Boolean> DOUBLE_NULLABLE
      Specifies whether a null can be generated for Double type; default is false; property name double.nullable.

    • FAIL_ON_ERROR

      @ExperimentalApi public static final SettingKey<Boolean> FAIL_ON_ERROR
      Specifies whether internal exceptions should be propagated up; default is false; property name fail.on.error.
      Since:
      3.0.1

    • FLOAT_MIN

      public static final SettingKey<Float> FLOAT_MIN
      Specifies minimum value for floats; default is 1; property name float.min.

    • FLOAT_MAX

      public static final SettingKey<Float> FLOAT_MAX
      Specifies maximum value for floats; default is 10000; property name float.max.

    • FLOAT_NULLABLE

      public static final SettingKey<Boolean> FLOAT_NULLABLE
      Specifies whether a null can be generated for Float type; default is false; property name float.nullable.

    • INTEGER_MIN

      public static final SettingKey<Integer> INTEGER_MIN
      Specifies minimum value for integers; default is 1; property name integer.min.

    • INTEGER_MAX

      public static final SettingKey<Integer> INTEGER_MAX
      Specifies maximum value for integers; default is 10000; property name integer.max.

    • INTEGER_NULLABLE

      public static final SettingKey<Boolean> INTEGER_NULLABLE
      Specifies whether a null can be generated for Integer type; default is false; property name integer.nullable.

    • JPA_ENABLED

      @ExperimentalApi public static final SettingKey<Boolean> JPA_ENABLED
      Specifies whether values should be generated based on JPA annotations, such as @Column.length; default is false; property name jpa.enabled.
      Since:
      3.3.0

    • LONG_MIN

      public static final SettingKey<Long> LONG_MIN
      Specifies minimum value for longs; default is 1; property name long.min.

    • LONG_MAX

      public static final SettingKey<Long> LONG_MAX
      Specifies maximum value for longs; default is 10000; property name long.max.

    • LONG_NULLABLE

      public static final SettingKey<Boolean> LONG_NULLABLE
      Specifies whether a null can be generated for Long type; default is false; property name long.nullable.

    • MAP_KEYS_NULLABLE

      public static final SettingKey<Boolean> MAP_KEYS_NULLABLE
      Specifies whether a null can be generated for map keys; default is false; property name map.keys.nullable.

    • MAP_MIN_SIZE

      public static final SettingKey<Integer> MAP_MIN_SIZE
      Specifies minimum size for maps; default is 2; property name map.min.size.

    • MAP_MAX_SIZE

      public static final SettingKey<Integer> MAP_MAX_SIZE
      Specifies maximum size for maps; default is 6; property name map.max.size.

    • MAP_NULLABLE

      public static final SettingKey<Boolean> MAP_NULLABLE
      Specifies whether a null can be generated for maps; default is false; property name map.nullable.

    • MAP_VALUES_NULLABLE

      public static final SettingKey<Boolean> MAP_VALUES_NULLABLE
      Specifies whether a null can be generated for map values; default is false; property name map.values.nullable.

    • MAX_DEPTH

      public static final SettingKey<Integer> MAX_DEPTH
      Specifies the maximum depth of the generated object tree; default is 8; property name max.depth.
      Since:
      2.7.0

    • MODE

      public static final SettingKey<Mode> MODE
      Specifies the mode: strict (unused selectors will trigger an exception) or lenient; default is Mode.STRICT; property name mode.
      Since:
      1.3.3
      See Also:

    • ON_SET_FIELD_ERROR

      @ExperimentalApi public static final SettingKey<OnSetFieldError> ON_SET_FIELD_ERROR
      Specifies what should happen if an error occurs setting a field's value; default is OnSetFieldError.IGNORE; property name on.set.field.error.

      Warning: an error caused by assigning an incompatible type is considered a user error and is never ignored, despite this setting.

      Since:
      2.1.0
      See Also:

    • ON_SET_METHOD_ERROR

      @ExperimentalApi public static final SettingKey<OnSetMethodError> ON_SET_METHOD_ERROR
      Specifies what should happen if an error occurs invoking a setter; default is OnSetMethodError.ASSIGN_FIELD; property name on.set.method.error.
      Since:
      2.1.0
      See Also:

    • ON_SET_METHOD_NOT_FOUND

      @ExperimentalApi public static final SettingKey<OnSetMethodNotFound> ON_SET_METHOD_NOT_FOUND
      Specifies what should happen if a setter method for a field cannot be resolved; default is OnSetMethodNotFound.ASSIGN_FIELD; property name on.set.method.not.found.

      Warning: OnSetMethodNotFound.FAIL is not applied to final fields since a field declared as final cannot have a setter.

      Since:
      2.1.0
      See Also:

    • ON_SET_METHOD_UNMATCHED

      @ExperimentalApi public static final SettingKey<OnSetMethodUnmatched> ON_SET_METHOD_UNMATCHED
      Specifies what should happen if a setter without a matching field is encountered; default is OnSetMethodUnmatched.IGNORE; property name on.set.method.unmatched.

      This setting is only applicable if ASSIGNMENT_TYPE is set to AssignmentType.METHOD.

      The matching of fields and setter methods is based on the configured SETTER_STYLE setting.

      Since:
      4.0.0
      See Also:

    • OVERWRITE_EXISTING_VALUES

      public static final SettingKey<Boolean> OVERWRITE_EXISTING_VALUES
      Specifies whether initialised fields can be overwritten by the engine to random values; default is true; property name overwrite.existing.values.

      If this setting is set to false, then initialised values will not be overwritten by the engine, but they can still be overwritten via the API using a selector.

      Below are a few examples based on the following class: 

      
 class Foo {
     String value = "initial";
 }

      Example 1: initialised value is overwritten with a random value because by default OVERWRITE_EXISTING_VALUES is true. 

      
 // Sample output: Foo[value=VEQHJ]
 Foo foo = Instancio.create(Foo.class);

      Example 2: initialised value is preserved when OVERWRITE_EXISTING_VALUES is false. 

      
 // Output: Foo[value=initial]
 Foo foo = Instancio.of(Foo.class)
     .set(Keys.OVERWRITE_EXISTING_VALUES, false)
     .create();

      Example 3: initialised value can be overwritten using a selector regardless of the OVERWRITE_EXISTING_VALUES setting. 

      
 // Output: Foo[value=Hello]
 Foo foo = Instancio.of(Foo.class)
     .set(Keys.OVERWRITE_EXISTING_VALUES, false)
     .set(field(Foo::getValue), "Hello")
     .create();
      Since:
      2.0.0

    • SEED

      public static final SettingKey<Long> SEED
      Specifies the seed value; default is null; property name seed.
      Since:
      1.5.1

    • SET_BACK_REFERENCES

      @ExperimentalApi public static final SettingKey<Boolean> SET_BACK_REFERENCES
      Specifies whether back references should be set for cyclic classes; default is false (cycles are terminated with null); property name set.back.references.

      For example, given the following classes: 

      
 class Order {
     List<OrderItem> items;
 }
 class OrderItem {
     Order order;
 }

      If SET_BACK_REFERENCES is disabled, creating an instance of Order would result in the OrderItem.order field being null: 

      
 Order order = Instancio.create(Order.class);

 assertThat(order.getItems()).allSatisfy(item ->
     assertThat(item.getOrder()).isNull()
 );

      If SET_BACK_REFERENCES is enabled, creating an instance of Order would result in the OrderItem.order field being set to the parent order: 

      
 Settings settings = Settings.create().set(Keys.SET_BACK_REFERENCES, true);
 Order order = Instancio.of(Order.class)
     .withSettings(settings)
     .create();

 assertThat(order.getItems()).allSatisfy(item ->
     assertThat(item.getOrder()).isSameAs(order)
 );
      Since:
      3.0.0

    • SETTER_EXCLUDE_MODIFIER

      @ExperimentalApi public static final SettingKey<Integer> SETTER_EXCLUDE_MODIFIER
      Specifies modifier exclusions for setter-methods; default is 0 (no exclusions); property name setter.exclude.modifier.

      This setting can be used to control which setter methods are allowed to be invoked (based on method modifiers) when ASSIGNMENT_TYPE is set to AssignmentType.METHOD). For instance, using this setting, it is possible to restrict method assignment to public setters only (by default, a setter is invoked even if it is private).

      Multiple modifiers can be specified using logical OR operator. For example, the following allows only public methods: 

      
   int exclusions = MethodModifier.PACKAGE_PRIVATE
                  | MethodModifier.PROTECTED
                  | MethodModifier.PRIVATE;

   Settings.create().set(Keys.SETTER_EXCLUDE_MODIFIER, exclusions);
      Since:
      2.16.0
      See Also:

    • SETTER_STYLE

      @ExperimentalApi public static final SettingKey<SetterStyle> SETTER_STYLE
      Indicates the naming convention of setter methods to use; default is SetterStyle.SET; property name setter.style.
      Since:
      2.1.0
      See Also:

    • SHORT_MIN

      public static final SettingKey<Short> SHORT_MIN
      Specifies minimum value for shorts; default is 1; property name short.min.

    • SHORT_MAX

      public static final SettingKey<Short> SHORT_MAX
      Specifies maximum value for shorts; default is 10000; property name short.max.

    • SHORT_NULLABLE

      public static final SettingKey<Boolean> SHORT_NULLABLE
      Specifies whether a null can be generated for Short type; default is false; property name short.nullable.

    • STRING_ALLOW_EMPTY

      public static final SettingKey<Boolean> STRING_ALLOW_EMPTY
      Specifies whether an empty string can be generated; default is false; property name string.allow.empty.

    • STRING_FIELD_PREFIX_ENABLED

      public static final SettingKey<Boolean> STRING_FIELD_PREFIX_ENABLED
      Specifies whether generated Strings should be prefixed with field names; default is false; property name string.field.prefix.enabled.
      Since:
      2.4.0

    • STRING_MIN_LENGTH

      public static final SettingKey<Integer> STRING_MIN_LENGTH
      Specifies minimum length of strings; default is 3; property name string.min.length.

    • STRING_MAX_LENGTH

      public static final SettingKey<Integer> STRING_MAX_LENGTH
      Specifies maximum length of strings; default is 10; property name string.max.length.

    • STRING_NULLABLE

      public static final SettingKey<Boolean> STRING_NULLABLE
      Specifies whether a null can be generated for String type; default is false; property name string.nullable.

  • Method Details

    • all

      public static List<SettingKey<Object>> all()
      Returns all keys supported by Instancio.
      Returns:
      all keys

    • get

      public static <T> SettingKey<T> get(@NotNull @NotNull String key)
      Returns a SettingKey instance with the given property key.
      Parameters:
      key - to lookup
      Returns:
      the setting key, or null if none found

    • ofType

      @ExperimentalApi public static <T> SettingKey.SettingKeyBuilder<T> ofType(Class<T> type)
      A builder for creating custom setting keys.

      When defining custom keys, specifying SettingKey.SettingKeyBuilder.withPropertyKey(String) is optional since not all settings will be defined in a properties file. If withPropertyKey() is not specified, then a random property key will be assigned.

      Type Parameters:
      T - the value type
      Parameters:
      type - of the value the key is associated with, not null
      Returns:
      key builder
      Since:
      2.12.0