org.jwalk.gen
Interface MasterGenerator

All Superinterfaces:

Generator

All Known Implementing Classes:

ArrayGenerator, ObjectGenerator, ValueGenerator

public interface MasterGenerator
extends Generator

MasterGenerator is the interface implemented by top-level generators. The default ObjectGenerator implements this interface. In addition to the protocol of Generator, a MasterGenerator must also know how to log created objects and convert them to their oracle value representation. This is a quasi-unique persistent string, which allows objects to be compared across different test runs. A MasterGenerator also provides access to the target object, the instance of the test class, during the generation process.

Version:

1.0

Author:

Anthony Simons

Method Summary

void	addDelegate(CustomGenerator generator) Adds a delegate CustomGenerator to this MasterGenerator.
JWalker	getJWalker() Returns the JWalker which created this MasterGenerator.
java.lang.Object	getTarget() Returns the target object, once it has been logged.
java.lang.Class<?>	getTargetType() Returns the type of the target object.
void	logObject(java.lang.Object object) Registers a created object with this MasterGenerator.
void	logTarget(java.lang.Object object) Registers the target object with this MasterGenerator.
java.lang.String	oracleValue(java.lang.Object object) Converts a created object into its oracle value format.

Methods inherited from interface org.jwalk.Generator

canCreate, nextValue

Method Detail

getJWalker

JWalker getJWalker()

Returns the JWalker which created this MasterGenerator. This method allows CustomGenerator classes to access the JWalker, the Settings and the Channels APIs from their owning MasterGenerator.

logTarget

void logTarget(java.lang.Object object)

Registers the target object with this MasterGenerator. The importance of this is that certain binary methods may need another object like the target, or a class like the target's class. The first TestCase in a TestSequence always returns the target object, which is logged with a MasterGenerator for later access.

Parameters:

object - the target object.

getTarget

java.lang.Object getTarget()

Returns the target object, once it has been logged. This method may be used to obtain the target object, after the first TestCase has been executed, which creates the target. If the first TestCase fails, this method will return null.

Returns:

the target object, the instance of the test class.

getTargetType

java.lang.Class<?> getTargetType()

Returns the type of the target object. This method must always work, returning the type of the target object. This is the same as the test class.

logObject

void logObject(java.lang.Object object)

Registers a created object with this MasterGenerator. Allows this MasterGenerator to recognise the object again during the same test run and yield up the same oracle value for it each time. Every test input created by this MasterGenerator (and by its delegate Generators) and every result returned from the test class's constructors and methods is logged. Logging an object creates the oracle value for it and indexes this against the object key. Logging an object twice has no further effect. Logging certain value-wrapping objects has no effect.

Parameters:

object - the Object to be logged.

oracleValue

java.lang.String oracleValue(java.lang.Object object)

Converts a created object into its oracle value format. In order to be comparable across different test runs, objects must be encoded into a format that permits identity-based comparisons, even though the objects are new instances on each test run. Most objects are mapped to an oracle value that encodes the object's type and a unique index, which marks the point in the test sequence when it was created. Certain value-wrapping objects have a unique printed form, and so do not need an encoded oracle value, but appear in their conventional form.

Parameters:

object - the object to encode.

Returns:

the oracle value format, whether encoded or not.

addDelegate

void addDelegate(CustomGenerator generator)

Adds a delegate CustomGenerator to this MasterGenerator. A delegate Generator is another generator which synthesises test inputs on behalf of this MasterGenerator. By adding a generator, you can customise how certain types are synthesised, by effectively delegating the creation of inputs, for those types handled by the delegate generator. If more than one delegate handles the same types, the most recently added delegate takes priority. Adding the delegate causes the delegate to set its owner to this MasterGenerator.

Parameters:

generator - the delegate CustomGenerator.