JML

Package org.jmlspecs.jmlunit.strategies

The types in this package are used in providing test data for JML/JUnit testing.

See:
          Description

Interface Summary
BooleanIterator An extended indefinite iterator interface that can iterate over values of type boolean without casting.
BooleanStrategyType The interface of strategies that provide test data of type boolean.
ByteIterator An extended indefinite iterator interface that can iterate over values of type byte without casting.
ByteStrategyType The interface of strategies that provide test data of type byte.
CharIterator An extended indefinite iterator interface that can iterate over values of type char without casting.
CharStrategyType The interface of strategies that provide test data of type char.
DoubleIterator An extended indefinite iterator interface that can iterate over values of type double without casting.
DoubleStrategyType The interface of strategies that provide test data of type double.
FloatIterator An extended indefinite iterator interface that can iterate over values of type float without casting.
FloatStrategyType The interface of strategies that provide test data of type float.
IndefiniteIterator Indefinite iterators.
IntIterator An extended indefinite iterator interface that can iterate over values of type int without casting.
IntStrategyType The interface of strategies that provide test data of type int.
LongIterator An extended indefinite iterator interface that can iterate over values of type long without casting.
LongStrategyType The interface of strategies that provide test data of type long.
ShortIterator An extended indefinite iterator interface that can iterate over values of type short without casting.
ShortStrategyType The interface of strategies that provide test data of type short.
StrategyType Strategies for providing test data.
 

