org.jicarilla.framework
Class AbstractExecutable

java.lang.Object
  org.jicarilla.framework.AbstractActive
      org.jicarilla.framework.AbstractExecutable

All Implemented Interfaces:

Active

Direct Known Subclasses:

AbstractAsyncEnabled, Connector

public abstract class AbstractExecutable

extends AbstractActive

Provides generic support for the 'inner worker thread' coding pattern where child classes are shielded from most of the processing mechanics. Subclasses will need to implement work(), which will be called from the inner worker thread.

Exactly how often or in what kind of thread configuration the work() method can be customized by passing in a custom Executor. If none is provided, a single new thread will be created. The worker passed to this executor will never Thread.sleep(long), but it will Thread.yield() after each call to work().

Note that this class is Active, and extends from AbstractActive. As such, you should not override the AbstractActive.initialize() nor the AbstractActive.dispose() methods, but only ever override doInitialize() and/or doDispose(). When you do, make sure to call the overridden methods as well.

Version:

$Id: AbstractExecutable.java,v 1.2 2004/01/04 16:10:21 lsimons Exp $

Author:

Leo Simons

Nested Class Summary

protected class

AbstractExecutable.Worker Private helper class that will be fed to an Executor.

Field Summary

protected Executor	m_executor The executor that will execute our worker.
protected ExceptionListener	m_listener The recipient of errors thrown by work().
protected AbstractExecutable.Worker	m_worker The worker that calls work().

Fields inherited from class org.jicarilla.framework.AbstractActive

m_running, m_stopped

Constructor Summary

AbstractExecutable()
Create a new instance that uses the ThreadedExecutor.

AbstractExecutable(Executor executor)
Create a new instance that uses the provided executor.

AbstractExecutable(Executor executor, ExceptionListener listener)
Create a new instance that uses the provided executor and sends all exceptions thrown by @{link #work()} to the provided listener.

Method Summary

protected void	doDispose() Stops the worker and disposes of all state.
protected void	doInitialize() Creates a new worker and tells the executor to execute it.
protected void	work() This method is called whenever your 'executable' class should perform 'a unit' of work.

Methods inherited from class org.jicarilla.framework.AbstractActive

checkActive, dispose, initialize, isActive, isDisposed, isInitialized, lazyInitialization

Methods inherited from class java.lang.Object

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

Field Detail

m_executor

protected Executor m_executor

The executor that will execute our worker.

m_worker

protected AbstractExecutable.Worker m_worker

The worker that calls work().

m_listener

protected ExceptionListener m_listener

The recipient of errors thrown by work().

Constructor Detail

AbstractExecutable

public AbstractExecutable()

Create a new instance that uses the ThreadedExecutor.

AbstractExecutable

public AbstractExecutable(Executor executor)

Create a new instance that uses the provided executor.

Parameters:

executor - the executor to use.

AbstractExecutable

public AbstractExecutable(Executor executor,
                          ExceptionListener listener)

Create a new instance that uses the provided executor and sends all exceptions thrown by @{link #work()} to the provided listener.

Parameters:

executor - the executor to use.

listener - the listener to send exceptions to. May be null.

Method Detail

doInitialize

protected void doInitialize()
                     throws java.lang.InterruptedException,
                            java.lang.Throwable

Creates a new worker and tells the executor to execute it.

Overrides:

doInitialize in class AbstractActive

Throws:

java.lang.InterruptedException - if the current thread has been Thread.interrupt()ed

java.lang.Throwable - in case of a problem.

doDispose

protected void doDispose()

Stops the worker and disposes of all state.

Overrides:

doDispose in class AbstractActive

work

protected void work()
             throws java.lang.Throwable

This method is called whenever your 'executable' class should perform 'a unit' of work. Override it in subclasses to do some meaningful stuff. Also note that a call to Thread.yield() is made every time this method returns, so you don't generally need to call yield() yourself...unless you're doing a pretty intensive operation.

Throws:

java.lang.Throwable - if any problem occurs. The exception will be fed to any exceptionlisteners that may exist.