Package com.pholser.junit.quickcheck.generator

Class Generator<T>

java.lang.Object
com.pholser.junit.quickcheck.generator.Generator<T>
Type Parameters:
T - type of property parameter to apply this generator's values to
All Implemented Interfaces:
Gen<T>, Shrink<T>
Direct Known Subclasses:
AbstractStringGenerator, ArrayGenerator, BitSetGenerator, BooleanGenerator, CharacterGenerator, CharsetGenerator, ClockGenerator, ComponentizedGenerator, CompositeGenerator, Ctor, DateGenerator, DecimalGenerator, DurationGenerator, EnumGenerator, ExhaustiveDomainGenerator, Fields, GuaranteeValuesGenerator, InstantGenerator, IntegralGenerator, LambdaGenerator, LocalDateGenerator, LocalDateTimeGenerator, LocaleGenerator, LocalTimeGenerator, MarkerInterfaceGenerator, MonthDayGenerator, NullableGenerator, OffsetDateTimeGenerator, OffsetTimeGenerator, OptionalDoubleGenerator, OptionalIntGenerator, OptionalLongGenerator, PeriodGenerator, PropertiesGenerator, RFC4122.AbstractUUIDGenerator, SamplingDomainGenerator, TimeZoneGenerator, VoidGenerator, YearGenerator, YearMonthGenerator, ZilchGenerator, ZonedDateTimeGenerator, ZoneIdGenerator, ZoneOffsetGenerator
public abstract class Generator<T> extends Object implements Gen<T>, Shrink<T>
Produces values for property parameters.

  • Field Details

  • Constructor Details

    • Generator

      protected Generator(Class<T> type)
      Parameters:
      type - class token for type of property parameter this generator is applicable to

    • Generator

      protected Generator(List<Class<T>> types)
      Used for generators of primitives and their wrappers. For example, a Generator<Integer> can be used for property parameters of type Integer or int.
      Parameters:
      types - class tokens for type of property parameter this generator is applicable to

  • Method Details

    • types

      public List<Class<T>> types()
      Returns:
      class tokens for the types of property parameters this generator is applicable to

    • canRegisterAsType

      public boolean canRegisterAsType(Class<?> type)
      Tells whether this generator is allowed to be used for property parameters of the given type.
      Parameters:
      type - type against which to test this generator
      Returns:
      true if the generator is allowed to participate in generating values for property parameters of type

    • shrink

      public final List<T> shrink(SourceOfRandomness random, Object larger)
      Gives some objects that are "smaller" than a given object.

      Generators first ensure that they can participate in shrinking the given value, and if so, they produce shrinks.

      Specified by:
      shrink in interface Shrink<T>
      Parameters:
      random - source of randomness to use in shrinking, if desired
      larger - the larger object
      Returns:
      objects that are "smaller" than the larger object

    • canShrink

      public boolean canShrink(Object larger)

      Tells whether this generator is allowed to participate in the Shrink process for the given "larger" value.

      Unless overridden, the only criterion for whether a generator is allowed to participate in shrinking a value is if the value can be safely cast to the type of values the generator produces.

      Parameters:
      larger - the "larger" value
      Returns:
      whether this generator can participate in "shrinking" the larger value

    • doShrink

      public List<T> doShrink(SourceOfRandomness random, T larger)

      Gives some objects that are "smaller" than a given "larger" object.

      Unless overridden, a generator will produce an empty list of "smaller" values.

      Parameters:
      random - source of randomness to use in shrinking, if desired
      larger - the larger object
      Returns:
      objects that are "smaller" than the larger object. Smaller objects should be provided before bigger objects to make shrinking process faster.

    • magnitude

      public BigDecimal magnitude(Object value)

      Gives a hint to the shrinking process as to the magnitude of the given value. The shrinking process will prefer trying values of greater magnitude before values of lesser magnitude. If not overridden, this implementation returns "one".

      Note to generator writers: Do not worry about normalizing a magnitude to a positive value; the shrinking mechanism will take care of it.

      Parameters:
      value - the value to assess
      Returns:
      a measure of the given value's magnitude
      See Also:

    • narrow

      protected final T narrow(Object wider)

      Attempts to "narrow" the given object to the type this generator produces.

      This is intended for use only by junit-quickcheck itself, and not by creators of custom generators.

      Parameters:
      wider - target of the narrowing
      Returns:
      narrowed the result of the narrowing
      Throws:
      ClassCastException - if the narrowing cannot be performed

    • hasComponents

      public boolean hasComponents()

      This is intended for use only by junit-quickcheck itself, and not by creators of custom generators.

      Returns:
      whether this generator has component generators, such as for those generators that produce lists or maps
      See Also:

    • numberOfNeededComponents

      public int numberOfNeededComponents()

      This is intended for use only by junit-quickcheck itself, and not by creators of custom generators.

      Returns:
      how many component generators this generator needs
      See Also:

    • addComponentGenerators

      public void addComponentGenerators(List<Generator<?>> newComponents)

      Adds component generators to this generator.

      Some generators need component generators to create proper values. For example, list generators require a single component generator in order to generate elements that have the type of the list parameter's type argument.

      This is intended for use only by junit-quickcheck itself, and not by creators of custom generators.

      Parameters:
      newComponents - component generators to add

    • canGenerateForParametersOfTypes

      public boolean canGenerateForParametersOfTypes(List<io.arxila.javaruntype.type.TypeParameter<?>> typeParameters)
      Parameters:
      typeParameters - a list of generic type parameters
      Returns:
      whether this generator can be considered for generating values for property parameters that have the given type parameters in their signatures

    • configure

      public void configure(AnnotatedType annotatedType)

      Configures this generator using annotations from a given annotated type.

      This method considers only annotations that are themselves marked with GeneratorConfiguration.

      By default, the generator will configure itself using this procedure:

      • For each of the given annotations:
        • Find a public method on the generator named configure, that accepts a single parameter of the annotation type
        • Invoke the configure method reflectively, passing the annotation as the argument
      Parameters:
      annotatedType - a type usage
      Throws:
      GeneratorConfigurationException - if the generator does not "understand" one of the generation configuration annotations on the annotated type

    • configure

      public void configure(AnnotatedElement element)
      Parameters:
      element - an annotated program element

    • provide

      public void provide(Generators provided)

      Supplies the available generators to this one.

      This is intended for use only by junit-quickcheck itself, and not by creators of custom generators.

      Parameters:
      provided - repository of available generators

    • copy

      public Generator<T> copy()
      Used by the framework to make a copy of the receiver.
      Returns:
      a copy of the receiver

    • compatibleWithTypeParameter

      protected static boolean compatibleWithTypeParameter(io.arxila.javaruntype.type.TypeParameter<?> parameter, Class<?> clazz)
      Parameters:
      parameter - a generic type parameter
      clazz - a type
      Returns:
      whether the type is compatible with the generic type parameter
      See Also:

    • gen

      protected Generators gen()
      Returns:
      an access point for the available generators

    • gen

      protected Generators gen(SourceOfRandomness random)
      Parameters:
      random - a source of randomness used when locating other generators
      Returns:
      an access point for the available generators

    • configurationAnnotationsOn

      protected static List<Annotation> configurationAnnotationsOn(AnnotatedElement element)
      Gives a list of the GeneratorConfiguration annotations present on the given program element.
      Parameters:
      element - an annotated program element
      Returns:
      what configuration annotations are present on that element

    • collectConfigurationAnnotations

      private Map<Class<? extends Annotation>,Annotation> collectConfigurationAnnotations(AnnotatedElement element)

    • configureStrict

      private void configureStrict(Map<Class<? extends Annotation>,Annotation> byType)

    • configureStrict

      private void configureStrict(Class<? extends Annotation> annotationType, Annotation configuration)

    • configureLenient

      private void configureLenient(Map<Class<? extends Annotation>,Annotation> byType)

    • configureLenient

      private void configureLenient(Class<? extends Annotation> annotationType, Annotation configuration)

    • configure

      private void configure(Class<? extends Annotation> annotationType, Annotation configuration, Consumer<ReflectionException> exceptionHandler)