Class Summary
AbstractExtensibleStrategyDecorator A decorator for strategies that allows for easy extension to the test data of the underlying strategy.
AbstractFilteringIteratorDecorator An filtering decorator for an indefinite iterator.
AbstractFilteringStrategyDecorator A decorator for strategies that filters out data that is not approved.
BooleanAbstractFilteringIteratorDecorator An filtering decorator for an indefinite iterator over type boolean.
BooleanAbstractFilteringStrategyDecorator A decorator for strategies that filters out data that is not approved.
BooleanAbstractIterator Common code for iterators over values of type boolean that implement the BooleanIterator interface.
BooleanAbstractStrategy Common code for strategies for providing test data of type boolean.
BooleanArrayIterator A BooleanIterator over arrays of boolean elements.
BooleanBigStrategy Test data of type boolean.
BooleanCompositeIterator Composition of several BooleanIterators.
BooleanCompositeStrategy A composition of several BooleanStrategys
BooleanExtensibleStrategy Common code for extensible strategies for providing test data of type boolean.
BooleanExtensibleStrategyDecorator A decorator for strategies (which provide test data of type type boolean) that allows for easy extension to the test data of the underlying strategy.
BooleanStrategy Test data of type boolean.
BooleanStrategyTypeTest Hand-coded JUnit test for subtypes of BooleanStrategyType.
ByteAbstractFilteringIteratorDecorator An filtering decorator for an indefinite iterator over type byte.
ByteAbstractFilteringStrategyDecorator A decorator for strategies that filters out data that is not approved.
ByteAbstractIterator Common code for iterators over values of type byte that implement the ByteIterator interface.
ByteAbstractStrategy Common code for strategies for providing test data of type byte.
ByteArrayIterator A ByteIterator over arrays of byte elements.
ByteBigStrategy Slightly more extensive test data of type byte.
ByteCompositeIterator Composition of several ByteIterators.
ByteCompositeStrategy A composition of several ByteStrategys
ByteExtensibleStrategy Common code for extensible strategies for providing test data of type byte.
ByteExtensibleStrategyDecorator A decorator for strategies (which provide test data of type type byte) that allows for easy extension to the test data of the underlying strategy.
ByteNonNegativeIteratorDecorator An indefinite iterator that filters out negative test data.
ByteNonNegativeStrategyDecorator A decorator for strategies that filters out that filters out negative test data.
ByteStrategy Minimal test data of type byte.
ByteStrategyTypeTest Hand-coded JUnit test for subtypes of ByteStrategyType.
CachedObjectAbstractStrategy A strategy for producing (test) data of an immutable or cloneable reference types from cached data provided by the user.
CharAbstractFilteringIteratorDecorator An filtering decorator for an indefinite iterator over type char.
CharAbstractFilteringStrategyDecorator A decorator for strategies that filters out data that is not approved.
CharAbstractIterator Common code for iterators over values of type char that implement the CharIterator interface.
CharAbstractStrategy Common code for strategies for providing test data of type char.
CharArrayIterator A CharIterator over arrays of char elements.
CharBigStrategy Slightly more extensive test data of type char.
CharCompositeIterator Composition of several CharIterators.
CharCompositeStrategy A composition of several CharStrategys
CharExtensibleStrategy Common code for extensible strategies for providing test data of type char.
CharExtensibleStrategyDecorator A decorator for strategies (which provide test data of type type char) that allows for easy extension to the test data of the underlying strategy.
CharIterator_JML_Test Automatically-generated test driver for JML and JUnit based testing of CharIterator.
CharIterator_JML_Test.OneTest A JUnit test object that can run a single test method.
CharIterator_JML_Test.TestAdvance Test for the advance method.
CharIterator_JML_Test.TestAtEnd Test for the atEnd method.
CharIterator_JML_Test.TestClone Test for the clone method.
CharIterator_JML_Test.TestGet Test for the get method.
CharIterator_JML_Test.TestGetChar Test for the getChar method.
CharIterator_JML_TestData Supply test data for the JML and JUnit based testing of CharIterator.
CharStrategy Minimal test data of type char.
CharStrategyTypeTest Hand-coded JUnit test for subtypes of CharStrategyType.
CloneableObjectAbstractExtensibleStrategyDecorator A decorator for cloneable object strategies that allows for easy extension with cloneable test data.
CloneableObjectAbstractStrategy A strategy for producing test data of cloneable reference types.
CloneableObjectAbstractStrategyTest Hand-coded JUnit test for testing CloneableObjectAbstractStrategy.
CloneableObjectArrayAbstractIterator An iterator that provides test data by returning a clone of the current object from an array of cloneable objects passed to its constructor.
CloneableObjectArrayAbstractIterator_JML_Test Automatically-generated test driver for JML and JUnit based testing of CloneableObjectArrayAbstractIterator.
CloneableObjectArrayAbstractIterator_JML_Test.OneTest A JUnit test object that can run a single test method.
CloneableObjectArrayAbstractIterator_JML_Test.TestAdvance Test for the advance method.
CloneableObjectArrayAbstractIterator_JML_Test.TestAtEnd Test for the atEnd method.
CloneableObjectArrayAbstractIterator_JML_Test.TestClone Test for the clone method.
CloneableObjectArrayAbstractIterator_JML_Test.TestGet Test for the get method.
CloneableObjectArrayAbstractIterator_JML_Test.TestToString Test for the toString method.
CloneableObjectArrayAbstractIterator_JML_TestData Supply test data for the JML and JUnit based testing of CloneableObjectArrayAbstractIterator.
CollectionStrategy A small extensible strategy for producing test data of type Collection.
CompositeIterator Composition of several indefinite iterators.
CompositeIterator_JML_Test Automatically-generated test driver for JML and JUnit based testing of CompositeIterator.
CompositeIterator_JML_Test.OneTest A JUnit test object that can run a single test method.
CompositeIterator_JML_Test.TestAdvance Test for the advance method.
CompositeIterator_JML_Test.TestAtEnd Test for the atEnd method.
CompositeIterator_JML_Test.TestClone Test for the clone method.
CompositeIterator_JML_Test.TestCompositeIterator Test for the CompositeIterator contructor.
CompositeIterator_JML_Test.TestCompositeIterator$1 Test for the CompositeIterator contructor.
CompositeIterator_JML_Test.TestCompositeIterator$2 Test for the CompositeIterator contructor.
CompositeIterator_JML_Test.TestGet Test for the get method.
CompositeIterator_JML_Test.TestToString Test for the toString method.
CompositeIterator_JML_TestData Supply test data for the JML and JUnit based testing of CompositeIterator.
CompositeStrategy A composition of several strategies
CompositeStrategyTest Hand-coded JUnit test for testing CompositeStrategy.
ConstructorFailed A class that stores an exception that occured during test suite construction as a JUnit test, and when the test is run makes the problem a failure.
DoubleAbstractFilteringIteratorDecorator An filtering decorator for an indefinite iterator over type double.
DoubleAbstractFilteringIteratorDecorator_JML_Test Automatically-generated test driver for JML and JUnit based testing of DoubleAbstractFilteringIteratorDecorator.
DoubleAbstractFilteringIteratorDecorator_JML_Test.OneTest A JUnit test object that can run a single test method.
DoubleAbstractFilteringIteratorDecorator_JML_Test.TestAdvance Test for the advance method.
DoubleAbstractFilteringIteratorDecorator_JML_Test.TestApprove Test for the approve method.
DoubleAbstractFilteringIteratorDecorator_JML_Test.TestAtEnd Test for the atEnd method.
DoubleAbstractFilteringIteratorDecorator_JML_Test.TestClone Test for the clone method.
DoubleAbstractFilteringIteratorDecorator_JML_Test.TestGet Test for the get method.
DoubleAbstractFilteringIteratorDecorator_JML_Test.TestGetDouble Test for the getDouble method.
DoubleAbstractFilteringIteratorDecorator_JML_Test.TestInitialize Test for the initialize method.
DoubleAbstractFilteringIteratorDecorator_JML_Test.TestToString Test for the toString method.
DoubleAbstractFilteringIteratorDecorator_JML_TestData Supply test data for the JML and JUnit based testing of DoubleAbstractFilteringIteratorDecorator.
DoubleAbstractFilteringStrategyDecorator A decorator for strategies that filters out data that is not approved.
DoubleAbstractIterator Common code for iterators over values of type double that implement the DoubleIterator interface.
DoubleAbstractStrategy Common code for strategies for providing test data of type double.
DoubleArrayIterator A DoubleIterator over arrays of double elements.
DoubleBigStrategy Slightly more extensive test data of type double.
DoubleCompositeIterator Composition of several DoubleIterators.
DoubleCompositeIterator_JML_Test Automatically-generated test driver for JML and JUnit based testing of DoubleCompositeIterator.
DoubleCompositeIterator_JML_Test.OneTest A JUnit test object that can run a single test method.
DoubleCompositeIterator_JML_Test.TestAdvance Test for the advance method.
DoubleCompositeIterator_JML_Test.TestAtEnd Test for the atEnd method.
DoubleCompositeIterator_JML_Test.TestClone Test for the clone method.
DoubleCompositeIterator_JML_Test.TestDoubleCompositeIterator Test for the DoubleCompositeIterator contructor.
DoubleCompositeIterator_JML_Test.TestDoubleCompositeIterator$1 Test for the DoubleCompositeIterator contructor.
DoubleCompositeIterator_JML_Test.TestDoubleCompositeIterator$2 Test for the DoubleCompositeIterator contructor.
DoubleCompositeIterator_JML_Test.TestGet Test for the get method.
DoubleCompositeIterator_JML_Test.TestGetDouble Test for the getDouble method.
DoubleCompositeIterator_JML_Test.TestToString Test for the toString method.
DoubleCompositeIterator_JML_TestData Supply test data for the JML and JUnit based testing of DoubleCompositeIterator.
DoubleCompositeStrategy A composition of several DoubleStrategys
DoubleExtensibleStrategy Common code for extensible strategies for providing test data of type double.
DoubleExtensibleStrategyDecorator A decorator for strategies (which provide test data of type type double) that allows for easy extension to the test data of the underlying strategy.
DoubleNonNegativeIteratorDecorator An indefinite iterator that filters out negative test data.
DoubleNonNegativeStrategyDecorator A decorator for strategies that filters out that filters out negative test data.
DoubleStrategy Minimal test data of type double.
DoubleStrategyTypeTest Hand-coded JUnit test for subtypes of DoubleStrategyType.
EmptyNewObjectIterator An empty new object iterator.
FloatAbstractFilteringIteratorDecorator An filtering decorator for an indefinite iterator over type float.
FloatAbstractFilteringStrategyDecorator A decorator for strategies that filters out data that is not approved.
FloatAbstractIterator Common code for iterators over values of type float that implement the FloatIterator interface.
FloatAbstractStrategy Common code for strategies for providing test data of type float.
FloatArrayIterator A FloatIterator over arrays of float elements.
FloatBigStrategy Slightly more extensive test data of type float.
FloatCompositeIterator Composition of several FloatIterators.
FloatCompositeStrategy A composition of several FloatStrategys
FloatExtensibleStrategy Common code for extensible strategies for providing test data of type float.
FloatExtensibleStrategyDecorator A decorator for strategies (which provide test data of type type float) that allows for easy extension to the test data of the underlying strategy.
FloatNonNegativeIteratorDecorator An indefinite iterator that filters out negative test data.
FloatNonNegativeStrategyDecorator A decorator for strategies that filters out that filters out negative test data.
FloatStrategy Minimal test data of type float.
FloatStrategyTypeTest Hand-coded JUnit test for subtypes of FloatStrategyType.
ImmutableObjectAbstractStrategy A strategy for producing test data of reference types with immutable objects, such as String.
ImmutableObjectAbstractStrategyTest Hand-coded JUnit test for testing ImmutableObjectAbstractStrategy.
ImmutableObjectArrayIterator An iterator that provides test data by returning the current object from an array of immutable objects passed to its constructor.
ImmutableObjectArrayIterator_JML_Test Automatically-generated test driver for JML and JUnit based testing of ImmutableObjectArrayIterator.
ImmutableObjectArrayIterator_JML_Test.OneTest A JUnit test object that can run a single test method.
ImmutableObjectArrayIterator_JML_Test.TestAdvance Test for the advance method.
ImmutableObjectArrayIterator_JML_Test.TestAtEnd Test for the atEnd method.
ImmutableObjectArrayIterator_JML_Test.TestClone Test for the clone method.
ImmutableObjectArrayIterator_JML_Test.TestGet Test for the get method.
ImmutableObjectArrayIterator_JML_Test.TestImmutableObjectArrayIterator Test for the ImmutableObjectArrayIterator contructor.
ImmutableObjectArrayIterator_JML_Test.TestToString Test for the toString method.
ImmutableObjectArrayIterator_JML_TestData Supply test data for the JML and JUnit based testing of ImmutableObjectArrayIterator.
ImmutableObjectExtensibleStrategyDecorator A decorator for immutable object strategies that allows for easy extension with immutable test data.
IndefiniteIteratorUtilities Static functions to aid in testing subtypes of IndefiniteIterator and hence, the testing of various strategies.
IntAbstractFilteringIteratorDecorator An filtering decorator for an indefinite iterator over type int.
IntAbstractFilteringStrategyDecorator A decorator for strategies that filters out data that is not approved.
IntAbstractIterator Common code for iterators over values of type int that implement the IntIterator interface.
IntAbstractStrategy Common code for strategies for providing test data of type int.
IntArrayIterator A IntIterator over arrays of int elements.
IntArrayIterator_JML_Test Automatically-generated test driver for JML and JUnit based testing of IntArrayIterator.
IntArrayIterator_JML_Test.OneTest A JUnit test object that can run a single test method.
IntArrayIterator_JML_Test.TestAdvance Test for the advance method.
IntArrayIterator_JML_Test.TestAtEnd Test for the atEnd method.
IntArrayIterator_JML_Test.TestClone Test for the clone method.
IntArrayIterator_JML_Test.TestGet Test for the get method.
IntArrayIterator_JML_Test.TestGetInt Test for the getInt method.
IntArrayIterator_JML_Test.TestIntArrayIterator Test for the IntArrayIterator contructor.
IntArrayIterator_JML_Test.TestToString Test for the toString method.
IntArrayIterator_JML_TestData Supply test data for the JML and JUnit based testing of IntArrayIterator.
IntBigStrategy Slightly more extensive test data of type int.
IntCompositeIterator Composition of several IntIterators.
IntCompositeStrategy A composition of several IntStrategys
IntExtensibleStrategy Common code for extensible strategies for providing test data of type int.
IntExtensibleStrategyDecorator A decorator for strategies (which provide test data of type type int) that allows for easy extension to the test data of the underlying strategy.
IntNonNegativeIteratorDecorator An indefinite iterator that filters out negative test data.
IntNonNegativeStrategyDecorator A decorator for strategies that filters out that filters out negative test data.
IntStrategy Minimal test data of type int.
IntStrategyTypeTest Hand-coded JUnit test for subtypes of IntStrategyType.
IteratorAbstractAdapter Make a java.util.Iterator into an IndefiniteIterator.
JMLCollectionStrategy A strategy for generating test data of type JMLCollection.
JMLCollectionUnextensibleStrategy A strategy for providing test data of type JMLCollection.
JMLTypeStrategy A strategy for generating test data of type JMLType.
JMLTypeUnextensibleStrategy A strategy for providing test data of type JMLType.
LimitedTestSuite A kind of test suite that only allows the first n tests to be added, and ignores the rest.
LongAbstractFilteringIteratorDecorator An filtering decorator for an indefinite iterator over type long.
LongAbstractFilteringStrategyDecorator A decorator for strategies that filters out data that is not approved.
LongAbstractIterator Common code for iterators over values of type long that implement the LongIterator interface.
LongAbstractStrategy Common code for strategies for providing test data of type long.
LongArrayIterator A LongIterator over arrays of long elements.
LongBigStrategy Slightly more extensive test data of type long.
LongCompositeIterator Composition of several LongIterators.
LongCompositeStrategy A composition of several LongStrategys
LongExtensibleStrategy Common code for extensible strategies for providing test data of type long.
LongExtensibleStrategyDecorator A decorator for strategies (which provide test data of type type long) that allows for easy extension to the test data of the underlying strategy.
LongNonNegativeIteratorDecorator An indefinite iterator that filters out negative test data.
LongNonNegativeStrategyDecorator A decorator for strategies that filters out that filters out negative test data.
LongStrategy Minimal test data of type long.
LongStrategyTypeTest Hand-coded JUnit test for subtypes of LongStrategyType.
NewObjectAbstractExtensibleStrategyDecorator A decorator for strategies that allows for easy extension in the "new object" style to the test data of the underlying strategy.
NewObjectAbstractIterator An iterator that provides test data by creating (in general) the objects each time the get() method is called.
NewObjectAbstractIterator_JML_Test Automatically-generated test driver for JML and JUnit based testing of NewObjectAbstractIterator.
NewObjectAbstractIterator_JML_Test.OneTest A JUnit test object that can run a single test method.
NewObjectAbstractIterator_JML_Test.TestAdvance Test for the advance method.
NewObjectAbstractIterator_JML_Test.TestAtEnd Test for the atEnd method.
NewObjectAbstractIterator_JML_Test.TestClone Test for the clone method.
NewObjectAbstractIterator_JML_Test.TestGet Test for the get method.
NewObjectAbstractIterator_JML_Test.TestInitialize Test for the initialize method.
NewObjectAbstractIterator_JML_Test.TestMake Test for the make method.
NewObjectAbstractIterator_JML_TestData Supply test data for the JML and JUnit based testing of NewObjectAbstractIterator.
NewObjectAbstractStrategy A strategy that provides test data by creating (in general) the objects each time the make() method is called for a particular argument.
NewObjectAbstractStrategyTest Hand-coded JUnit test for testing NewObjectAbstractStrategy.
NonNullIteratorDecorator An indefinite iterator that filters out null's that would be returned otherwise.
NonNullIteratorDecorator_JML_Test Automatically-generated test driver for JML and JUnit based testing of NonNullIteratorDecorator.
NonNullIteratorDecorator_JML_Test.OneTest A JUnit test object that can run a single test method.
NonNullIteratorDecorator_JML_Test.TestAdvance Test for the advance method.
NonNullIteratorDecorator_JML_Test.TestApprove Test for the approve method.
NonNullIteratorDecorator_JML_Test.TestAtEnd Test for the atEnd method.
NonNullIteratorDecorator_JML_Test.TestClone Test for the clone method.
NonNullIteratorDecorator_JML_Test.TestGet Test for the get method.
NonNullIteratorDecorator_JML_Test.TestInitialize Test for the initialize method.
NonNullIteratorDecorator_JML_Test.TestNonNullIteratorDecorator Test for the NonNullIteratorDecorator contructor.
NonNullIteratorDecorator_JML_Test.TestToString Test for the toString method.
NonNullIteratorDecorator_JML_TestData Supply test data for the JML and JUnit based testing of NonNullIteratorDecorator.
NonNullStrategyDecorator A decorator that filters out null test data.
NonNullStrategyDecoratorTest Hand-coded JUnit test for testing NonNullStrategyDecorator.
ObjectArrayAbstractIterator An indefinite iterator that provides test data from an array of objects passed to its constructor.
ObjectStrategy A minimal, extensible strategy for producing test data of type Object.
ObjectStrategyTest Hand-coded JUnit test for testing ObjectStrategy.
ShortAbstractFilteringIteratorDecorator An filtering decorator for an indefinite iterator over type short.
ShortAbstractFilteringStrategyDecorator A decorator for strategies that filters out data that is not approved.
ShortAbstractIterator Common code for iterators over values of type short that implement the ShortIterator interface.
ShortAbstractStrategy Common code for strategies for providing test data of type short.
ShortArrayIterator A ShortIterator over arrays of short elements.
ShortBigStrategy Slightly more extensive test data of type short.
ShortCompositeIterator Composition of several ShortIterators.
ShortCompositeStrategy A composition of several ShortStrategys
ShortExtensibleStrategy Common code for extensible strategies for providing test data of type short.
ShortExtensibleStrategyDecorator A decorator for strategies (which provide test data of type type short) that allows for easy extension to the test data of the underlying strategy.
ShortNonNegativeIteratorDecorator An indefinite iterator that filters out negative test data.
ShortNonNegativeStrategyDecorator A decorator for strategies that filters out that filters out negative test data.
ShortStrategy Minimal test data of type short.
ShortStrategyTypeTest Hand-coded JUnit test for subtypes of ShortStrategyType.
StringStrategy A strategy for producing test data of type String.
StringStrategyTest Hand-coded JUnit test for testing StringStrategy.
TestSuite This class is automatically generated using org.multijava.util.testing.Main and is used to group a collection of JUnit tests for the local package and perhaps some subpackages.
TestSuite.TestSuite$1  
 

