Package org.instancio

Class Instancio

java.lang.Object
org.instancio.Instancio
public final class Instancio extends Object
Instancio API for creating instances of a class.

Usage

Create and populate an instance of a class

Returns an object fully populated with random data with non-null values. 

     Person person = Instancio.create(Person.class);

Customise object's values

Returns an object populated with random data and some specified fields' values customised. 

     Person person = Instancio.of(Person.class)
             .set(field("fullName"), "Homer Simpson") // Person.fullName
             .supply(all(LocalDateTime.class), () -> LocalDateTime.now())
             .generate(field(Phone.class, "number"), gen -> gen.text().pattern("(#d#d#d) #d#d#d-#d#d#d#d"))
             .create();

Allow null values to be generated

Default behaviour is to populate every field with a non-null, random value. Specifying nullable will randomly generate either null or an actual value. 

     Person person = Instancio.of(Person.class)
             .withNullable(field("gender")) // Person.gender is nullable
             .withNullable(field(Address.class, "street")) // Address.street is nullable
             .withNullable(all(Date.class)) // all dates are nullable
             .create();

Ignore certain fields or classes

Ignored fields will not be populated. Their values will be null (unless they have a default value assigned). 

     Person person = Instancio.of(Person.class)
             .ignore(field("age"))
             .ignore(field(Address.class, "city"))
             .ignore(all(Date.class))
             .create();

Creating instances of a class from a Model

