y.module
Class YModule

java.lang.Object
  y.module.YModule

Direct Known Subclasses:

IOHandlerModule, LayoutModule

public abstract class YModule
extends java.lang.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(java.lang.String name)
Initializes a new YModule instance with the given name.

YModule(java.lang.String moduleName, java.lang.String authorName, java.lang.String description)
Deprecated. Use YModule(String) instead. Proper module description should take place in the API documentation.

Method Summary

void	addModuleListener(ModuleListener listener) Adds the given module listener to receive module events during the execution of this module.
protected OptionHandler	createOptionHandler() Creates an option handler for this class.
protected java.lang.Thread	createThread(java.lang.Runnable forRunnable) Creates a new thread that is named after this module and sets the thread priority to Thread.MIN_PRIORITY.
protected void	dispose() Disposition code performed after the execution of mainrun() was finished.
protected boolean	exceptionHappened(java.lang.Throwable throwable) Callback method used by run() to indicate exceptional behavior.
protected void	fitGraph2DView() Fits the contents inside the current view if the current view is of type Graph2DView.
java.lang.String	getAuthor() Deprecated. Proper module description should take place in the API documentation.
java.lang.String	getDescription() Deprecated. Proper module description should take place in the API documentation.
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.
ModuleListener[]	getModuleListeners() Returns all the module listeners that have been added to this module.
java.lang.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().
protected void	initGuiFactory(OptionHandler optionHandler) Sets the GuiFactory instance responsible for localizing the given option handler's user interface.
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 the given module listener so that it no longer receives module events from this module.
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(java.lang.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(java.lang.String name)

Initializes a new YModule instance with the given name.

The module's author and description properties will be set to empty strings.

Parameters:

name - the module's name.

YModule

public YModule(java.lang.String moduleName,
               java.lang.String authorName,
               java.lang.String description)

Deprecated. Use YModule(String) instead. Proper module description should take place in the API documentation.

Initializes a new YModule instance with the given name, author and description.

Method Detail

getModuleName

public java.lang.String getModuleName()

Returns the name of this module.

setModuleName

public void setModuleName(java.lang.String name)

Sets name of this module.

getAuthor

public java.lang.String getAuthor()

Deprecated. Proper module description should take place in the API documentation.

Returns the name of this module's author

getDescription

public java.lang.String getDescription()

Deprecated. Proper module description should take place in the API documentation.

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)

Adds the given module listener to receive module events during the execution of this module.

Parameters:

listener - The listener to register. May not be null.

See Also:

ModuleListener

removeModuleListener

public void removeModuleListener(ModuleListener listener)

Removes the given module listener so that it no longer receives module events from this module.

Parameters:

listener - The listener to remove.

See Also:

ModuleListener

getModuleListeners

public ModuleListener[] getModuleListeners()

Returns all the module listeners that have been added to this module.

See Also:

addModuleListener(ModuleListener), removeModuleListener(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 contents inside the current view if the current view is of type Graph2DView.

See Also:

Graph2DView.fitContent()

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.

initGuiFactory

protected void initGuiFactory(OptionHandler optionHandler)

Sets the GuiFactory instance responsible for localizing the given option handler's user interface.

The default implementation of this method looks for the first resource bundle that corresponds to this module's class or one of the module's super classes.

Parameters:

optionHandler - the option handler whose user interface will be localized.

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 java.lang.Thread createThread(java.lang.Runnable forRunnable)

Creates a new thread that is named after this module and sets the thread priority to Thread.MIN_PRIORITY.

Called from startAsThread(y.view.Graph2D).

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(java.lang.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()