y.module
Class YModule

java.lang.Object
  y.module.YModule

Direct Known Subclasses:

IOHandlerModule, LabelingModule, LayoutModule

public abstract class YModule
extends Object

This abstract class provides a skeleton for algorithms on graphs. It defines an interface for the caller of the algorithm and provides a mechanism for parameter passing via OptionHandlers.

Tips how to write your own module:
To write your own graph algorithm you have to overwrite the following methods:

• init()
• mainrun()
• dispose()

To specify your own options/parameters the createOptionHandler() has to be overridden.

Field Summary

static short	FAILED Exit state constant.
protected ModuleListenerSupport	moduleListenerSupport The ModuleListenerSupport associated with this YModule.
static short	PRECONDITION_VIOLATED Exit state constant.
static short	SUCCESS Exit state constant.

Constructor Summary

YModule(String moduleName, String authorName, String description)
Instantiates a YModule.

Method Summary

void	addModuleListener(ModuleListener listener) Registers ModuleListener to receive events during the execution of this module.
protected OptionHandler	createOptionHandler() Creates an option handler for this class.
protected Thread	createThread(Runnable forRunnable) Factory Method for startAsThread(y.view.Graph2D).
protected void	dispose() Disposition code performed after the execution of mainrun() was finished.
protected boolean	exceptionHappened(Throwable throwable) Callback method used by run() to indicate exceptional behavior.
protected void	fitGraph2DView() Fits the content if the current view is of type Graph2DView.
String	getAuthor() Returns the name of this module's author
String	getDescription() Returns a short description of what this module does
short	getExitStatus() Yields the exit status.
protected Graph2D	getGraph2D() Grants access to the graph2D acted upon.
protected Graph2DView	getGraph2DView() Grants access to the current view this module acts upon.
String	getModuleName() Returns the name of this module.
OptionHandler	getOptionHandler() Returns the option handler of this module.
protected Timer	getTimer() Grants access to a timer object associated with this module.
protected View	getView() Grants access to the current view this module acts upon.
protected void	init() Initialization code performed before calling mainrun().
boolean	isAbortable() Returns whether or not this module can be aborted.
boolean	isBackupRealizersEnabled() Returns whether or not this module will ask the given graph to backup all its realizers before it starts acting upon the graph.
protected abstract void	mainrun() Main execution code to be implemented by any subclassing module.
void	removeModuleListener(ModuleListener listener) Removes ModuleListener from the list of listeners.
protected void	run() Calls the canonical module execution sequence: init() - mainrun() - dispose().
void	setBackupRealizersEnabled(boolean enabled) Sets whether or not this module will ask the given graph to backup all its realizers before it starts acting upon the graph.
protected void	setExitStatus(short status) Sets the exit status of this module.
void	setGraph2D(Graph2D graph) Sets the graph being acted upon.
void	setModuleName(String name) Sets name of this module.
void	setOptionHandler(OptionHandler oh) Sets the option handler for this method.
void	start(Graph2D graph) Main module startup routine.
void	startAsThread(Graph2D graph) Starts this module as a thread.

Methods inherited from class java.lang.Object

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

Field Detail

SUCCESS

public static final short SUCCESS

Exit state constant. Signals successful termination of this module/

See Also:

Constant Field Values

FAILED

public static final short FAILED

Exit state constant. Signals a failure of this module.

See Also:

Constant Field Values

PRECONDITION_VIOLATED

public static final short PRECONDITION_VIOLATED

Exit state constant. Signals that a precondition for this module was not met.

See Also:

Constant Field Values

moduleListenerSupport

protected final ModuleListenerSupport moduleListenerSupport

The ModuleListenerSupport associated with this YModule.

Constructor Detail

YModule

public YModule(String moduleName,
               String authorName,
               String description)

Instantiates a YModule. Specify name, author and a short description for this module.

Method Detail

getModuleName

public String getModuleName()

Returns the name of this module.

setModuleName

public void setModuleName(String name)

Sets name of this module.

getAuthor

public String getAuthor()

Returns the name of this module's author

getDescription

public String getDescription()

