org.jwalk
Class Channels

java.lang.Object
  org.jwalk.Channels

public class Channels
extends java.lang.Object

Channels is the API through which client programs set up two-way communication channels with a JWalker. The interaction pattern follows Java's event model. Client programs must register a QuestionListener and a ReportListener with this API, to handle QuestionEvents and ReportEvents, respectively. If no such listeners are registered, then a default Console object is used, which uses standard input and output for communication.

A QuestionListener is any object satisfying the QuestionListener interface, which implements the respond(QuestionEvent) method. Typically, such a method will display a question in the format desired by the client program and accept a response from the user, returning this as an enumerated Answer value. See the QuestionListener interface for more details.

A ReportListener is any object satisfying the ReportListener interface, which implements the publish(ReportEvent) method. Typically, such a method will display the contents of a report in the format desired by the client program. See the ReportListener interface for more details.

QuestionEvent and ReportEvent are two kinds of event that respectively wrap up a Question and a Report. Whenever a JWalker wishes to communicate, it dispatches one or other of these events to the appropriate listener. The listener will access the Question or Report using the API of QuestionEvent or ReportEvent, respectively.

Version:

1.1

Author:

Anthony Simons

Constructor Summary

Channels()
Creates the default Channels.

Method Summary

void	addQuestionListener(QuestionListener listener) Sets the handler for QuestionEvents to the new listener.
void	addReportListener(ReportListener listener) Sets the handler for ReportEvents to the new listener.
Answer	dispatch(Question question) Dispatches a Question from a JWalker via these Channels.
void	dispatch(Report report) Dispatches a Report from a JWalker via these Channels.
boolean	interrupted() Reports whether the current operating status is interrupted.
boolean	nominal() Reports whether the current operating status is nominal.
boolean	outOfMemory() Reports whether the JWalker engine ran out of memory during testing.
void	removeQuestionListener(QuestionListener listener) Unregisters the handler for QuestionEvents.
void	removeReportListener(ReportListener listener) Unregisters the handler for ReportEvents.
void	setNominal() Resets the operating status to nominal.
void	setOutOfMemory() Sets the operating status to Out of Memory.
void	setUserAborted() Sets the operating status to User Aborted.
boolean	userAborted() Reports whether the user aborted the current test cycle voluntarily.

Methods inherited from class java.lang.Object

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

Constructor Detail

Channels

public Channels()

Creates the default Channels. Both the QuestionListener and the ReportListener are bound to a default Console instance. This is an object that interacts with the user on the command line.

Method Detail

addQuestionListener

public void addQuestionListener(QuestionListener listener)

Sets the handler for QuestionEvents to the new listener. Client programs use this method to register the object they wish to intercept and handle QuestionEvents generated by a JWalker. The added listener replaces the default Console.

Parameters:

listener - the QuestionListener to register.

addReportListener

public void addReportListener(ReportListener listener)

Sets the handler for ReportEvents to the new listener. Client programs use this method to register the object they wish to intercept and handle ReportEvents generated by a JWalker. The added listener replaces the default Console.

Parameters:

listener - the QuestionListener to register.

removeQuestionListener

public void removeQuestionListener(QuestionListener listener)

Unregisters the handler for QuestionEvents. Removes the listener, if it is the current QuestionListener, and replaces it with the default Console.

Parameters:

listener - the QuestionListener to unregister.

removeReportListener

public void removeReportListener(ReportListener listener)

Unregisters the handler for ReportEvents. Removes the listener, if it is the current ReportListener, and replaces it with the default Console.

Parameters:

listener - the ReportListener to unregister.

dispatch

public void dispatch(Report report)

Dispatches a Report from a JWalker via these Channels. Called by a JWalker each time it wishes to submit a Report to the client program. The current ReportListener will be asked to publish a ReportEvent containing the JWalker as its source and the Report as its content.

Parameters:

report - the Report being dispatched.

dispatch

public Answer dispatch(Question question)

Dispatches a Question from a JWalker via these Channels. Called by a JWalker each time it wishes to ask a question of the client program. The current QuestionListener will be asked to respond to a QuestionEvent containing the JWalker as its source and the Question as its content. An enumerated Answer from: {YES, NO, QUIT} is expected in reply.

Parameters:

question - the Question being asked.

Returns:

an Answer from: {YES, NO, QUIT}.

nominal

public boolean nominal()

Reports whether the current operating status is nominal. This value is checked inside the JWalker engine's main loop, and if true, testing may continue. If false, testing must be interrupted immediately.

Returns:

true, if the operating status is nominal.

interrupted

public boolean interrupted()

Reports whether the current operating status is interrupted. This is true, if either the out of memory, or user abort conditions were set.

Returns:

true, if the operating status is interrupted.

outOfMemory

public boolean outOfMemory()

Reports whether the JWalker engine ran out of memory during testing. This value is checked after an interruption to testing, when composing the Notification to report an out of memory error.

Returns:

true, if testing was interrupted due to memory exhaustion.

userAborted

public boolean userAborted()

Reports whether the user aborted the current test cycle voluntarily. This value is checked after an interruption to testing, when composing the Notification to report that the user aborted the cycle.

Returns:

true, if testing was interrupted due to a user abort.

setNominal

public void setNominal()

Resets the operating status to nominal. Clears any fault that may have been detected in a previous cycle.

setOutOfMemory

public void setOutOfMemory()

Sets the operating status to Out of Memory. This is called when a test cycle exhausts the available Java heap memory.

setUserAborted

public void setUserAborted()

Sets the operating status to User Aborted. This is called when the user decides to abort the current test cycle.