Exception Summary
TestSuiteFullException This exception is ued to tell a test driver that we have enough tests.
 

Package org.jmlspecs.jmlunit.strategies Description

The types in this package are used in providing test data for JML/JUnit testing. These types constitute a small framework, and users should not hesitate to extend them in ways that are useful for their purposes.

Overview

In this package are mainly two kinds of types: iterators and strategies. These follow the design patterns of the same names. There are also some other miscellaneous types related to JML/JUnit testing.

Test data are provided to the test drivers through iterators. In this package, strategies are mainly used as ways to compute iterators for providing test data. We now describe iterators and strategies in more detail. We began by describing the iterators, because the strategies build on them. However, readers may want to skip directly to the discussion of strategies, because the strategies are most often used by testers, whereas the iterators are usually only used indirectly.

Iterators

The iterators describe the mechanisms for iterating over data of a given type. The fundamental interface for these iterators is the type IndefiniteIterator. An indefinite iterator can be thought of as a cursor that points into a sequence. Unlike normal Java iterators (such as Iterator), an indefinite iterator does not advance when the get() method is called; instead, the advance() method must be called explicitly to advance the cursor. This is useful for the loops in the test drivers, which must provide data for an outer loop's type for each iteration of an inner loop.

They are two kinds of iterators that implement or extend this interface. The first is a set of iterators that can iterate over objects (i.e., references to objects). The second is a set of iterators that can iterate over primitive values (such as booleans or ints).

