org.jicarilla.framework
Class AbstractAsyncEnabled

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

All Implemented Interfaces:

Active, AsyncEnabled

public abstract class AbstractAsyncEnabled

extends AbstractExecutable

implements AsyncEnabled

A basic AsyncEnabled implementation that inherits actual thread handling to the AbstractActive class. Any calls to handle(Invocation) are queued, with the work() method (implementing the 'interface' exposed by AbstractExecutable) dequeuing an invocation and sending it to doHandle(Invocation).

To create concrete AsyncEnabled classes based on this abstract class, there's usually little you will want or need to do. Likely entry points for customization include the getImmediateResult(Invocation) method (which is called from handle()), the doHandle() method (if you wish to redirect the handling of the asynchronous calls somewhere else) and the doHandleException(Invocation) method (if you wish to handle exceptions thrown from applying Invocations gracefully).

Version:

$Id: AbstractAsyncEnabled.java,v 1.3 2003/11/17 21:10:23 lsimons Exp $

Author:

Leo Simons

Nested Class Summary

Nested classes inherited from class org.jicarilla.framework.AbstractExecutable

AbstractExecutable.Worker

Field Summary

protected Channel

m_incoming The recipient of incoming calls.

Fields inherited from class org.jicarilla.framework.AbstractExecutable

m_executor, m_listener, m_worker

Fields inherited from class org.jicarilla.framework.AbstractActive

m_running, m_stopped

Constructor Summary

AbstractAsyncEnabled(Executor executor)
Create an instance using a custom executor.

AbstractAsyncEnabled(Executor executor, ExceptionListener listener)
Create an instance using a custom executor and an exception listener.

Method Summary

protected void	doHandle(Invocation invocation) This method will be called from the worker thread and you should implement whatever behaviour neccessary to complete the invocation.
protected void	doHandleException(Invocation invocation) This method is called by the default doHandle() implementation if an exception occurs making the invocation.
protected java.lang.Object	getImmediateResult(Invocation invocation) Override this to specify what the handle() method should return after enqueuing an invocation.
java.lang.Object	handle(Invocation invocation) Enqueue the invocation on the asynchronous call stack.
protected void	work() Implements the superclass method by dequeuing an invocation (possibly blocking until one is added to the queue), then feeding it to the doHandle(Invocation) method.

Methods inherited from class org.jicarilla.framework.AbstractExecutable

doDispose, doInitialize

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_incoming

protected final Channel m_incoming

The recipient of incoming calls.

Constructor Detail

AbstractAsyncEnabled

public AbstractAsyncEnabled(Executor executor)

Create an instance using a custom executor.

Parameters:

executor - the Executor that will be used in AbstractExecutable to do the work

AbstractAsyncEnabled

public AbstractAsyncEnabled(Executor executor,
                            ExceptionListener listener)

Create an instance using a custom executor and an exception listener.

Parameters:

executor - the Executor that will be used in AbstractExecutable to do the work

listener - the listener that will be notified of any abnomral problems occuring during the calls to work(). Note that any exceptions resulting from applying an Invocation are not sent to this listener.

Method Detail

handle

public java.lang.Object handle(Invocation invocation)
                        throws java.lang.InterruptedException

Enqueue the invocation on the asynchronous call stack.

Specified by:

handle in interface AsyncEnabled

Parameters:

invocation - the invocation to enqueue

Returns:

whatever getImmediateResult(Invocation) returns

Throws:

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

getImmediateResult

protected java.lang.Object getImmediateResult(Invocation invocation)

Override this to specify what the handle() method should return after enqueuing an invocation. The default implementation simply returns null.

Parameters:

invocation - the invocation that has just been enqueued

Returns:

null, but subclasses may change that behaviour

doHandle

protected void doHandle(Invocation invocation)

This method will be called from the worker thread and you should implement whatever behaviour neccessary to complete the invocation. The default implementation simply runs the invocation.

Parameters:

invocation - the invocation that has just been dequeued and should now be applied or redirected somewhere else

doHandleException

protected void doHandleException(Invocation invocation)

This method is called by the default doHandle() implementation if an exception occurs making the invocation. The default implementation silently ignores the problem, which is arguably a bad idea, but acceptable if subclasses never throw exceptions.

Parameters:

invocation - the invocation that was applied and caused an exception

work

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

Implements the superclass method by dequeuing an invocation (possibly blocking until one is added to the queue), then feeding it to the doHandle(Invocation) method.

Overrides:

work in class AbstractExecutable

Throws:

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

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