org.instancio.InstancioApi Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of instancio-core Show documentation
Show all versions of instancio-core Show documentation
The standalone module of Instancio
/*
* Copyright 2022-2024 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.instancio;
import org.instancio.documentation.ExperimentalApi;
import org.instancio.feed.Feed;
import org.instancio.feed.FeedProvider;
import org.instancio.generator.Generator;
import org.instancio.generator.GeneratorSpec;
import org.instancio.settings.SettingKey;
import org.instancio.settings.Settings;
import java.util.function.Function;
import java.util.function.Supplier;
import java.util.stream.Stream;
/**
* Instancio API for generating instances of a class populated with random data.
*
* @param type to create
* @since 1.0.1
*/
public interface InstancioApi extends
BaseApi,
SettingsApi,
LenientModeApi,
VerboseModeApi {
/**
* Creates a new instance of a class and populates it with data.
*
* Example:
*
{@code
* Person person = Instancio.of(Person.class)
* // snip...
* .create();
* }
*
* The returned object will have all its fields populated with random data,
* including collection and array fields.
*
* @return a fully populated object
* @since 1.0.1
*/
T create();
/**
* Returns a {@link Result} containing the created object and seed value
* used to generate its values. The seed value can be used to reproduce
* the same object again.
*
*
Example:
*
{@code
* Result result = Instancio.of(Person.class)
* .set(field(Person::getName), "Homer Simpson")
* .asResult();
*
* Person person = result.get();
* long seed = result.getSeed();
* }
*
* @return result containing the created object
* @since 1.5.1
*/
Result asResult();
/**
* A convenience method for mapping the result (as returned by the
* {@link #create()} method) to another object using a {@code function}.
*
* For example, this method can be used to return the result
* as JSON or other formats:
*
*
{@code
* String json = Instancio.of(Person.class).as(json());
* }
*
* where {@code json()} is a user-defined method implemented
* using the preferred library, e.g. using Jackson:
*
*
{@code
* public static Function json() {
* return result -> new ObjectMapper()
* .writerWithDefaultPrettyPrinter()
* .writeValueAsString(result);
* }
* }
*
* @param function the function for mapping the result
* @param the type of object the result is mapped to
* @return the object returned by applying the mapping function to the result
* @since 4.8.0
*/
@ExperimentalApi
default R as(Function function) {
return function.apply(create());
}
/**
* Creates an infinite {@link Stream} of objects. Ensure {@code limit()}
* is called on the returned stream to prevent an infinite loop.
*
* Each object is generated separately when using this method.
* For instance, if a stateful generator like a sequence generator
* is used, the sequence will restart from one for each object:
*
*
{@code
* List persons = Instancio.of(Person.class)
* .generate(field(Person::getId), gen -> gen.longSeq())
* .stream()
* .limit(3)
* .collect(Collectors.toList());
*
* // Output:
* // [Person[id=1], Person[id=1], Person[id=1]]
* }
*
* Compared to using {@code ofList()}, where the sequence is continuous:
*
*
{@code
* List persons = Instancio.ofList(Person.class)
* .size(3)
* .generate(field(Person::getId), gen -> gen.longSeq())
* .create();
*
* // Output:
* // [Person[id=1], Person[id=2], Person[id=3]]
* }
*
* @return an infinite stream of object instances
* @since 1.1.9
*/
Stream stream();
/**
* Creates a model containing generation parameters for creating an object
* A model acts as a template for creating objects or other models.
*
* The example below illustrates how to create a reusable model
* with predefined attributes, which serves as a template for generating
* objects with base properties:
*
*
{@code
* Model simpsons = Instancio.of(Person.class)
* .set(field(Person::getLastName), "Simpson")
* .set(field(Address::getCity), "Springfield")
* .generate(field(Person::getAge), gen -> gen.ints().range(40, 50))
* .toModel();
*
* Person homer = Instancio.of(simpsons)
* .set(field(Person::getFirstName), "Homer")
* .set(all(Gender.class), Gender.MALE)
* .create();
*
* Person marge = Instancio.of(simpsons)
* .set(field(Person::getFirstName), "Marge")
* .set(all(Gender.class), Gender.FEMALE)
* .create();
* }
*
* For more information, see:
*
*
* - The
* Using Models section of the user guide
* -
* Creating Object Templates Using Models article at instancio.org
*
*
* @return a model that can be used as a template for creating objects
* @see #setModel(TargetSelector, Model)
* @since 1.0.1
*/
Model toModel();
/**
* {@inheritDoc}
*
* @since 1.0.1
*/
@Override
InstancioApi ignore(TargetSelector selector);
/**
* {@inheritDoc}
*
* @since 1.0.1
*/
@Override
InstancioApi withNullable(TargetSelector selector);
/**
* {@inheritDoc}
*
* @since 1.2.3
*/
@Override
InstancioApi set(TargetSelector selector, V value);
/**
* {@inheritDoc}
*
* @since 4.4.0
*/
@Override
@ExperimentalApi
InstancioApi setModel(TargetSelector selector, Model model);
/**
* {@inheritDoc}
*
* @since 1.0.1
*/
@Override
InstancioApi supply(TargetSelector selector, Supplier supplier);
/**
* {@inheritDoc}
*
* @since 1.0.1
*/
@Override
InstancioApi supply(TargetSelector selector, Generator generator);
/**
* {@inheritDoc}
*
* @since 2.2.0
*/
@Override
InstancioApi generate(TargetSelector selector, GeneratorSpecProvider gen);
/**
* {@inheritDoc}
*
* @since 2.6.0
*/
@Override
@ExperimentalApi
InstancioApi generate(TargetSelector selector, GeneratorSpec spec);
/**
* {@inheritDoc}
*
* @since 1.0.4
*/
@Override
InstancioApi onComplete(TargetSelector selector, OnCompleteCallback callback);
/**
* {@inheritDoc}
*
* @since 4.6.0
*/
@Override
@ExperimentalApi
InstancioApi filter(TargetSelector selector, FilterPredicate predicate);
/**
* {@inheritDoc}
*
* @since 4.7.0
*/
@Override
@ExperimentalApi
InstancioApi setBlank(TargetSelector selector);
/**
* {@inheritDoc}
*
* @since 1.4.0
*/
@Override
InstancioApi subtype(TargetSelector selector, Class subtype);
/**
* {@inheritDoc}
*
* @since 3.0.0
*/
@Override
@ExperimentalApi
InstancioApi assign(Assignment... assignments);
/**
* {@inheritDoc}
*
* @since 2.9.0
*/
@Override
InstancioApi withMaxDepth(int maxDepth);
/**
* {@inheritDoc}
*
* @since 4.3.1
*/
@Override
InstancioApi withSetting(SettingKey key, V value);
/**
* {@inheritDoc}
*
* @since 1.0.1
*/
@Override
InstancioApi withSettings(Settings settings);
/**
* {@inheritDoc}
*
* @since 1.0.1
*/
@Override
InstancioApi withSeed(long seed);
/**
* {@inheritDoc}
*
* @since 1.4.1
*/
@Override
InstancioApi lenient();
/**
* {@inheritDoc}
*
* @since 3.0.0
*/
@Override
@ExperimentalApi
InstancioApi verbose();
/**
* {@inheritDoc}
*
* @since 5.0.0
*/
@Override
@ExperimentalApi
InstancioApi applyFeed(TargetSelector selector, Feed feed);
/**
* {@inheritDoc}
*
* @since 5.0.0
*/
@Override
@ExperimentalApi
InstancioApi applyFeed(TargetSelector selector, FeedProvider provider);
/**
* {@inheritDoc}
*
* @since 4.8.0
*/
@Override
@ExperimentalApi
InstancioApi withUnique(TargetSelector selector);
}