org.jwalk
Class JWalker

java.lang.Object
  org.jwalk.JWalker

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

ClassInspector

public class JWalker
extends java.lang.Object
implements java.lang.Runnable

JWalker is the top-level API class through which third-party software communicates with the different lazy systematic unit testing algorithms for unit testing Java classes. JWalker contains two other component APIs: the Settings API allows testers to set up the desired test parameters, such as the test class, the test strategy to follow and the maximum depth of exploration; while the Channels API allows the tester to register third-party objects with JWalker, to which all test results and queries will be dispatched.

A test session begins by creating an instance of JWalker, accessing the Channels API to set up communication channels, then accessing the Settings API to set up the test parameters. These channels and settings may persist over several runs of the JWalker, unless modified by the tester. To start testing, invoke this JWalker's execute() method. To start testing in the background, create a new Thread wrapping this JWalker and invoke the Thread's start() method. That's all there is to it. Consult the Settings and Channels APIs for further details.

Version:

1.1

Author:

Anthony Simons

Field Summary

protected Channels	channels The Channels API supports registering listeners.
protected Settings	settings The Settings API supports supplying test parameters.

Constructor Summary

	JWalker() Creates a JWalker, ready to use.
protected	JWalker(Settings settings, Channels channels) Secretly initialises the settings and channels.

Method Summary

void	execute() Executes this JWalker as a single-threaded application.
Channels	getChannels() Returns the Channels API, to enable setting call-back channels.
Settings	getSettings() Returns the Settings API, to enable setting test parameters.
java.lang.Class<?>	getTestClass() Returns the test class.
boolean	outOfMemory() Reports whether Java ran out of heap memory during the execution of this JWalker engine.
void	run() Executes this JWalker inside a recently-started worker Thread.
boolean	userAborted() Reports whether the user aborted the execution of this JWalker engine.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

settings

protected Settings settings

The Settings API supports supplying test parameters. JWalker creates useful default settings, but the tester should expect to supply some information, such as the test class, test strategy and depth of path exploration.

channels

protected Channels channels

The Channels API supports registering listeners. The tester is expected to register one or more objects conforming to the two event handling interfaces: ReportListener and QuestionListener.

Constructor Detail

JWalker

public JWalker()

Creates a JWalker, ready to use. This is the constructor to use when building a JWalker. After construction, the tester may access the Settings and Channels APIs, which are initialised to suitable default objects.

JWalker

protected JWalker(Settings settings,
                  Channels channels)

Secretly initialises the settings and channels. Used by descendants of JWalker, which are passed the settings and channels.

Method Detail

getSettings

public Settings getSettings()

Returns the Settings API, to enable setting test parameters.

Returns:

the settings API.

getChannels

public Channels getChannels()

Returns the Channels API, to enable setting call-back channels.

Returns:

the channels API.

getTestClass

public java.lang.Class<?> getTestClass()

Returns the test class. Returns the test class that was set by the tester in the Settings. Provided so that all Generators may access the test class through any JWalker.

Returns:

the testClass, or null if this has not yet been set.

execute

public void execute()
             throws PermissionException,
                    GeneratorException,
                    ExecutionException

Executes this JWalker as a single-threaded application. Executes the chosen test series, as determined by the settings, and communicates all test reports and user queries back via the channels. This is the usual top-level method for invoking the JWalker test engine.

JWalker is the ancestor of classes denoting particular test strategies. It is designed according to the Strategy design pattern (see Gamma, et al., 1995). Every descendant is constructed with Settings and Channels arguments, and is then invoked using execute().

Throws:

GeneratorException - if any constructor or method argument value could not be synthesised. A CustomGenerator must be provided that is capable of synthesising values of the argument type.

ExecutionException - if any constructor or method could not be invoked, for reasons of visibility, security or bad arguments, or if it is detected that a constructor or method behaves randomly.

PermissionException - if the loaded test class, or any custom generator, could not be instantiated, either for reasons of security, or visibility, or because it was abstract, or an interface.

run

public void run()

Executes this JWalker inside a recently-started worker Thread. This method is provided to allow the JWalker engine to run as a background process, inside a separate worker Thread. The client application must create the Thread and set its priority, according to how time-sharing should occur between the main thread and this worker thread.

In other respects, this method behaves like the execute() method, except that it must handle the three declared exceptions, in order to be compatible with the signature for run() in the interface Runnable. Any raised exceptions are therefore wrapped inside Notifications, which are dispatched to the channels, to be unpacked later by the client application.

Specified by:

run in interface java.lang.Runnable

outOfMemory

public boolean outOfMemory()

Reports whether Java ran out of heap memory during the execution of this JWalker engine. Checks the operating status of the Channels, to see if the out of memory condition was set.

Returns:

true if Java ran out of heap memory.

userAborted

public boolean userAborted()

Reports whether the user aborted the execution of this JWalker engine. Checks the operating status of the Channels, to see if the user abort condition was set.

Returns:

true if the user aborted the current test series.