Iterators That Iterate Over Objects

The concrete class ImmutableObjectArrayIterator can be used in testing objects of types that have immutable objects (such as String). Its get() method simply returns the current object from the array of immutable objects passed to its constructor.

The abstract class CloneableObjectArrayAbstractIterator can be used in testing objects of types that have a clone() method. The get() method of this iteratoro returns a clone of the current object from the array of immutable objects passed to its constructor. Unfortunately, because Java doesn't have a standard interface with a public clone() method (Cloneable should have this, but doesn't), there is no way to make this class concrete. Instead it relies on a cloneElement(Object) method to clone the objects of the type. The cloneElement(Object) method is specified to be "pure", and so it cannot call a clone() method that is not pure. If that is not possible, then one should use the following iterator type.

The abstract class NewObjectAbstractIterator describes a family of iterators that provide test data by creating an object each time the get() method is called. Generally this would be done to avoid aliasing between the objects used in testing. (However one can also use this kind of iterator to create intentional aliasing if desired, by returning the same object multiple times when the get() method is called.) This package does not provide any useful concrete subclasses of NewObjectAbstractIterator. However, there is an subclass that defines an empty new object iterator in EmptyNewObjectIterator, and an anonymous subclass in NewObjectAbstractStrategy.

The classes ImmutableObjectArrayIterator, CloneableObjectArrayAbstractIterator, and NewObjectAbstractIterator correspond to three of the basic strategies for producing test data, which are embodied in this package by the classes ImmutableObjectAbstractStrategy, CloneableObjectAbstractStrategy, and NewObjectAbstractStrategy, respectively. There also some classes that are convenient for constructing other indefinite iterators that return objects. These are described below.

The concrete class CompositeIterator allows one to compose several indefinite iterators into one larger indefinite iteration.

The concrete class NonNullIteratorDecorator allows one to filter out null values from an indefinite iteration. It is built as a subclass of AbstractFilteringIteratorDecorator from which you may build other filtering iterator decorators.

Iterators That Iterate Over Primitive Values

To provide efficient access to indefinite iteration elements of primitive value types, this package also provides several other implementations of the IndefiniteIterator interface. Indeed, this interface is extended by an interface for each primitive value type in Java: namely BooleanIterator, ByteIterator, CharIterator, DoubleIterator, FloatIterator, IntIterator, LongIterator, and ShortIterator. These extended interfaces iterate over values of the corresponding primitive value types. For example, ShortIterator can iterate over the primitive type short. For each such primitive value type VT, the corresponding interface VTIterator has a method, getVT(), that returns a value of the type VT. For example, ShortIterator has a method getShort() that returns a value of type short.

For each of the primitive value types, VT, the corresponding interface is implemented by an abstract class, named, VTAbstractIterator. These abstract classes simply define the get() method required by the interface using the getVT() method. For example, the get() method required by the interface ShortIterator (inherited from IndefiniteIterator) is defined to call the getShort() method, and to make the result the "boxed" version of that number, by calling the constructor for the boxed type Short.

Each such abstract class, VTAbstractIterator, is in turn extended by a concrete class named VTArrayIterator, which can iterate over arrays of the type VT. For example, ShortAbstractIterator has a subclass ShortArrayIterator, which can iterator over arrays of type short.

Also, for each such value type, VT, there is a composite iterator, VTCompositeIterator. For example ShortCompositeIterator is one such class. There is also an abstract filtering iterator decorator VTAbstractFilteringIteratorDecorator -- for example ShortAbstractFilteringIteratorDecorator. These can be used to make your own filtering decorators. An example, which also exists for each of the numeric types, is ShortNonNegativeIteratorDecorator.

Strategies

A strategy describes a way to compute an iterator. Think of strategies as embodying decisions about how to provide test data. The fundamental interface for strategies is the type StrategyType. This interface consists of a single method iterator(), which can be called to return an IndefiniteIterator object. This indefinite iterator provides the actual test data. Thus the strategy's sole responsibility is to compute this iterator. One way to do this is to provide the actual data (e.g., in an array) to the constructor of an appropriate indefinite iterator class.

In what follows we first describe how one should pick a strategy, and then describe the strategies in detail.

Choosing a Strategy

From the user's perspective, the choice of a strategy depends on the kind of test data to be provided.

Strategies for Immutable Objects or Primitive Values

For types with immutable objects that are built-in to Java, one can use a strategy that is provided in this package. For example, for the type String one would use the strategy StringStrategy. For a primitive value type, such as short one would use the corresponding strategy, such as ShortStrategy. For both kinds of strategies, the strategy itself provides only a very small set of test data. You can either use the slightly more extensive test data provided in a class like ShortBigStrategy or you can extend one of these strategies yourself by defining a subclass that overrides the addData() method to provide the additional test data. The addData() method returns an array of objects, and by using an anonymous subclass and an array allocation expression, in the body of the method override it is easy to provide test data of such types. For example, the following shows how to make a subclass of StringStrategy that provides three additional pieces of test data. Note that this is an expression in Java of type StringStrategy.

            new StringStrategy() {
                protected Object[] addData() {
                    return new String[] {
                        "Baby",
                        "Cortez",
                        "Yoonsik",
                    };
                }
            }

For types with immutable objects for which no strategy is provided in this package, the user can subclass the framework's abstract class ImmutableObjectAbstractStrategy. By default this strategy provides only the null object.

This abstract strategy is extended to by overriding the addData() method, as shown above. Examples of how to extend this strategy with your own data are found in the class ImmutableObjectAbstractStrategyTest.

Strategies for Cloneable Types

For types with mutable objects that have a clone() method, one can make a subclass of the class CloneableObjectAbstractStrategy, and provide test data by overriding the addData() method, as above. This strategy clones each object in the array of objects provided as it is returned by the get() method. By default this strategy provides only the null object.

This abstract strategy is extended to by overriding the addData() method, in the same was as the StringStrategy example above. However, subclasses of CloneableObjectAbstractStrategy must also provide a cloneElement(Object) method.

Examples of how to extend this abstract strategy with your own data are found in the class CloneableObjectAbstractStrategyTest.

Strategies for Non-Cloneable Types with Mutable Objects

For the case of a type with objects that are both mutable and not cloneable, one can make a subclass of NewObjectAbstractStrategy. One has to override the make(int) method to provide test data. This can also be done using an anonymous subclass. For example, one can write the following expression to make such a subclass and override the make(int) method.

            new NewObjectAbstractStrategy() {
                public Object make(int n) {
                    switch (n) {
                    case 0:
                        return new Person("Baby");
                    case 1:
                        return new Person("Cortez");
                    case 2:
                        return new Person("Isabella");
                    default:
                        break;
                    }
                    throw new java.util.NoSuchElementException();
                }
            }
Note that NewObjectAbstractStrategy automatically adds null as a default piece of test data, even though it is not returned the make(int) method. In essence, the indefinite iterator returned by this strategy is the composite of an iterator just returns null and one that iterates over the test data provided by the override of the make(int).

There are also a few pre-defined strategies with the same extension mechanism in this framework. These are described below.

If the type you want to provide test data for is actually Object, then you can extend the type ObjectStrategy, in the same way as described above. This strategy, by default, provides the null object and an empty object, made with new Object(). When you extend it with appropriate data by overriding the make(int), it can be useful for testing an equals method.

An alternative to extending ObjectStrategy directly is to make a composite of this strategy and a strategy for some other type (e.g., the type whose objects you are actually testing). This is especially useful for testing the equals(Object) method, since it will provide some test data for which the equals method will return true. For example, if vMyTypeStrategy is a fields that holds a strategy for providing test data of type MyType, the the following would be an expression that computes a strategy that is a composite of ObjectStrategy and vMyTypeStrategy.

        new org.jmlspecs.jmlunit.strategies.CompositeStrategy
        (new org.jmlspecs.jmlunit.strategies.StrategyType[] {
            new org.jmlspecs.jmlunit.strategies.ObjectStrategy(),
            vMyTypeStrategy,
         }
        )
Note that vMyTypeStrategy has to already have a value for this exprssion to be well-defined; hence vMyTypeStrategy should have a definition that appears earlier than this expression in the program.

In the same ways, you can extend the type CollectionStrategy to provide test data of type Collection. By default, this strategy only provides a small amount of test data. CollectionStrategy is a good example of how to extend NewObjectAbstractStrategy to provide useful test data of some type. (See also NewObjectAbstractStrategyTest for a small example.)

Combining and Filtering Strategies

You may sometimes find it convenient to combine strategies, or to filter them. The basic way to combine strategies is to use the CompositeStrategy type. This class lets you combine two or more strategies by sequencing the test data they provide. Such composites also exist for each primitive value type; for example, you can use ShortCompositeStrategy to combine strategies that provide test data of type short, etc.

The strategy NonNullStrategyDecorator is a Decorator that takes a strategy and filters it for non-null elements; that is, it only passes along the elements that are not null, effectively removing those that are null. As a decorator, it takes a strategy as an argument to its constructor. This strategy is built from the abstract class AbstractFilteringStrategyDecorator, which you can use to build your own filtering strategy decorators. Such filtering strategies also exist for each primitive value type; for example, you can use ShortAbstractFilteringStrategyDecorator to define your own filtering decorators on strategies that provide data of type short. An example of this is found in ShortNonNegativeStrategyDecorator.

