Search this API

y.module
Class YModule

java.lang.Object
  extended by 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:

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()

© Copyright 2000-2021,
yWorks GmbH.
All rights reserved.