Package org.instancio.settings

Interface Settings

public interface Settings
This class provides an API for updating settings programmatically. An instance of this class can be created using one of the static methods below. Instances of this class can be shared when creating different objects.
  • create() - returns a new instance of blank settings
  • defaults() - returns a new instance containing default settings

Out of the box, Instancio uses default settings as returned by defaults(). Defaults can be overridden either globally using a configuration file, or per-object using the API, for example: 


     // Create a blank instance of settings and set the overrides
     Settings settings = Settings.create()
         .set(Keys.COLLECTION_MIN_SIZE, 50)
         .set(Keys.COLLECTION_MAX_SIZE, 100);

     // Pass the overrides when creating an object
     Person person = Instancio.of(Person.class)
         .withSettings(settings)
         .create();

For information on how to override settings globally using a configuration file, please refer to the user guide.

Since:
1.0.1
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static Settings
    create()
    Creates a new instance of empty settings.
    static Settings
    defaults()
    Creates a new instance containing default settings.
    static Settings
    from(@NotNull Map<Object,Object> map)
    Create settings from the given map.
    static Settings
    from(@NotNull Settings other)
    Create settings from the given settings.
    <T> T
    get(@NotNull SettingKey<T> key)
    Get setting value for given key.
    Map<Class<?>,Class<?>>
    getSubtypeMap()
    Returns a read-only view of the subtype map.
    boolean
    isLocked()
    Checks if this instance is locked for modifications.
    Settings
    lock()
    Locks these settings for further modifications, making this instance immutable.
    Settings
    mapType(@NotNull Class<?> type, @NotNull Class<?> subtype)
    Maps the supertype from supertype to 'to' subtype.
    Settings
    merge(@NotNull Settings other)
    Creates a new instance of settings by merging given settings with these settings.
    <T> Settings
    set(SettingKey<T> key, T value)
    Set the setting with the given key to the specified value.

  • Method Details

    • create

      static Settings create()
      Creates a new instance of empty settings.
      Returns:
      a new instance of empty settings

    • defaults

      static Settings defaults()
      Creates a new instance containing default settings.
      Returns:
      a new instance of settings containing the defaults

    • from

      static Settings from(@NotNull @NotNull Map<Object,Object> map)
      Create settings from the given map.
      Parameters:
      map - to create settings from
      Returns:
      a new instance of settings created from the given map

    • from

      static Settings from(@NotNull @NotNull Settings other)
      Create settings from the given settings.
      Parameters:
      other - settings to create settings from
      Returns:
      a new instance of settings

    • merge

      Settings merge(@NotNull @NotNull Settings other)
      Creates a new instance of settings by merging given settings with these settings.
      Parameters:
      other - settings to merge
      Returns:
      new instance of merged settings

    • get

      <T> T get(@NotNull @NotNull SettingKey<T> key)
      Get setting value for given key.
      Type Parameters:
      T - setting value type
      Parameters:
      key - setting key
      Returns:
      value for given key, or null if none.

    • set

      <T> Settings set(SettingKey<T> key, T value)
      Set the setting with the given key to the specified value.

      Note: when updating range settings (such as Keys.COLLECTION_MIN_SIZE and Keys.COLLECTION_MAX_SIZE), range bounds are auto-adjusted by Constants.RANGE_ADJUSTMENT_PERCENTAGE if the new minimum is higher than the current maximum, and vice versa.

      Parameters:
      key - the key to set, not null
      value - to set, can be null
      Returns:
      this instance of settings

    • mapType

      Settings mapType(@NotNull @NotNull Class<?> type, @NotNull @NotNull Class<?> subtype)
      Maps the supertype from supertype to 'to' subtype.

      Example: 

      
   Settings settings = Settings.create()
       .mapType(Animal.class, Dog.class);

   Animal animal = Instancio.of(Animal.class)
       .withSettings(settings)
       .create();

   assertThat(animal).isExactlyInstanceOf(Dog.class);
      Parameters:
      type - the type to map to a subtype
      subtype - the subtype class
      Returns:
      this instance of settings

    • getSubtypeMap

      Map<Class<?>,Class<?>> getSubtypeMap()
      Returns a read-only view of the subtype map.
      Returns:
      subtype map

    • lock

      Settings lock()
      Locks these settings for further modifications, making this instance immutable.
      Returns:
      this instance of settings that can no longer be modified

    • isLocked

      boolean isLocked()
      Checks if this instance is locked for modifications.
      Returns:
      true if this instance is locked for modifications, false otherwise
      Since:
      4.4.0
      See Also: