ABLE 2.0.0 07/02/2003 10:25:01

com.ibm.able
Class AbleEvent

java.lang.Object
  |
  +--java.util.EventObject
        |
        +--com.ibm.able.AbleEvent
All Implemented Interfaces:
java.io.Serializable

public class AbleEvent
extends java.util.EventObject

The AbleEvent class defines the event object used for notification and for invoking methods called actions on other AbleBeans. Events can be constructed for registered listeners to handle synchronously on the caller's thread or asynchronously on the AbleEventQueue thread.

AbleEvent objects contain:

The following event types are provided:

  1. ACTION
  2. DATACHANGED
  3. EOF
  4. TRANSACTION
  5. CLOSED

While AbleEvent objects are immutable, an argument object can be manipulated by the user. If this is undesirable, the user must clone() the argument object before constructing an AbleEvent object. All event attributes and the argument object (if used) must be specified when the event is constructed. There is no provision for setting these items after an AbleEvent is constructed.

Note that for action events (those events that have an action string specified), the "action" is taken to be the name of a method on the target AbleEventListener object, and the argument object is passed to that method as the single argument.

See Also:
AbleEventListener, Serialized Form

Field Summary
protected  java.lang.String action
          The action is either null or it contains the name of a method to call on an AbleEventListener.
static int ACTION
          An ACTION event is used to invoke a method on the genSource object, passing argObject as the single argument.
protected  java.lang.Object argObject
          The argObject is either null or it contains an arbitrary object that makes sense to the AbleEventListener.
protected  boolean asynchronous
          The asynchronous flag indicates the type of event processing desired; true means to process on AbleEventQueue thread rather than on the caller's thread.
static int CLOSED
          A CLOSED event is used to notify listeners that the genSource object, typically an AbleDataSource or AbleDataSink, has closed and is no longer processing data.
static int DATACHANGED
          A DATACHANGED event is used to notify listeners that the genSource object content has changed.
static int EOF
          An EOF event notifies listeners that the genSource object, typically an AbleDataSource has reached an end-of-file condition.
protected  java.lang.Object genSource
          The genSource object is a nontransient version of the source generating the event.
protected  int id
          The id is the type of AbleEvent.
protected  java.lang.String replyAction
          The replyAction is either null or it contains the name of a method to call on the replyTo: AbleEventListener(s).
protected  java.lang.Object replyTo
          The replyTo object is either null or it contains a reference to one or more AbleEventListeners who are to be sent a reply event.
static int TRANSACTION
          A TRANSACTION event indicates the event includes a replyTo object.
protected  java.lang.String transactionId
          The transactionId may be null or contain a String identifier for the transaction specified by this event.
 
Fields inherited from class java.util.EventObject
source
 
Constructor Summary
AbleEvent(java.lang.Object theSource)
          Construct an asynchronous DATACHANGED event for a given object.
AbleEvent(java.lang.Object theSource, java.lang.Object theArgObject)
          Construct an asynchronous DATACHANGED event for a given object and argument.
AbleEvent(java.lang.Object theSource, java.lang.Object theArgObject, int theId)
          Construct an asynchronous event of a specific type for a given object and argument.
AbleEvent(java.lang.Object theSource, java.lang.Object theArgObject, int theId, boolean async)
          Construct an event of a specific type for a given object, argument, and define whether it is to be run synchronously or asynchronously.
AbleEvent(java.lang.Object theSource, java.lang.Object theArgObject, java.lang.String theAction)
          Construct an asynchronous ACTION event for a given object, argument, and define whether it is to be run synchronously or asynchronously.
AbleEvent(java.lang.Object theSource, java.lang.Object theArgObject, java.lang.String theAction, boolean async)
          Construct an ACTION event for a given object and argument.
AbleEvent(java.lang.Object theSource, java.lang.Object theArgObject, java.lang.String theAction, boolean async, java.lang.Object theReplyTo, java.lang.String theReplyAction, java.lang.String theTransactionId)
          Construct a TRANSACTION event.
 
Method Summary
static java.lang.String Copyright()
          Determine the copyright of this class.
 java.lang.String getAction()
          Returns the event's action string, the name of a method in the argument object.
 java.lang.Object getArgObject()
          Returns the event's argument object.
 java.lang.Object getGenSource()
          Returns the event's generating source.
 int getId()
          Returns the event id.
 java.lang.String getReplyAction()
          Returns the event's replyAction value.
 java.lang.Object getReplyTo()
          Returns the event's replyTo object.
 java.lang.String getTransactionId()
          Returns the event's transactionId value, used by the replyTo object to identify the transaction.
 boolean isAsynchronous()
          Indicates true if the event should be handled asynchronously or false if synchronous,
 
Methods inherited from class java.util.EventObject
getSource, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ACTION

public static final int ACTION
An ACTION event is used to invoke a method on the genSource object, passing argObject as the single argument.

DATACHANGED

public static final int DATACHANGED
A DATACHANGED event is used to notify listeners that the genSource object content has changed. Often this means that an AbleBean's inputBuffer or outputBuffer has been updated.

This is the default event type.


EOF

public static final int EOF
An EOF event notifies listeners that the genSource object, typically an AbleDataSource has reached an end-of-file condition.

TRANSACTION

public static final int TRANSACTION
A TRANSACTION event indicates the event includes a replyTo object.

CLOSED

public static final int CLOSED
A CLOSED event is used to notify listeners that the genSource object, typically an AbleDataSource or AbleDataSink, has closed and is no longer processing data.

action

protected java.lang.String action
The action is either null or it contains the name of a method to call on an AbleEventListener. If a method name is specified, the argObject is passed to the method as the single argument. (Note that the argObject itself may be null.)

id

protected final int id
The id is the type of AbleEvent. Default value is DATACHANGED.

asynchronous

protected boolean asynchronous
The asynchronous flag indicates the type of event processing desired; true means to process on AbleEventQueue thread rather than on the caller's thread.

argObject

protected java.lang.Object argObject
The argObject is either null or it contains an arbitrary object that makes sense to the AbleEventListener. If the action and argObject parameters are specified, the method named by action is passed to the argObject as the single argument.

genSource

protected final java.lang.Object genSource
The genSource object is a nontransient version of the source generating the event. For a distributed agent application, this would probably be an interface.

replyTo

protected java.lang.Object replyTo
The replyTo object is either null or it contains a reference to one or more AbleEventListeners who are to be sent a reply event.

replyAction

protected java.lang.String replyAction
The replyAction is either null or it contains the name of a method to call on the replyTo: AbleEventListener(s). If a method name is specified, the argObject is passed to the method as the single argument. (Note that the argObject itself may be null.)

transactionId

protected java.lang.String transactionId
The transactionId may be null or contain a String identifier for the transaction specified by this event.
Constructor Detail

AbleEvent

public AbleEvent(java.lang.Object theSource)
Construct an asynchronous DATACHANGED event for a given object.
Parameters:
theSource - The object that is creating and using this event.

AbleEvent

public AbleEvent(java.lang.Object theSource,
                 java.lang.Object theArgObject)
Construct an asynchronous DATACHANGED event for a given object and argument.
Parameters:
theSource - The object that is creating and using this event.
theArgObject - An object to be passed to the event listener. This parameter is optional and therefore may be specified as null.

AbleEvent

public AbleEvent(java.lang.Object theSource,
                 java.lang.Object theArgObject,
                 int theId)
Construct an asynchronous event of a specific type for a given object and argument.
Parameters:
theSource - The Able object that is creating and using this event.
theArgObject - An object to be passed to the event listener. This parameter is optional and therefore may be specified as null.
theId - An event type.

AbleEvent

public AbleEvent(java.lang.Object theSource,
                 java.lang.Object theArgObject,
                 int theId,
                 boolean async)
Construct an event of a specific type for a given object, argument, and define whether it is to be run synchronously or asynchronously.
Parameters:
theSource - The Able object that is creating and using this event.
theArgObject - An object to be passed to the event listener. This parameter is optional and therefore may be specified as null.
theId - An event type.
async - true indicates the event should be processed asynchronously, false synchronously.

AbleEvent

public AbleEvent(java.lang.Object theSource,
                 java.lang.Object theArgObject,
                 java.lang.String theAction)
Construct an asynchronous ACTION event for a given object, argument, and define whether it is to be run synchronously or asynchronously.
Parameters:
theSource - The Able object that is creating and using this event.
theArgObject - An object to be passed to the event listener. This parameter is optional and therefore may be specified as null.
theAction - A string containing the name of a method to invoke on the event listener. The method will be passed the argObject.

AbleEvent

public AbleEvent(java.lang.Object theSource,
                 java.lang.Object theArgObject,
                 java.lang.String theAction,
                 boolean async)
Construct an ACTION event for a given object and argument.
Parameters:
theSource - The Able object that is creating and using this event.
theArgObject - An object to be passed to the event listener. This parameter is optional and therefore may be specified as null.
theAction - A string containing the name of a method to invoke on the event listener. The method will be passed the argObject.
async - true indicates the event should be processed asynchronously, false synchronously.

AbleEvent

public AbleEvent(java.lang.Object theSource,
                 java.lang.Object theArgObject,
                 java.lang.String theAction,
                 boolean async,
                 java.lang.Object theReplyTo,
                 java.lang.String theReplyAction,
                 java.lang.String theTransactionId)
Construct a TRANSACTION event. This event specifies an argument and an action for the AbleEventListener to process. It also contains one or more AbleEventListener to replyTo and the action to be used in the reply event. This constructor allows specification of a transactionId field which is copied to the reply event.
Parameters:
theSource - The Able object that is creating and using this event.
theArgObject - An object to be passed to the event listener. This parameter is optional and therefore may be specified as null.
theAction - A string containing the name of a method to invoke on the event listener. The method will be passed the argObject.
async - true indicates the event should be processed asynchronously, false synchronously.
theReplyTo - Where a reply event should be sent - could be null (no reply), a single AbleEventListener, or an Object[] or Vector holding a list of AbleEventListeners.

theReplyAction - The name of the action in the reply event, a method on the replyTo object.
theTransactionId - An identifier for this transaction to be passed back in the reply event.
Method Detail

getArgObject

public java.lang.Object getArgObject()
Returns the event's argument object.

Note that it is not guaranteed that the argument is immutable, unless the argument is restricted by the caller to clonable.

Returns:
The event's argument object, or null if no argument object has been specified.

getId

public int getId()
Returns the event id.

getAction

public java.lang.String getAction()
Returns the event's action string, the name of a method in the argument object.
Returns:
the event's action string or null if no action string has been specified.

isAsynchronous

public boolean isAsynchronous()
Indicates true if the event should be handled asynchronously or false if synchronous,

getGenSource

public java.lang.Object getGenSource()
Returns the event's generating source.
Returns:
An object or interface representing the object that generated the event. NOTE that in a distributed application, this must be cast to an appropriate interface!

getReplyTo

public java.lang.Object getReplyTo()
Returns the event's replyTo object.
Returns:
Where a reply event should be sent - could be null (no reply), a single AbleEventListener, or an Object[] or Vector holding a list of AbleEventListeners.

getReplyAction

public java.lang.String getReplyAction()
Returns the event's replyAction value.
Returns:
The name of the action in the reply event, a method on the replyTo object; can be null.

getTransactionId

public java.lang.String getTransactionId()
Returns the event's transactionId value, used by the replyTo object to identify the transaction.
Returns:
The transactionId, which can be null or an arbitrarily-assigned but presumably unique identifier.

Copyright

public static java.lang.String Copyright()
Determine the copyright of this class.
Returns:
A String containing this class's copyright statement.

ABLE 2.0.0 07/02/2003 10:25:01

(C) Copyright IBM Corporation 1999, 2003