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:

• Keys
• SettingKey

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(Map<Object,Object> map)	Create settings from the given map.
static Settings	from(Settings other)	Create settings from the given settings.
<T> T	get(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(Class<?> type, Class<?> subtype)	Maps a supertype to a specified subtype, allowing the creation of instances of the subtype when the supertype is requested.
Settings	merge(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(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(Settings other)

Create settings from the given settings.

Parameters:

other - settings to create settings from

Returns:

a new instance of settings

merge

Settings merge(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(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(Class<?> type,
 Class<?> subtype)

Maps a supertype to a specified subtype, allowing the creation of instances of the subtype when the supertype is requested.

Example usage:

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

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

 assertThat(animal).isExactlyInstanceOf(Dog.class);
 

This method is useful when you want to specify a concrete type for a given abstract or interface type during object generation.

Parameters:

type - the supertype to map

subtype - the subtype to map to

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:

• lock()