Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 sender object (the source) itself.
- A set of attributes which define the event, including an event name, and an optional action String that can be used for routing purposes. When an event object is instantiated, a creation timestamp and a unique ID are added to the event as well.

- An optional argument object, which can be an instance of any object class as required by the application.

The following event types are provided:

1. `ACTION`
2. `DATACHANGED`
3. `EOF`
4. `TRANSACTION`
5. `CLOSED`
6. `DEBUG`

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` | `COMMONBASEEVENT` A COMMONBASEEVENT event is used to notify listeners that the `genSource` has populated the `argObject` value with an object that implements the CommonBaseEvent interface.
`static int` | `DATACHANGED` A DATACHANGED event is used to notify listeners that the `genSource` object content has changed.
`static int` | `DEBUG` A DEBUG event is used to notify listeners that the `genSource` object, typically an `or AbleAgent`, has reached a significant state during processing and allows a debugger to suspend the bean/agent and view state information.
`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
`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.

  See Also:
    Constant Field Values

### 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.

  See Also:
    Constant Field Values

### 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.

  See Also:
    Constant Field Values

### TRANSACTION

    public static final int TRANSACTION

  A TRANSACTION event indicates the event includes a `replyTo` object.

  See Also:
    Constant Field Values

### 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.

  See Also:
    Constant Field Values

### DEBUG

    public static final int DEBUG

  A DEBUG event is used to notify listeners that the `genSource` object, typically an `or AbleAgent`, has reached a significant state during processing and allows a debugger to suspend the bean/agent and view state information.

  See Also:
    Constant Field Values

### COMMONBASEEVENT

    public static final int COMMONBASEEVENT

  A COMMONBASEEVENT event is used to notify listeners that the `genSource` has populated the `argObject` value with an object that implements the CommonBaseEvent interface.

  See Also:
    Constant Field Values

### 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.

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

(C) Copyright IBM Corporation 1999, 2005