Returns a short description of what this module does

getTimer

protected Timer getTimer()

Grants access to a timer object associated with this module. Note that the timer does not start automatically when the module is launched.

setGraph2D

public void setGraph2D(Graph2D graph)

Sets the graph being acted upon.

getGraph2D

protected Graph2D getGraph2D()

Grants access to the graph2D acted upon.

addModuleListener

public void addModuleListener(ModuleListener listener)

Registers ModuleListener to receive events during the execution of this module.

Parameters:

listener - The listener to register.

See Also:

ModuleListener

removeModuleListener

public void removeModuleListener(ModuleListener listener)

Removes ModuleListener from the list of listeners.

Parameters:

listener - The listener to remove.

See Also:

ModuleListener

getView

protected View getView()

Grants access to the current view this module acts upon.

getGraph2DView

protected Graph2DView getGraph2DView()

Grants access to the current view this module acts upon. Returns null if the current view is not of type Graph2DView.

fitGraph2DView

protected void fitGraph2DView()

Fits the content if the current view is of type Graph2DView.

getOptionHandler

public OptionHandler getOptionHandler()

Returns the option handler of this module. Module writers can provide an option handler by overwriting createOptionHandler(). If this module does not provide an option handler null is returned.

createOptionHandler

protected OptionHandler createOptionHandler()

Creates an option handler for this class. Module writers should override this method to provide an appropriate option handler.

Returns:

The option handler for this module, null by default.

setOptionHandler

public void setOptionHandler(OptionHandler oh)

Sets the option handler for this method. One should not use this method with modules that provide their own option handlers, since they depend on a specific option handler configuration.

start

public void start(Graph2D graph)

Main module startup routine. Modules should be always launched by this method.

Parameters:

graph - the graph being acted upon

startAsThread

public void startAsThread(Graph2D graph)

Starts this module as a thread. Modules can specify if they want to be launched in a Thread.
It is suggested to implement your own threading logic because there is no good way to determine when or how the module finished and how the used Thread should be configured.

Parameters:

graph - the graph being acted upon.

createThread

protected Thread createThread(Runnable forRunnable)

Factory Method for startAsThread(y.view.Graph2D). This method creates a new Thread and sets its Priority to Thread.MIN_PRIORITY

isAbortable

public boolean isAbortable()

Returns whether or not this module can be aborted. A Module that can be aborted handles InterruptedExceptions gracefully. By default modules cannot be aborted.

getExitStatus

public short getExitStatus()

Yields the exit status. Note that in general this makes sense after the algorithm has run, only.

Returns:

One of the values SUCCESS, FAILED, or PRECONDITION_VIOLATED

setExitStatus

protected void setExitStatus(short status)

Sets the exit status of this module. This method should be invoked when the algorithm has finished.

Parameters:

status - One of the values SUCCESS, FAILED AND PRECONDITION_VIOLATED.

init

protected void init()

Initialization code performed before calling mainrun().

mainrun

protected abstract void mainrun()

Main execution code to be implemented by any subclassing module.

dispose

protected void dispose()

Disposition code performed after the execution of mainrun() was finished.

run

protected void run()

Calls the canonical module execution sequence: init() - mainrun() - dispose().

exceptionHappened

protected boolean exceptionHappened(Throwable throwable)

Callback method used by run() to indicate exceptional behavior. This method will notify registered listeners via ModuleListenerSupport.fireExceptionThrown(Throwable) and returns true iff this instance has listeners. Subclasses may override this method to change the behavior according to their needs.

Parameters:

throwable - the exception

Returns:

whether the throwable should be rethrown by the caller.

isBackupRealizersEnabled

public boolean isBackupRealizersEnabled()

Returns whether or not this module will ask the given graph to backup all its realizers before it starts acting upon the graph.

See Also:

setBackupRealizersEnabled(boolean)

setBackupRealizersEnabled

public void setBackupRealizersEnabled(boolean enabled)

Sets whether or not this module will ask the given graph to backup all its realizers before it starts acting upon the graph. By default, this feature is enabled.

See Also:

Graph2D.backupRealizers()