Details

They are two kinds of strategies that implement or extend the StrategyType interface. The first is a set of strategies that can be used to provide test data of reference types (subtypes of Object). The second is a set of strategies that can be used to provide test data of primitive value types (such as booleans or ints).

Strategies for Objects

The abstract class ImmutableObjectAbstractStrategy is a strategy for producing test data of types with immutable objects, like String. The strategy JMLCollectionStrategy is built from this class.

The abstract class CloneableAbstractStrategy is a strategy for producing test data for types with mutable objects that have a clone() method. The strategy JMLTypeStrategy is built from this class.

The abstract class NewObjectAbstractStrategy is a strategy for producing test data for types with mutable objects that do not have a clone() method.

Strategies for Primitive Values

For each of the primitive value types, VT, there are two corresponding strategies: VTStrategy and VTBigStrategy. For example, for the primitive value type short there are the strategies ShortStrategy and ShortStrategy. The classes with names of the form VTStrategy provide the barest minimum of test data. For the integral types this consists of just the numbers 0, 1, and -1. The floating point types provide these along with the "not a number" value of the type. The classes with names of the form VTBigStrategy provide a slightly larger amount of test data; for the numeric types this includes the numbers 3, -5, and the minimum and maximum values of each type. For the floating point types, the VTBigStrategy classes also include the various infinities and smallest values.

Making Extensible Strategies Yourself

You may sometimes find it convenient to make a strategy extensible yourself, in order to allow further specialization. For immutable and cloneable objects, you can do this in the same way as many of the standard strategies by using the ImmutableObjectExtensibleStrategyDecorator or the CloneableObjectAbstractExtensibleStrategyDecorator. These decorators are built from AbstractExtensibleStrategyDecorator, which may be useful for more general cases. Versions of such extensible strategy decorators also exist for all the primitive value types; for example, there is ShortExtensibleStrategyDecorator.

For types with mutable objects that have no clone method, you can subclass NewObjectAbstractExtensibleStrategyDecorator. For example, ObjectStrategy is built as a subclass of this type.

Miscellaneous Types

The class LimitedTestSuite is used in testing to "throttle" the tests. It is a kind of test suite that accumulates test data up to a certain point, and then becomes "full". Its addTest method throws a TestSuiteFullException when a test is added to a full test suite.

The class ConstructorFailed is used to track errors that happen during test suite construction. These typically result from a constructor that is implemented incorrectly or doesn't satisfy its specification. When called during construction of the test suite, i.e., when the failure is part of providing test data, then the problem is recorded as an instance of this class. Such a test, when run, simply reports the problem it stores.

The abstract class IteratorAbstractAdapter can be used to adapt an iterator to the indefinite iterator protocol. This is an abstract class because iterators do not provide a clone() method.

The class IndefiniteIteratorUtilities has various method that are used in various JUnit test classes in this directory for testing the strategies. The class CharStrategyTypeTest and the classes such as ShortStrategyTypeTest use these classes in their testing of the strategies.

The class TracingTestSuite is another subclass of TestSuite. It is primarily intended for debugging.

Coding and the Makefiles

The main problem of coding in this package is how to avoid duplication between value types, for example between ShortIterator and LongIterator. The way this is done is by coding these types once, and using a sed script to make the different versions of a type. For example, ShortIterator and LongIterator, as well as several other types are generated by the file _ValueType_Iterator.java-generic using the script _ValueType_.sh. Fragments of code that must be different in each type are defined using one of the strings in the sed script. Thus, it is important, when making changes to these types, to change the corresponding .java-generic file, instead of the generated .java files. The Makefile is designed to make the generated files read-only to prevent editing the wrong files.

With the Makefile, you can use make generate to generate the files from the scripts. See the targets in the makefile and the definition of the VALUETYPEGENERICS macro for all of the generics.

Note, however that the types named, ...Strategy and ...BigStrategy are not generated from a single file, but rather handcrafted for each type. For example ShortStrategy and LongStrategy, are written in this way.

The source code for this package uses the GNU Lesser General Public License, since it is part of the JML runtime libraries.

Acknowledgments

These types were originally designed by Gary T. Leavens. David Cok helped by running ESC/Java 2 on the types and prompting corrections.

At Iowa State, the development of JML was partially funded by the (US) National Science Foundation under grants CCR-9503168, CCR-9803843, CCR-0097907, and CCR-0113181.


JML

JML is Copyright (C) 1998-2002 by Iowa State University and is distributed under the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This release depends on code from the MultiJava project and is based in part on the Kopi project Copyright (C) 1990-99 DMS Decision Management Systems Ges.m.b.H.