Class specifications can also be saved as a Model using the toModel() method. Then instances of a class can be generated from the model. Models can be useful for:
  • reducing code duplication by re-using the same model in different parts of the code
  • acting as a prototype for creating specialised instances of a class by overriding model specifications

     // Create a model
     Model<Person> simpsons = Instancio.of(Person.class)
             .supply(all(Address.class), () -> new Address("742 Evergreen Terrace", "Springfield", "US"))
             .supply(field("pets"), () -> List.of(
                          new Pet(PetType.CAT, "Snowball"),
                          new Pet(PetType.DOG, "Santa's Little Helper"))
             //... other specs
             .toModel();

     // Use the above model as is
     Person person = Instancio.of(simpsons).create();

     // Use the model but override the name
     Person homer = Instancio.of(simpsons).set(field("name"), "Homer").create();
     Person marge = Instancio.of(simpsons).set(field("name"), "Marge").create();

     // A model can also used to create another model.
     // This snippet creates a new model from the original model to include a new pet.
     Model<Person> withNewPet = Instancio.of(simpsons)
             .supply(field("pets"), () -> List.of(
                          new Pet(PetType.PIG, "Plopper"),
                          new Pet(PetType.CAT, "Snowball"),
                          new Pet(PetType.DOG, "Santa's Little Helper"))
             .toModel();

Creating generic classes

There are two ways to create generic class instances.

Option 1: using a TypeToken


     List<Person> person = Instancio.create(new TypeToken<List<Person>>() {}); // note the empty '{}' braces

Option 2: using withTypeParameters to specify generic type arguments


     List<Person> person = Instancio.of(List.class).withTypeParameters(Person.class).create();

Note: the second approach will produce an "unchecked assignment" warning.

Since:
1.0.1
See Also:

  • Method Details

    • create

      public static <T> T create(Class<T> type)
      Creates a fully-populated instance of given class.
      Type Parameters:
      T - type
      Parameters:
      type - to create
      Returns:
      a fully-populated instance
      Since:
      1.0.1

    • stream

      public static <T> Stream<T> stream(Class<T> type)
      Creates an infinite stream of distinct, fully populated instances of given class.

      Example: 

      
     List<Person> persons = Instancio.stream(Person.class)
         .limit(5)
         .collect(Collectors.toList());
      Type Parameters:
      T - type
      Parameters:
      type - to create
      Returns:
      an infinite stream of distinct, fully populated instances
      Since:
      1.1.9

    • create

      public static <T> T create(TypeTokenSupplier<T> typeToken)
      Creates a fully-populated instance of type specified in the type token. This method can be used to create generic classes.

      Example: List<Person> persons = Instancio.of(new TypeToken<List<Person>>(){}).create()

      Type Parameters:
      T - type
      Parameters:
      typeToken - specifying the type to create
      Returns:
      a fully-populated instance

    • stream

      public static <T> Stream<T> stream(TypeTokenSupplier<T> typeToken)
      Creates an infinite stream of distinct, fully populated instances of type specified in the type token.

      Example: 

      
     List<Pair<Integer, String>> pairs = Instancio.stream(new TypeToken<Pair<Integer, String>>() {})
         .limit(5)
         .collect(Collectors.toList());
      Type Parameters:
      T - type
      Parameters:
      typeToken - specifying the type to create
      Returns:
      an infinite stream of distinct, fully populated instances
      Since:
      1.1.9

    • create

      public static <T> T create(Model<T> model)
      Creates a populated instance of a class represented by the given model.

      See the Model class on how to create models.

      Type Parameters:
      T - type
      Parameters:
      model - specifying generation parameters of the object to create
      Returns:
      a populated instance
      See Also:

    • of

      public static <T> InstancioOfClassApi<T> of(Class<T> type)
      Builder version of create(Class) that allows customisation of generated values. 
      
     Person person = Instancio.of(Person.class)
         .generate(allInts(), gen -> gen.ints().min(1).max(99))
         .supply(all(Address.class), () -> new Address("742 Evergreen Terrace", "Springfield", "US"))
         .supply(field("pets"), () -> List.of(
                             new Pet(PetType.CAT, "Snowball"),
                             new Pet(PetType.DOG, "Santa's Little Helper")))
         .create();
      Type Parameters:
      T - type
      Parameters:
      type - to create
      Returns:
      API builder reference

    • of

      public static <T> InstancioApi<T> of(TypeTokenSupplier<T> typeToken)
      Builder version of create(TypeTokenSupplier) that allows customisation of generated values. 
      
     List<Person> persons = Instancio.of(new TypeToken<List<Person>>(){})
         .generate(allInts(), gen -> gen.ints().min(1).max(99))
         .supply(all(Address.class), () -> new Address("742 Evergreen Terrace", "Springfield", "US"))
         .supply(field("pets"), () -> List.of(
                             new Pet(PetType.CAT, "Snowball"),
                             new Pet(PetType.DOG, "Santa's Little Helper")))
         .create();
      Type Parameters:
      T - type
      Parameters:
      typeToken - specifying the type to create
      Returns:
      API builder reference

    • of

      public static <T> InstancioApi<T> of(Model<T> model)
      Builder version of create(Model) that allows overriding of generation parameters of an existing model. 
      
     Model<Person> personModel = Instancio.of(Person.class)
         .generate(allInts(), gen -> gen.ints().min(1).max(99))
         .supply(all(Address.class), () -> new Address("742 Evergreen Terrace", "Springfield", "US"))
         .supply(field("pets"), () -> List.of(
                             new Pet(PetType.CAT, "Snowball"),
                             new Pet(PetType.DOG, "Santa's Little Helper")))
         .toModel();

     // Use the existing model and add/override generation parameters
     Person simpsonKid = Instancio.of(personModel)
         .generate(field("fullName"), gen -> gen.oneOf("Lisa Simpson", "Bart Simpson"))
         .create();
      Type Parameters:
      T - type
      Parameters:
      model - specifying generation parameters of the object to create
      Returns:
      API builder reference

    • ofList

      public static <T> InstancioOfCollectionApi<List<T>> ofList(Class<T> elementType)
      Builder API for generating a List that allows customisation of generated values.
      Type Parameters:
      T - element type
      Parameters:
      elementType - class to generate as list elements
      Returns:
      API builder reference
      Since:
      2.0.0

    • ofSet

      public static <T> InstancioOfCollectionApi<Set<T>> ofSet(Class<T> elementType)
      Builder API for generating a Set that allows customisation of generated values.
      Type Parameters:
      T - element type
      Parameters:
      elementType - class to generate as set elements
      Returns:
      API builder reference
      Since:
      2.0.0

    • ofMap

      public static <K, V> InstancioOfCollectionApi<Map<K,V>> ofMap(Class<K> keyType, Class<V> valueType)
      Builder API for generating a Map that allowss customisation of generated values.
      Type Parameters:
      K - key type
      V - value type
      Parameters:
      keyType - class to generate as map keys
      valueType - class to generate as map values
      Returns:
      API builder reference
      Since:
      2.0.0