com.ibm.able
Class AbleObject

java.lang.Object
  com.ibm.able.AbleObject

All Implemented Interfaces:

AbleBean, AbleDataBufferManager, AbleEventListener, AbleEventListenerManager, AbleEventQueueManager, AbleEventQueueProcessor, AblePropertyChangeManager, AbleSerializable, java.io.Serializable

Direct Known Subclasses:

AbleAbstractImport, AbleBeanAdaptor, AbleBeanWrapper, AbleConversationManager, AbleDataMap, AbleDataSeries, AbleDataSeriesHeader, AbleDataTable, AbleDBExport, AbleDecisionTree, AbleDecisionTree, AbleDefaultAgent, AbleExport, AbleFileWatcher, AbleFilter, AbleKnn, AbleNaiveBayes, AbleNaiveBayes, AbleNaiveBayesDistributed, AbleNetwork, AblePetriNode, AbleRemoteObject, AbleRuleSet, AbleTimeSeriesFilter, PolicyDemo, SampleSensorEffector, SimpleAbleBean

public class AbleObject

extends java.lang.Object

implements AbleBean, java.io.Serializable

The AbleObject class is the default implementation of the AbleBean interface and is the base class for all ABLE objects. AbleObjects are JavaBeans which are specifically designed to be part of the ABLE framework.

The Able lifecycle is modeled after the FIPA 97 specification. The mapping from states and transitions to methods is as follows:

Initial AbleState	Resulting AbleState	Produced by Method
UNKNOWN	UNINITIATED	constructor
UNINITIATED	INITIATED	init() or init(Object) -- asynchronous events not enabled
UNINITIATED	WAITING	init() or init(Object) -- if asynchronous events enabled
INITIATED	WAITING	startEnabledEventProcessing()
WAITING or ACTIVE	SUSPENDED	suspendEnabledEventProcessing()
SUSPENDED	WAITING	resumeEnabledEventProcessing()
WAITING or ACTIVE	UNKNOWN	quitEnabledEventProcessing()
ACTIVE	WAITING	*EventQueue run() loop toggles state
WAITING	ACTIVE	*EventQueue run() loop toggles state
WAITING or ACTIVE	TRANSIT	move() method -- mobile agent not yet supported

*EventQueue run() loop state changes do not cause an AbleProperty.ProcessingState event. All other transitions cause an AbleProperty.ProcessingState event. To register for run() loop state changes, register with stateChgSupport. Notification of other transitions are sent to listeners registered with chgSupport.

See Also:

Serialized Form

Field Summary

protected boolean	changed The "changed" field indicates whether the object has been changed since the last time it was saved (serialized) and hence needs to update/reset itself.
protected java.beans.PropertyChangeSupport	chgSupport Property change support.
protected java.lang.String	comment The "comment" provides a place to associate a description of this object.
protected boolean	dataFlowEnabled The "dataFlowEnabled" field indicates whether this bean should process data in buffers.
static java.lang.String	defaultName The name assigned to a new AbleObject when the empty constructor is used.
protected java.util.Vector	destBufferConnections A list of AbleBufferConnection objects that receive output data from this bean.
protected AbleEventQueue	eventQueue The event queue provides a single asynchronous thread of control for this Able object.
protected java.lang.String	fileName The name of the file where this bean will be written when it is serialized, or the name of the file from which a serialized version of the bean will be read.
protected java.lang.Object	inputBuffer The "inputBuffer" field is initialized to null, but can be used by other objects to provide input data to a bean's process() synchronous method.
protected java.util.Vector	listeners A list of AbleEventListener objects that have registered with this bean.
protected AbleLogger	logger The logger is a default static logger to record locale-specific messages for users and operators.
protected java.lang.String	name The name of this bean.
protected java.lang.Object	outputBuffer The "outputBuffer" field is initialized to null, but may be set by this bean's synchronous process() method to provide output data to other ABLE objects.
protected AbleBeanContainer	parent The AbleBeanContainer parent, if any, in which this bean resides.
protected java.util.Map	properties A collection of properties that the user can set and use in any manner desired.
protected AblePropertyConnectionManager	propertyConnectionMgr The property connections manager, a serializable version of a property change listener, is used to propagate property change events.
protected java.util.Vector	sourceBufferConnections A list of AbleBufferConnection objects that provide input data to this bean.
protected AbleState	state The state of this bean as defined in AbleState.
protected java.beans.PropertyChangeSupport	stateChgSupport State change support.
protected AbleLogger	trace The trace field is a default static logger for programmer-use trace messages.

Constructor Summary

AbleObject()
Construct a base AbleObject with a default name.

AbleObject(java.lang.String theName)
Construct a base AbleObject with a specified name.

AbleObject(java.lang.String theName, java.lang.String theComment)
Construct a base AbleObject with a specified name and comment.

Method Summary

void	addAbleEventListener(AbleEventListener theListener) Adds an event listener to this bean.
void	addDestBufferConnection(AbleBufferConnection theAbleBufferConnection) Adds a destination buffer connection.
void	addPropertyChangeListener(java.beans.PropertyChangeListener theListener) Add a property change listener to this bean.
void	addPropertyConnection(AblePropertyConnection thePropertyConnection) Adds a property connection.
void	addSourceBufferConnection(AbleBufferConnection theAbleBufferConnection) Adds a source buffer connection.
void	addStateChangeListener(java.beans.PropertyChangeListener theStateChangeListener) Add a state change listener to this bean.
void	dataChanged(java.lang.Object theArg) A convenience method to construct and send an asynchronous AbleEvent.DATACHANGED event to notify any registered listeners that this bean's internal state has changed.
void	firePropertyChange(java.lang.String thePropertyName, java.lang.Object theOldValue, java.lang.Object theNewValue) Fire a PropertyChangeEvent for a changed property.
void	flushAbleEventQueue() Removes all events from the event queue.
java.util.Vector	getAbleEventListeners() Returns a list of all registered listeners.
int	getAbleEventProcessingEnabled() Returns the state of asynchronous ABLE event processing.
int	getAbleEventQueueSize() Returns the number of events on the event queue.
java.lang.String	getComment() Returns the comment associated with this bean.
java.util.Vector	getDestBufferConnections() Returns the list of all destination (output) buffer connections.
java.lang.String	getFileName() Returns the persistent store file name.
java.lang.Object	getInputBuffer() Returns a reference to the input buffer.
java.lang.Object	getInputBuffer(int theIndex) Returns the value of a single element of the input buffer.
java.lang.String	getInputBufferAsString() Returns the contents of the input buffer as a String.
java.lang.String[]	getInputBufferAsStringArray() Returns the contents of the input buffer as an array of strings.
java.util.Enumeration	getInputBufferContents() Returns the contents of the input buffer as an enumeration.
AbleLogger	getLogger() Returns the current message logger.
java.lang.String	getName() Returns the name of this bean.
java.lang.Object	getOutputBuffer() Returns a reference to the output buffer.
java.lang.Object	getOutputBuffer(int theIndex) Returns the value of a single element of the output buffer.
java.lang.String	getOutputBufferAsString() Returns the contents of the output buffer as a String.
java.lang.String[]	getOutputBufferAsStringArray() Returns the contents of the output buffer as an array of Strings.
java.util.Enumeration	getOutputBufferContents() Returns the contents of the output buffer as an enumeration.
AbleBeanContainer	getParent() Returns the containing parent of this bean.
java.util.Map	getProperties() Returns a pointer to the entire current collection of properties.
java.lang.String	getProperty(java.lang.String theName) Gets the property associated with the specified name.
java.beans.PropertyChangeListener[]	getPropertyChangeListeners() Get the set of registered property change listeners from this bean.
AblePropertyConnectionManager	getPropertyConnectionManager() Returns this bean's property connection manager.
long	getSleepTime() Returns the current sleep time setting.
java.util.Vector	getSourceBufferConnections() Returns a list of all source (input) buffer connections.
int	getState() Returns the current state of this bean.
AbleLogger	getTraceLogger() Returns the current trace logger.
void	handleAbleEvent(AbleEvent theAbleEvent) Handles an Able event.
boolean	hasInputBuffer() Indicates if this bean has an input buffer.
boolean	hasOutputBuffer() Indicates if this bean has an output buffer.
void	init() Initialize and configure the bean.
void	init(java.lang.Object theArg) Initialize and configure the bean, using the specified Object.
boolean	isAbleEventPostingEnabled() Indicates whether asynchronous ABLE event posting is enabled or disabled.
boolean	isAbleEventProcessingEnabled() Indicates whether asynchronous ABLE event processing is enabled or disabled.
boolean	isChanged() Indicates if the bean has been changed since the last serialization operation.
boolean	isConnectable() Indicates if this bean supports buffer connections.
boolean	isDataFlowEnabled() Indicates if the bean will process data in buffers.
boolean	isTimerEventProcessingEnabled() Indicates if automatic periodic processing is enabled or disabled.
void	notifyAbleEventListeners(AbleEvent theEvent) Notify all registered listeners by sending the specified event via their implemented AbleEventListener.handleAbleEvent(AbleEvent) method.
void	process() Performs the main, synchronous, standard processing function performed by this bean.
java.lang.Object	process(java.lang.Object theArg) Perform the main, standard processing function performed by this bean, using the argument Object (usually passed via an AbleEvent).
void	processAbleEvent(AbleEvent theAbleEvent) Processes an Able event synchronously; that is, on the same thread as the caller.
void	processBufferConnections() Processes all buffer connections.
void	processNoEventProcessingEnabledSituation() Process the situation where neither timer nor Able event processing is enabled in the event queue, but the event queue's asynchronus thread of control has been started.
void	processTimerEvent() Process a timer expiration event synchronously; that is, on the same thread as the caller.
void	quitAll() Quits all forms of processing for this bean.
void	quitEnabledEventProcessing() Stop the bean's asynchronous thread of control.
void	removeAbleEventListener(AbleEventListener theListener) Removes an event listener from this bean.
void	removeAllAbleEventListeners() Remove all listener connections from this bean.
void	removeAllBufferConnections() Remove all buffer connections whether source or destination.
void	removeAllConnections() Removes all Property, Buffer, and Event connections.
void	removeAllPropertyConnections() Removes all property connections.
void	removeDestBufferConnection(AbleBufferConnection theAbleBufferConnection) Remove a destination buffer connection.
java.lang.String	removeProperty(java.lang.String theName) Removes the property and the specified name from the collection of properties.
void	removePropertyChangeListener(java.beans.PropertyChangeListener theListener) Remove a property change listener from this bean.
void	removePropertyConnection(AblePropertyConnection thePropertyConnection) Removes a property connection.
void	removeSourceBufferConnection(AbleBufferConnection theAbleBufferConnection) Removes a source buffer connection.
void	removeStateChangeListener(java.beans.PropertyChangeListener theStateChangeListener) Remove a state change listener from this bean.
void	reset() Reset this bean to its "initialized" state.
void	restartEnabledEventProcessing() Restart the bean's asynchronous thread of control after the bean has moved from one system to another.
AbleBean	restoreFromFile() Read a serialized bean from the file named previously by the setFileName() method, or from the default name provided by the implementor.
AbleBean	restoreFromFile(java.lang.String theFileName) Read a serialized bean from the specified file.
static AbleBean	restoreFromSerializedFile(java.lang.String theFileName) Read a serialized bean from the specified file.
static AbleBean	restoreFromStream(java.io.ObjectInputStream theObjectInputStream) Read a serialized bean from the specified object input stream.
void	resumeAll() Resumes all of the bean's suspended asynchronous threads of control.
void	resumeEnabledEventProcessing() Resume the bean's suspended asynchronous thread of control.
void	saveToFile() Write a serialized version of this bean to the file named previously by the setFileName(java.lang.String) method, or to the default name provided by the implementor.
void	saveToFile(java.lang.String theFileName) Write a serialized version of this bean to the specified file.
void	setAbleEventProcessingEnabled(int theEnabledFlag) Specify whether asynchronous ABLE event processing is enabled or disabled.
void	setChanged(boolean theChangedFlag) Set the changed flag.
void	setComment(java.lang.String theComment) Set or change the comment describing this bean.
void	setDataFlowEnabled(boolean theDataFlowEnabledState) Sets the data flow processing state of the bean.
void	setFileName(java.lang.String theFileName) Sets or changes the persistent store file name.
void	setInputBuffer(int theIndex, java.lang.Object theObject) Sets the value of a single element of the input buffer.
void	setInputBuffer(java.lang.Object theInputBuffer) Sets the input buffer to the specified object.
void	setLogger(AbleLogger theLogger) Sets the logger to be used for message output.
void	setName(java.lang.String theName) Set or change the name of this bean.
void	setOutputBuffer(int theIndex, java.lang.Object theObject) Sets the value of a single element of the output buffer.
void	setOutputBuffer(java.lang.Object theOutputBuffer) Sets the output buffer to the specified object.
void	setParent(AbleBeanContainer theParent) Sets the containing parent of this bean.
void	setProperties(java.util.Map theProperties) Sets the entire collection of properties to the specified collection.
void	setProperty(java.lang.String theName, java.lang.String theValue) Sets the specified property to the specified value.
void	setSleepTime(long theSleepTime) Sets the sleep time interval for the asynchronous timed processing loop.
void	setState(int theState) Set the state of this bean.
void	setTimerEventProcessingEnabled(boolean theEnabledFlag) Specify whether automatic periodic processing is enabled or disabled.
void	setTraceLogger(AbleLogger theLogger) Sets a logger to be used for tracing program-level output.
boolean	sourceConnectionsOK(java.util.Vector theObjectProcessList) Check to see if the incoming connections are OK.
void	startEnabledEventProcessing() Start the bean's asynchronous thread of control.
void	suspendAll() Temporarily suspends all of the bean's asynchronous threads of control.
void	suspendEnabledEventProcessing() Temporarily suspend the bean's asynchronous thread of control.

Methods inherited from class java.lang.Object

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

Field Detail

defaultName

public static final java.lang.String defaultName

The name assigned to a new AbleObject when the empty constructor is used.

name

protected java.lang.String name

The name of this bean. The value is never expected to be null, and is used as a key when beans are included in containers or as listeners. For this reason, once a bean is initialized, it is recommended that the name not be changed.

See Also:

setName(String), getName()

comment

protected java.lang.String comment

The "comment" provides a place to associate a description of this object. The value is initialized to the empty String ("") and is never expected to be null.

See Also:

setComment(String), getComment()

changed

protected boolean changed

The "changed" field indicates whether the object has been changed since the last time it was saved (serialized) and hence needs to update/reset itself. true indicates that the object has been changed, false indicates that it has not. The field is initialized to false.

See Also:

setChanged(boolean), isChanged()

dataFlowEnabled

protected boolean dataFlowEnabled

The "dataFlowEnabled" field indicates whether this bean should process data in buffers. true indicates that the object should process data in buffers, false indicates that it should not. The field is initialized to false.

See Also:

setDataFlowEnabled(boolean), isDataFlowEnabled()

fileName

protected java.lang.String fileName

The name of the file where this bean will be written when it is serialized, or the name of the file from which a serialized version of the bean will be read. The field is initialized to "untitled.ser".

See Also:

setFileName(String), getFileName()

trace

protected AbleLogger trace

The trace field is a default static logger for programmer-use trace messages. This field is initialized to Able.TraceLog. To minimize performance impacts of tracing, any calls to the the trace field should be bound by if (trace.isLogging()). Tracing may be performed for an individual bean, which is controlled by the methods Able.startBeanTraceLogging(AbleBean) and Able.stopBeanTraceLogging(AbleBean).

See Also:

AbleTraceLogger, setTraceLogger(com.ibm.able.AbleLogger), getTraceLogger()

logger

protected AbleLogger logger

The logger is a default static logger to record locale-specific messages for users and operators. This field is initialized to Able.MessageLog.

See Also:

AbleTraceLogger, setLogger(AbleLogger), getLogger()

parent

protected AbleBeanContainer parent

The AbleBeanContainer parent, if any, in which this bean resides. This field is initialized to null.

See Also:

setParent(AbleBeanContainer), getParent()

state

protected AbleState state

The state of this bean as defined in AbleState. This field is initialized to AbleState.Unknown.

See Also:

setState(int), getState()

inputBuffer

protected java.lang.Object inputBuffer

The "inputBuffer" field is initialized to null, but can be used by other objects to provide input data to a bean's process() synchronous method.

Although any Object type may be used as an input buffer, the base ABLE classes expect the buffer to be one of the following types:

• double[]
• long[]
• Number[]
• Byte[]
• Double[]
• Float[]
• Integer[]
• Long[]
• Short[]
• String[]
• Vector
• Hashtable

If you wish to use another type in a class you are developing, you may need to override some buffer manipulation methods.

See Also:

setInputBuffer(Object), setInputBuffer(int, Object), getInputBuffer(), getInputBuffer(int)

outputBuffer

protected java.lang.Object outputBuffer

The "outputBuffer" field is initialized to null, but may be set by this bean's synchronous process() method to provide output data to other ABLE objects.

See Also:

setOutputBuffer(Object), setOutputBuffer(int, Object), getOutputBuffer(), getOutputBuffer(int)

sourceBufferConnections

protected java.util.Vector sourceBufferConnections

A list of AbleBufferConnection objects that provide input data to this bean. The field is initialized to a new, empty Vector, and is never expected to be null.

See Also:

addSourceBufferConnection(AbleBufferConnection), removeSourceBufferConnection(AbleBufferConnection), getSourceBufferConnections(), processBufferConnections(), removeAllBufferConnections()

destBufferConnections

protected java.util.Vector destBufferConnections

A list of AbleBufferConnection objects that receive output data from this bean. The field is initialized to a new, empty Vector, and is never expected to be null.

See Also:

addDestBufferConnection(AbleBufferConnection), removeDestBufferConnection(AbleBufferConnection), getDestBufferConnections(), processBufferConnections(), removeAllBufferConnections()

propertyConnectionMgr

protected AblePropertyConnectionManager propertyConnectionMgr

The property connections manager, a serializable version of a property change listener, is used to propagate property change events. It is registered as a listener with the chgSupport object.

See Also:

addPropertyConnection(AblePropertyConnection), removePropertyConnection(AblePropertyConnection), getPropertyConnectionManager()

properties

protected java.util.Map properties

A collection of properties that the user can set and use in any manner desired.

The default underlying data type is java.util.Hashtable, selected because its methods are synchronized. If synchronization isn't an issue, use setProperties(Map) to set the member to some other data type.

The member must never be null.

Property change events are not fired for changes to this member.

Since:

2.2.0

See Also:

setProperty(String,String), getProperty(String), setProperties(Map), getProperties()

eventQueue

protected AbleEventQueue eventQueue

The event queue provides a single asynchronous thread of control for this Able object. The event queue can provide periodic processing at set intervals, asynchronous event processing, or both.

See Also:

AbleEventQueue

listeners

protected transient java.util.Vector listeners

A list of AbleEventListener objects that have registered with this bean. The field is initialized to a new, empty Vector, and is never expected to be null.

See Also:

addAbleEventListener(AbleEventListener), removeAbleEventListener(AbleEventListener), notifyAbleEventListeners(AbleEvent)

chgSupport

protected transient java.beans.PropertyChangeSupport chgSupport

Property change support.

See Also:

addPropertyChangeListener(PropertyChangeListener), removePropertyChangeListener(PropertyChangeListener), firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

stateChgSupport

protected transient java.beans.PropertyChangeSupport stateChgSupport

State change support.

A bean's state can change rapidly and frequently, particularly when processing asynchronously. This results in many state changes between AbleState.Active and AbleState.Waiting which may not be of general interest. events flying about; not everyone may be interested in these state changes, so regular property change listeners are not notified of state changes; only those that explicitly register as state change listeners are notified.

See Also:

addStateChangeListener(PropertyChangeListener), removeStateChangeListener(PropertyChangeListener)

Constructor Detail

AbleObject

public AbleObject()

Construct a base AbleObject with a default name.

A default AblePropertyConnectionManager object is added to the internal PropertyChangeSupport object. The state is changed to AbleState.Uninitiated.

AbleObject

public AbleObject(java.lang.String theName)

Construct a base AbleObject with a specified name.

A default AblePropertyConnectionManager object is added to the internal PropertyChangeSupport object. The state is changed to AbleState.Uninitiated.

Parameters:

theName - The name of this bean.

AbleObject

public AbleObject(java.lang.String theName,
                  java.lang.String theComment)

Construct a base AbleObject with a specified name and comment. A default AblePropertyConnectionManager object is added to the internal PropertyChangeSupport object. The state is changed to AbleState.Uninitiated.

Parameters:

theName - The name of this bean.

theComment - A descriptive comment for this bean.

Method Detail

restoreFromSerializedFile

public static AbleBean restoreFromSerializedFile(java.lang.String theFileName)
                                          throws java.lang.ClassNotFoundException,
                                                 java.io.IOException

Read a serialized bean from the specified file.

Note that a side-effect of this method is that the instance variable fileName of the restored bean is changed to the specified file name using the setFileName() method. As the original serialized file may have been copied to the file being read, this ensures the fileName reflects the actual file.

Parameters:

theFileName - The path and file containing the serialized AbleBean.

Returns:

The de-serialized bean.

Throws:

java.lang.ClassNotFoundException - If any class file is not found during reserialization.

java.io.IOException - If an IO exception occurs while reading the file.

restoreFromStream

public static AbleBean restoreFromStream(java.io.ObjectInputStream theObjectInputStream)
                                  throws java.lang.ClassNotFoundException,
                                         java.io.IOException

Read a serialized bean from the specified object input stream.

Note that the fileName instance variable is changed to the empty string ("").

Parameters:

theObjectInputStream - The name of the file containing the serialized AbleBean

Returns:

The de-serialized bean.

Throws:

java.lang.ClassNotFoundException - If any class file is not found during reserialization.

java.io.IOException - If an IO exception occurs while reading the file.

setName

public void setName(java.lang.String theName)

Set or change the name of this bean. As this value is used as a key when beans are included in containers or as listeners, once a bean is initialized, it is recommended that the name not be changed.

An AbleProperty.Name PropertyChangeEvent is fired.

Specified by:

setName in interface AbleBean

Parameters:

theName - The new name of this bean, replacing any current name.

getName

public java.lang.String getName()

Description copied from interface: AbleBean

Returns the name of this bean.

Specified by:

getName in interface AbleBean

Returns:

The current name of this AbleBean object or the empty string if no name has been set. The value is never expected to be null.

setComment

public void setComment(java.lang.String theComment)

Set or change the comment describing this bean.

An AbleProperty.Comment PropertyChangeEvent is fired.

Specified by:

setComment in interface AbleBean

Parameters:

theComment - The new comment for this bean, replacing any current comment.

See Also:

comment

getComment

public java.lang.String getComment()

Description copied from interface: AbleBean

Returns the comment associated with this bean.

Specified by:

getComment in interface AbleBean

Returns:

The current comment associated with this bean or the empty string if no comment has been set. The value is never expected to be null.

setChanged

public void setChanged(boolean theChangedFlag)

Set the changed flag.

An AbleProperty.Changed PropertyChangeEvent is fired.

Specified by:

setChanged in interface AbleBean

Parameters:

theChangedFlag - The value indicating whether this bean is to be marked as modified. If true, the bean will be marked as modified; otherwise, the bean will be marked as unmodified. Saving or serializing the bean should reset the change flag to unmodified.

See Also:

changed

isChanged

public boolean isChanged()

Description copied from interface: AbleBean

Indicates if the bean has been changed since the last serialization operation.

Specified by:

isChanged in interface AbleBean

Returns:

true if the bean has been changed since the last save; false otherwise.

dataChanged

public void dataChanged(java.lang.Object theArg)
                 throws AbleException

A convenience method to construct and send an asynchronous AbleEvent.DATACHANGED event to notify any registered listeners that this bean's internal state has changed.

Specified by:

dataChanged in interface AbleEventListenerManager

Parameters:

theArg - An object to be used as the argument of an AbleEvent.

Throws:

AbleException - If an error occurs.

See Also:

handleAbleEvent(AbleEvent), AbleEvent.AbleEvent(Object,Object)

setDataFlowEnabled

public void setDataFlowEnabled(boolean theDataFlowEnabledState)

Sets the data flow processing state of the bean.

An AbleProperty.DataFlowEnabled PropertyChangeEvent is fired.

Specified by:

setDataFlowEnabled in interface AbleDataBufferManager

Parameters:

theDataFlowEnabledState - Indicates if this bean will process data in buffers. When set to true, this bean will be included in its parent's process list.

isDataFlowEnabled

public boolean isDataFlowEnabled()

Description copied from interface: AbleDataBufferManager

Indicates if the bean will process data in buffers.

Specified by:

isDataFlowEnabled in interface AbleDataBufferManager

Returns:

true if the bean will process data in buffers; false otherwise.

setFileName

public void setFileName(java.lang.String theFileName)

Sets or changes the persistent store file name. An AbleProperty.FileName PropertyChangeEvent is fired.

Specified by:

setFileName in interface AbleSerializable

Parameters:

theFileName - The new name of the file to which this bean can be serialized or from which the bean can be de-serialized. This file name replaces the current file name.

getFileName

public java.lang.String getFileName()

Description copied from interface: AbleSerializable

Returns the persistent store file name.

Specified by:

getFileName in interface AbleSerializable

Returns:

A String containing the current name of the file to which this bean is to be serialized or from which the bean can be de-serialized.

setTraceLogger

public void setTraceLogger(AbleLogger theLogger)

Sets a logger to be used for tracing program-level output. A AbleProperty.Logger is fired.

If a logger is available and is active, base ABLE code will use it to log trace messages.

Specified by:

setTraceLogger in interface AbleBean

Parameters:

theLogger - A logger that can be used to trace base ABLE code. The value cannot be null.

getTraceLogger

public AbleLogger getTraceLogger()

Description copied from interface: AbleBean

Returns the current trace logger.

Specified by:

getTraceLogger in interface AbleBean

Returns:

The current trace logger.

setLogger

public void setLogger(AbleLogger theLogger)

Sets the logger to be used for message output. A AbleProperty.Logger is fired.

If a logger is available and is active, it will be used to log translated messages.

Specified by:

setLogger in interface AbleBean

Parameters:

theLogger - A logger that can be used to record translated messages. The value cannot be null.

getLogger

public AbleLogger getLogger()

Description copied from interface: AbleBean

Returns the current message logger.

Specified by:

getLogger in interface AbleBean

Returns:

the current message logger.

setParent

public void setParent(AbleBeanContainer theParent)

Sets the containing parent of this bean. Typically this method is called from the parent container's addBean method. It is not expected to be called from the bean itself. A AbleProperty.Parent is fired.

Specified by:

setParent in interface AbleBean

Parameters:

theParent - An ABLE bean container object in which this bean currently resides. Note that a bean may only have one parent at any given time, so this new parent completely replaces the current parent.

getParent

public AbleBeanContainer getParent()

Description copied from interface: AbleBean

Returns the containing parent of this bean.

Specified by:

getParent in interface AbleBean

Returns:

An AbleBeanContainer object in which this bean resides or null if no parent has been set.

setState

public void setState(int theState)

Set the state of this bean. An AbleProperty.State PropertyChangeEvent is fired through the stateChgSupport object.

Specified by:

setState in interface AbleBean

Parameters:

theState - An AbleState. value.

getState

public int getState()

Description copied from interface: AbleBean

Returns the current state of this bean.

Specified by:

getState in interface AbleBean

Returns:

An AbleState value.

setInputBuffer

public void setInputBuffer(java.lang.Object theInputBuffer)
                    throws AbleException

Sets the input buffer to the specified object. No PropertyChangeEvent is fired.

Specified by:

setInputBuffer in interface AbleDataBufferManager

Parameters:

theInputBuffer - Any object, such as a String[], Vector, Hashtable, and so on, that can act as a buffer of input data. A reference to the object is saved; the object is not cloned. Note that once the input buffer is set, it must not be tampered with while an AbleBean is reading data from it.

Throws:

AbleException - If an error occurs.

getInputBuffer

public java.lang.Object getInputBuffer()

Description copied from interface: AbleDataBufferManager

Returns a reference to the input buffer.

Specified by:

getInputBuffer in interface AbleDataBufferManager

Returns:

A reference to the object that is the current input buffer, or null if no input buffer has been set.

setInputBuffer

public void setInputBuffer(int theIndex,
                           java.lang.Object theObject)
                    throws AbleException

Description copied from interface: AbleDataBufferManager

Sets the value of a single element of the input buffer.

Specified by:

setInputBuffer in interface AbleDataBufferManager

Parameters:

theIndex - The location in the input buffer to be set to the specified value.

theObject - The new value of the element at the specified location.

Throws:

AbleException - If the input buffer does not support indexing.

getInputBuffer

public java.lang.Object getInputBuffer(int theIndex)
                                throws AbleException

Description copied from interface: AbleDataBufferManager

Returns the value of a single element of the input buffer.

Specified by:

getInputBuffer in interface AbleDataBufferManager

Parameters:

theIndex - The location to retrieve from the input buffer.

Returns:

The object at the specified location, or null if no input buffer exists or if the location does not contain a value.

Throws:

AbleException - If the input buffer does not support indexing.

hasInputBuffer

public boolean hasInputBuffer()

Description copied from interface: AbleDataBufferManager

Indicates if this bean has an input buffer.

Specified by:

hasInputBuffer in interface AbleDataBufferManager

Returns:

true if the input buffer has been set; that is, the buffer is not null; otherwise false is returned.

getInputBufferAsStringArray

public java.lang.String[] getInputBufferAsStringArray()
                                               throws AbleException

Description copied from interface: AbleDataBufferManager

Returns the contents of the input buffer as an array of strings.

Specified by:

getInputBufferAsStringArray in interface AbleDataBufferManager

Returns:

An array of string values of the input buffer, or null if no input buffer has been sent.

Throws:

AbleException - If the input buffer cannot be converted to an array of string values.

getInputBufferContents

public java.util.Enumeration getInputBufferContents()
                                             throws AbleException

Description copied from interface: AbleDataBufferManager

Returns the contents of the input buffer as an enumeration.

Specified by:

getInputBufferContents in interface AbleDataBufferManager

Returns:

An enumeration of values from the input buffer, or null if no input buffer has been set.

Throws:

AbleException - If the input buffer cannot be returned as an enumeration.

setOutputBuffer

public void setOutputBuffer(java.lang.Object theOutputBuffer)
                     throws AbleException

Sets the output buffer to the specified object.

An AbleProperty.OutputBuffer PropertyChangeEvent is fired.

Specified by:

setOutputBuffer in interface AbleDataBufferManager

Parameters:

theOutputBuffer - Any object, such as a String[], Vector, Hashtable, and so on, that can act as a buffer of output data. A reference to the object is saved; the object is not cloned. Note that once the output buffer is set, it must not be tampered with while an AbleBean is writing data to it.

Throws:

AbleException - If an error occurs.

getOutputBuffer

public java.lang.Object getOutputBuffer()

Description copied from interface: AbleDataBufferManager

Returns a reference to the output buffer.

Specified by:

getOutputBuffer in interface AbleDataBufferManager

Returns:

A reference to the object that is the current output buffer, or null if no output buffer has been set.

setOutputBuffer

public void setOutputBuffer(int theIndex,
                            java.lang.Object theObject)
                     throws AbleException

Description copied from interface: AbleDataBufferManager

Sets the value of a single element of the output buffer.

Specified by:

setOutputBuffer in interface AbleDataBufferManager

Parameters:

theIndex - The location in the output buffer to be set to the specified value.

theObject - The new value of the element at the specified location.

Throws:

AbleException - If the output buffer does not support indexing.

getOutputBuffer

public java.lang.Object getOutputBuffer(int theIndex)
                                 throws AbleException

Description copied from interface: AbleDataBufferManager

Returns the value of a single element of the output buffer.

Specified by:

getOutputBuffer in interface AbleDataBufferManager

Parameters:

theIndex - The location in the output buffer to be retrieved.

Returns:

The object at the specified location, or null if no output buffer exists or if the location does not contain a value.

Throws:

AbleException - If the output buffer does not support indexing.

hasOutputBuffer

public boolean hasOutputBuffer()

Description copied from interface: AbleDataBufferManager

Indicates if this bean has an output buffer.

Specified by:

hasOutputBuffer in interface AbleDataBufferManager

Returns:

true if the output buffer has been set; that is, the buffer is not null; otherwise false is returned.

getOutputBufferAsStringArray

public java.lang.String[] getOutputBufferAsStringArray()
                                                throws AbleException

Description copied from interface: AbleDataBufferManager

Returns the contents of the output buffer as an array of Strings.

Specified by:

getOutputBufferAsStringArray in interface AbleDataBufferManager

Returns:

An array of string values of the output buffer, or null if no output buffer has been set.

Throws:

AbleException - If the output buffer cannot be converted to an array of String values.

getOutputBufferContents

public java.util.Enumeration getOutputBufferContents()
                                              throws AbleException

Description copied from interface: AbleDataBufferManager

Returns the contents of the output buffer as an enumeration.

Specified by:

getOutputBufferContents in interface AbleDataBufferManager

Returns:

An enumeration of the output buffer, or null if no output buffer has been set.

Throws:

AbleException - If the output buffer cannot be returned as an enumeration.

getOutputBufferAsString

public java.lang.String getOutputBufferAsString()
                                         throws AbleException

Description copied from interface: AbleDataBufferManager

Returns the contents of the output buffer as a String.

Specified by:

getOutputBufferAsString in interface AbleDataBufferManager

Returns:

A string representation of the output buffer, or null if no output buffer has been set.

Throws:

AbleException - If the output buffer cannot be converted to String.

getInputBufferAsString

public java.lang.String getInputBufferAsString()
                                        throws AbleException

Description copied from interface: AbleDataBufferManager

Returns the contents of the input buffer as a String.

Specified by:

getInputBufferAsString in interface AbleDataBufferManager

Returns:

A string representation of the input buffer, or null if no input buffer has been set.

Throws:

AbleException - If the input buffer cannot be converted to String.

addSourceBufferConnection

public void addSourceBufferConnection(AbleBufferConnection theAbleBufferConnection)

Adds a source buffer connection.

An AbleProperty.SourceBufferConnections PropertyChangeEvent is fired.

Specified by:

addSourceBufferConnection in interface AbleDataBufferManager

Parameters:

theAbleBufferConnection - An AbleBufferConnection object including a bean whose output buffer populates this bean's input buffer.

removeSourceBufferConnection

public void removeSourceBufferConnection(AbleBufferConnection theAbleBufferConnection)

Removes a source buffer connection.

An AbleProperty.SourceBufferConnections PropertyChangeEvent is fired.

Specified by:

removeSourceBufferConnection in interface AbleDataBufferManager

Parameters:

theAbleBufferConnection - The AbleBufferConnection object to be removed.

getSourceBufferConnections

public java.util.Vector getSourceBufferConnections()

Description copied from interface: AbleDataBufferManager

Returns a list of all source (input) buffer connections. Typically only one of these connections is to an active bean.

Specified by:

getSourceBufferConnections in interface AbleDataBufferManager

Returns:

All source buffer connections.

addDestBufferConnection

public void addDestBufferConnection(AbleBufferConnection theAbleBufferConnection)

Adds a destination buffer connection.

An AbleProperty.DestBufferConnections PropertyChangeEvent is fired.

Specified by:

addDestBufferConnection in interface AbleDataBufferManager

Parameters:

theAbleBufferConnection - An AbleBufferConnection object including a bean whose input buffer is to be populated from this bean's output buffer.

removeDestBufferConnection

public void removeDestBufferConnection(AbleBufferConnection theAbleBufferConnection)

Remove a destination buffer connection.

An AbleProperty.DestBufferConnections PropertyChangeEvent is fired.

Specified by:

removeDestBufferConnection in interface AbleDataBufferManager

Parameters:

theAbleBufferConnection - The AbleBufferConnection object to be removed.

getDestBufferConnections

public java.util.Vector getDestBufferConnections()

Description copied from interface: AbleDataBufferManager

Returns the list of all destination (output) buffer connections.

Specified by:

getDestBufferConnections in interface AbleDataBufferManager

Returns:

All destination buffer connections.

isConnectable

public boolean isConnectable()

Indicates if this bean supports buffer connections.

This base implementation always returns true, as all of the base classes support buffers & data flow processing. If you are implementing a bean or agent that does not support data flow processing, or only supports it conditionally, you may want to override this method.

Specified by:

isConnectable in interface AbleDataBufferManager

Returns:

true if this bean supports buffer connections; false otherwise.

processBufferConnections

public void processBufferConnections()
                              throws AbleException

Processes all buffer connections. Moves data from connected source beans' outputBuffers to this bean's inputBuffer. All connections are processed and any exception resulting from any connection are thrown as an AbleExceptionCollection.

Specified by:

processBufferConnections in interface AbleDataBufferManager

Throws:

AbleException - If an error occurs.

removeAllConnections

public void removeAllConnections()
                          throws AbleException

Removes all Property, Buffer, and Event connections.

Specified by:

removeAllConnections in interface AbleBean

Throws:

AbleException - If an error occurs.

See Also:

removeAllAbleEventListeners(), removeAllBufferConnections(), removeAllPropertyConnections()

removeAllBufferConnections

public void removeAllBufferConnections()

Remove all buffer connections whether source or destination.

Both an AbleProperty.SourceBufferConnections PropertyChangeEvent and an AbleProperty.DestBufferConnections PropertyChangeEvent are fired.

Specified by:

removeAllBufferConnections in interface AbleDataBufferManager

addPropertyConnection

public void addPropertyConnection(AblePropertyConnection thePropertyConnection)

Adds a property connection.

A AbleProperty.DestBufferConnections is fired.

Specified by:

addPropertyConnection in interface AblePropertyChangeManager

Parameters:

thePropertyConnection - The ABLE property connection object representing a bean's interest in one of the implementor's properties.

removePropertyConnection

public void removePropertyConnection(AblePropertyConnection thePropertyConnection)
                              throws AbleException

Removes a property connection.

Specified by:

removePropertyConnection in interface AblePropertyChangeManager

Parameters:

thePropertyConnection - The ABLE property connection object to remove.

Throws:

AbleException - If an error occurs.

removeAllPropertyConnections

public void removeAllPropertyConnections()
                                  throws AbleException

Removes all property connections.

Specified by:

removeAllPropertyConnections in interface AblePropertyChangeManager

Throws:

AbleException - If an error occurs.

getPropertyConnectionManager

public AblePropertyConnectionManager getPropertyConnectionManager()

Description copied from interface: AblePropertyChangeManager

Returns this bean's property connection manager.

Specified by:

getPropertyConnectionManager in interface AblePropertyChangeManager

Returns:

The ABLE property connection manager for this bean.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener theListener)

Description copied from interface: AblePropertyChangeManager

Add a property change listener to this bean.

Specified by:

addPropertyChangeListener in interface AblePropertyChangeManager

Parameters:

theListener - An object interested in this bean's property changes.

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener theListener)

Description copied from interface: AblePropertyChangeManager

Remove a property change listener from this bean.

Specified by:

removePropertyChangeListener in interface AblePropertyChangeManager

Parameters:

theListener - The object no longer interested in this bean's properties.

getPropertyChangeListeners

public java.beans.PropertyChangeListener[] getPropertyChangeListeners()

Description copied from interface: AblePropertyChangeManager

Get the set of registered property change listeners from this bean.

Specified by:

getPropertyChangeListeners in interface AblePropertyChangeManager

firePropertyChange

public void firePropertyChange(java.lang.String thePropertyName,
                               java.lang.Object theOldValue,
                               java.lang.Object theNewValue)

Fire a PropertyChangeEvent for a changed property.

Parameters:

thePropertyName - The property being changed, typically defined in AbleProperty.

theOldValue - The previous value for the object.

theNewValue - The new value for the object.

init

public void init()
          throws AbleException

Initialize and configure the bean. The bean's state changes to AbleState.Initiated or AbleState.Waiting. If either the AbleEventProcessing or TimerEventProcessing flags are enabled, this method calls startEnabledEventProcessing() to start a new thread for asynchronous or timer event processing.

An AbleProperty.ProcessingState PropertyChangeEvent is fired.

Beans overriding this method should call super.init() after any customization and before returning so that the thread is started if needed and the PropertyChangeEvent is fired.

An application using asynchronous or timer event processing should sleep until the event queue is functional by imbedding logic like this:

    anAbleObject.init();
    while (!AbleState.isReady(anAbleObject.getState())) {
        try {
            Thread.sleep(100l);
        } catch (InterruptedException e1) {
        }
    }
 

Specified by:

init in interface AbleBean

Throws:

AbleException - If an error occurs.

See Also:

startEnabledEventProcessing()

init

public void init(java.lang.Object theArg)
          throws AbleException

Initialize and configure the bean, using the specified Object. In this implementation, the argument parameter is ignored; hence it behaves exactly like init().

An AbleProperty.ProcessingState PropertyChangeEvent is fired.

Specified by:

init in interface AbleBean

Parameters:

theArg - An Object used to initialize the bean, typically by getting parameters of interest, but ignored in this implementatoin.

Throws:

AbleException - If an error occurs.

reset

public void reset()
           throws AbleException

Reset this bean to its "initialized" state.

This base method has no default implementation. It only provides tracing.

Specified by:

reset in interface AbleBean

Throws:

AbleException - If an error occurs.

See Also:

AbleBean.reset()

process

public void process()
             throws AbleException

Performs the main, synchronous, standard processing function performed by this bean.

This base method implementation provides tracing only.

Specified by:

process in interface AbleBean

Throws:

AbleException - If an error occurs.

See Also:

inputBuffer, outputBuffer, AbleBean.process()

process

public java.lang.Object process(java.lang.Object theArg)
                         throws AbleException

Perform the main, standard processing function performed by this bean, using the argument Object (usually passed via an AbleEvent). This function copies the input parameter into the inputBuffer, invokes process() and then returns a clone of the outputBuffer.

Specified by:

process in interface AbleBean

Parameters:

theArg - An Object providing data input to the bean. Note: Only Object[], String[], Vector, and double[] arguments are handled

Returns:

the results of the process() computation, a clone of the bean OutputBuffer

Throws:

AbleException - In the following situations:

the inputBuffer variable is null (usually allocated in the init method)

the class of the parameter theArg does not match the class of the inputBuffer variable

the length of the parameter theArg array does not match the length of the inputBuffer array

the length of the parameter theArg Vector does not match the length of the inputBuffer Vector

when the bean has source data connections because the buffers could be overwritten from other threads

the outputBuffer variable is null (usually allocated in the init method)

the outputBuffer variable is an unsuppported class.

See Also:

inputBuffer, outputBuffer, AbleBean.process()

quitAll

public void quitAll()
             throws AbleException

Description copied from interface: AbleBean

Quits all forms of processing for this bean. Stop all of the bean's asynchronous threads of control. The bean's state changes to AbleState.Unknown, and it should be considered unusable for further processing.

A simple AbleBean may just call AbleEventQueueManager.quitEnabledEventProcessing(). A more complex bean may also clear itself of references so that garbage collection can occur.

A bean implementing AbleBeanContainer should call quitAll on each bean it contains and accumulate errors from each contained bean.

Specified by:

quitAll in interface AbleBean

Throws:

AbleException - If an error occurs.

See Also:

AbleBean.suspendAll(), AbleBean.resumeAll()

suspendAll

public void suspendAll()
                throws AbleException

Description copied from interface: AbleBean

Temporarily suspends all of the bean's asynchronous threads of control. The bean's state changes to AbleState.Suspended.

If the bean is a simple AbleBean, this method just calls its AbleEventQueueManager.suspendEnabledEventProcessing() method.

A bean implementing AbleBeanContainer should call this method on each bean it contains and accumulate errors from each contained bean.

Specified by:

suspendAll in interface AbleBean

Throws:

AbleException - If an error occurs.

See Also:

AbleBean.resumeAll(), AbleBean.quitAll()

resumeAll

public void resumeAll()
               throws AbleException

Description copied from interface: AbleBean

Resumes all of the bean's suspended asynchronous threads of control. The bean's state changes from AbleState.Suspended to AbleState.Waiting.

If the bean is a simple AbleBean, this method just calls its AbleEventQueueManager.resumeEnabledEventProcessing() method.

A bean implementing AbleBeanContainer should call this method on each bean it contains and accumulate errors from each contained bean.

Specified by:

resumeAll in interface AbleBean

Throws:

AbleException - If an error occurs.

See Also:

AbleBean.suspendAll(), AbleBean.quitAll()

setProperty

public void setProperty(java.lang.String theName,
                        java.lang.String theValue)

Description copied from interface: AbleBean

Sets the specified property to the specified value.

Specified by:

setProperty in interface AbleBean

Parameters:

theName - The name of the property to be placed into the collection of properties.

theValue - The value associated with the specified property.

getProperty

public java.lang.String getProperty(java.lang.String theName)

Description copied from interface: AbleBean

Gets the property associated with the specified name.

Specified by:

getProperty in interface AbleBean

Parameters:

theName - The name of the property to be returned.

Returns:

The value associated with the specified name, or null if no property has been set for the specified name.

removeProperty

public java.lang.String removeProperty(java.lang.String theName)

Description copied from interface: AbleBean

Removes the property and the specified name from the collection of properties.

Specified by:

removeProperty in interface AbleBean

Parameters:

theName - The name of the property to be removed.

Returns:

The value associated with the specified name, or null if no property has been set for the specified name.

setProperties

public void setProperties(java.util.Map theProperties)

Description copied from interface: AbleBean

Sets the entire collection of properties to the specified collection.

Specified by:

setProperties in interface AbleBean

Parameters:

theProperties - The set of properties that will replace the current collection of properties. If this parameter is specified as null, the call is ignored; that is, the underlying data member is not changed. Otherwise, the underlying data member is changed to point to the specified collection.

Keys and values of the properties collection must be confined to the String data type.

getProperties

public java.util.Map getProperties()

Description copied from interface: AbleBean

Returns a pointer to the entire current collection of properties.

Specified by:

getProperties in interface AbleBean

Returns:

The entire current collection of properties.

setSleepTime

public void setSleepTime(long theSleepTime)

Sets the sleep time interval for the asynchronous timed processing loop.

An AbleProperty.SleepTime PropertyChangeEvent is fired.

Specified by:

setSleepTime in interface AbleEventQueueManager

Parameters:

theSleepTime - The number of milliseconds for which the process is to sleep before it awakes and calls AbleEventQueueProcessor.processTimerEvent().

See Also:

processTimerEvent()

getSleepTime

public long getSleepTime()

Description copied from interface: AbleEventQueueManager

Returns the current sleep time setting.

Specified by:

getSleepTime in interface AbleEventQueueManager

Returns:

The current sleep time setting in milliseconds.

setTimerEventProcessingEnabled

public void setTimerEventProcessingEnabled(boolean theEnabledFlag)

Specify whether automatic periodic processing is enabled or disabled. When enabled and the asynchronous thread of control is started, the bean will awaken at periodic intervals as specified by sleepTime, and call the processTimerEvent() method.

This method can be used before the asynchronous thread of control is started in order to set the bean's initial behavior; the method can also be used while the thread is running to start and stop the behavior.

An AbleProperty.TimerEventProcessingEnabled PropertyChangeEvent is fired.

Specified by:

setTimerEventProcessingEnabled in interface AbleEventQueueManager

Parameters:

theEnabledFlag - Specify true if the bean is to awaken every N milliseconds and call AbleEventQueueProcessor.processTimerEvent(); specify false if no automatic periodic processing is to take place while the asynchronous thread of control is running.

See Also:

setSleepTime(long), processTimerEvent(), startEnabledEventProcessing()

isTimerEventProcessingEnabled

public boolean isTimerEventProcessingEnabled()

Description copied from interface: AbleEventQueueManager

Indicates if automatic periodic processing is enabled or disabled.

Specified by:

isTimerEventProcessingEnabled in interface AbleEventQueueManager

Returns:

true if the bean will awaken every N milliseconds; false otherwise.

setAbleEventProcessingEnabled

public void setAbleEventProcessingEnabled(int theEnabledFlag)
                                   throws java.lang.IllegalArgumentException

Specify whether asynchronous ABLE event processing is enabled or disabled. When enabled and the asynchronous thread of control is started, the bean will awaken whenever an asynchronous event is placed on the bean's internal event queue and call the processAbleEvent(com.ibm.able.AbleEvent) method.

This method can be used before the asynchronous thread of control is started in order to set the bean's initial behavior; the method can also be used while the thread is running to start and stop the behavior.

An AbleProperty.AbleEventProcessingEnabled PropertyChangeEvent is fired.

Specified by:

setAbleEventProcessingEnabled in interface AbleEventQueueManager

Parameters:

theEnabledFlag - Specify one of the following values:

Able.ProcessingEnabled_PostingEnabled

Able.ProcessingEnabled_PostingDisabled

Able.ProcessingDisabled_PostingEnabled

Able.ProcessingDisabled_PostingDisabled

Throws:

java.lang.IllegalArgumentException - If the parameter is not a valid value.

See Also:

processAbleEvent(com.ibm.able.AbleEvent), startEnabledEventProcessing()

getAbleEventProcessingEnabled

public int getAbleEventProcessingEnabled()

Description copied from interface: AbleEventQueueManager

Returns the state of asynchronous ABLE event processing.

Specified by:

getAbleEventProcessingEnabled in interface AbleEventQueueManager

Returns:

The event processing state, one of the following values:

Able.ProcessingEnabled_PostingEnabled

Able.ProcessingEnabled_PostingDisabled

Able.ProcessingDisabled_PostingEnabled

Able.ProcessingDisabled_PostingDisabled

isAbleEventPostingEnabled

public boolean isAbleEventPostingEnabled()

Description copied from interface: AbleEventQueueManager

Indicates whether asynchronous ABLE event posting is enabled or disabled.

Specified by:

isAbleEventPostingEnabled in interface AbleEventQueueManager

Returns:

true if Able events are permitted to be placed on the event queue; false otherwise.

isAbleEventProcessingEnabled

public boolean isAbleEventProcessingEnabled()

Description copied from interface: AbleEventQueueManager

Indicates whether asynchronous ABLE event processing is enabled or disabled.

Specified by:

isAbleEventProcessingEnabled in interface AbleEventQueueManager

Returns:

true if Able events are permitted to be taken from the event queue and processed; false otherwise.

flushAbleEventQueue

public void flushAbleEventQueue()

Description copied from interface: AbleEventQueueManager

Removes all events from the event queue.

Note that unless event Posting is disabled before clearing the event queue, new events may arrive on the queue as soon as it has been cleared!

Specified by:

flushAbleEventQueue in interface AbleEventQueueManager

getAbleEventQueueSize

public int getAbleEventQueueSize()

Description copied from interface: AbleEventQueueManager

Returns the number of events on the event queue.

Note that unless both event Posting and event Processing are disabled, the number may be invalid as soon as it is returned.

Specified by:

getAbleEventQueueSize in interface AbleEventQueueManager

Returns:

The number of events on the queue.

startEnabledEventProcessing

public void startEnabledEventProcessing()

Start the bean's asynchronous thread of control.

An AbleProperty.ProcessingState PropertyChangeEvent is fired.

In this thread, the bean can perform one, both, or none of these actions, depending on what is enabled:

• The bean can sleep and wake up at specific intervals, performing the processing in AbleEventQueueProcessor.processTimerEvent().
• The bean can sleep and wake up any time an asynchronous event is placed on it's internal event queue, performing the processing in AbleEventQueueProcessor.processAbleEvent(com.ibm.able.AbleEvent).

If either is enabled, the thread begins running, and the bean's state changes to AbleState.Waiting

Specified by:

startEnabledEventProcessing in interface AbleEventQueueManager

See Also:

setTimerEventProcessingEnabled(boolean), setAbleEventProcessingEnabled(int), quitEnabledEventProcessing(), init()

quitEnabledEventProcessing

public void quitEnabledEventProcessing()
                                throws AbleException

Stop the bean's asynchronous thread of control. Bean-level tracing is also stopped. The bean's state changes to AbleState.Unknown.

This method must be called synchronously; it cannot be called from the asynchronous thread itself.

An AbleProperty.ProcessingState PropertyChangeEvent is fired.

Timer event processing and ABLE event processing cease, but if event Posting is still enabled, events may still be placed on the internal event queue by other processes.

Specified by:

quitEnabledEventProcessing in interface AbleEventQueueManager

Throws:

AbleException - If an error occurs.

See Also:

startEnabledEventProcessing(), setAbleEventProcessingEnabled(int), Able.stopBeanTraceLogging(com.ibm.able.AbleBean)

suspendEnabledEventProcessing

public void suspendEnabledEventProcessing()

Temporarily suspend the bean's asynchronous thread of control. The bean's state changes to AbleState.Unknown.

This method must be called synchronously; it cannot be called from the asynchronous thread itself.

An AbleProperty.ProcessingState PropertyChangeEvent is fired.

Timer event processing and ABLE event processing cease, but if event Posting is still enabled, events may still be placed on the internal event queue by other processes.

Specified by:

suspendEnabledEventProcessing in interface AbleEventQueueManager

See Also:

resumeEnabledEventProcessing(), setAbleEventProcessingEnabled(int)

resumeEnabledEventProcessing

public void resumeEnabledEventProcessing()

Resume the bean's suspended asynchronous thread of control. The bean's state changes to AbleState.Waiting.

An AbleProperty.ProcessingState PropertyChangeEvent is fired.

Timer event processing and ABLE event processing resume if these actions are enabled.

Specified by:

resumeEnabledEventProcessing in interface AbleEventQueueManager

See Also:

suspendEnabledEventProcessing(), setAbleEventProcessingEnabled(int), setTimerEventProcessingEnabled(boolean)

restartEnabledEventProcessing

public void restartEnabledEventProcessing()
                                   throws AbleException

Restart the bean's asynchronous thread of control after the bean has moved from one system to another. The bean's state changes to AbleState.Waiting.

An AbleProperty.ProcessingState PropertyChangeEvent is fired.

Timer event processing and ABLE event processing resume if these actions are enabled.

Specified by:

restartEnabledEventProcessing in interface AbleEventQueueManager

Throws:

AbleException - If an error occurs.

See Also:

setAbleEventProcessingEnabled(int), setTimerEventProcessingEnabled(boolean)

addAbleEventListener

public void addAbleEventListener(AbleEventListener theListener)

Adds an event listener to this bean.

An AbleProperty.Listeners PropertyChangeEvent is fired.

Specified by:

addAbleEventListener in interface AbleEventListenerManager

Parameters:

theListener - An object interested in this bean.

removeAbleEventListener

public void removeAbleEventListener(AbleEventListener theListener)

Removes an event listener from this bean.

An AbleProperty.Listeners PropertyChangeEvent is fired.

Specified by:

removeAbleEventListener in interface AbleEventListenerManager

Parameters:

theListener - The object no longer interested in this bean.

removeAllAbleEventListeners

public void removeAllAbleEventListeners()

Remove all listener connections from this bean.

A single AbleProperty.Listeners PropertyChangeEvent is fired regardless of the quantity of listeners removed.

notifyAbleEventListeners

public void notifyAbleEventListeners(AbleEvent theEvent)
                              throws AbleException

Notify all registered listeners by sending the specified event via their implemented AbleEventListener.handleAbleEvent(AbleEvent) method.

Specified by:

notifyAbleEventListeners in interface AbleEventListenerManager

Parameters:

theEvent - The AbleEvent to be broadcast to all listeners. If the event is asynchronous, an unsuccessful posting will cause an exception. If the event is synchronous, unsuccessful processing will cause an exception.

Throws:

An - AbleException with the following data members provided:

1. message, a concatenated String consisting of the name and localized exception text for each errant listener
2. object, a Vector of AbleException objects whose object member is the failed listener.

AbleException - If an error occurs.

getAbleEventListeners

public java.util.Vector getAbleEventListeners()

Returns a list of all registered listeners.

Specified by:

getAbleEventListeners in interface AbleEventListenerManager

Returns:

A cloned vector of registered AbleEventListener objects.

addStateChangeListener

public void addStateChangeListener(java.beans.PropertyChangeListener theStateChangeListener)

Add a state change listener to this bean.

Parameters:

theStateChangeListener - An object interested in the state changes of this bean.

removeStateChangeListener

public void removeStateChangeListener(java.beans.PropertyChangeListener theStateChangeListener)

Remove a state change listener from this bean.

Parameters:

theStateChangeListener - The object no longer interested in the state changes of this bean.

saveToFile

public void saveToFile()
                throws java.io.IOException

Description copied from interface: AbleSerializable

Write a serialized version of this bean to the file named previously by the AbleSerializable.setFileName(java.lang.String) method, or to the default name provided by the implementor.

Specified by:

saveToFile in interface AbleSerializable

Throws:

java.io.IOException - If any error occurs.

saveToFile

public void saveToFile(java.lang.String theFileName)
                throws java.io.IOException

Write a serialized version of this bean to the specified file.

Note that a side-effect of this method is that the instance variable "fileName" is changed to the specified file name using the setFileName() method; setFileName() is used so that a property change event will fire.

Specified by:

saveToFile in interface AbleSerializable

Parameters:

theFileName - The name of the file to write.

Throws:

java.io.IOException - If any error occurs.

restoreFromFile

public AbleBean restoreFromFile()
                         throws java.lang.ClassNotFoundException,
                                java.io.IOException

Description copied from interface: AbleSerializable

Read a serialized bean from the file named previously by the setFileName() method, or from the default name provided by the implementor.

Specified by:

restoreFromFile in interface AbleSerializable

Returns:

The de-serialized bean.

Throws:

java.lang.ClassNotFoundException - If any error occurs.

java.io.IOException - If any error occurs.

restoreFromFile

public AbleBean restoreFromFile(java.lang.String theFileName)
                         throws java.lang.ClassNotFoundException,
                                java.io.IOException

Read a serialized bean from the specified file.

Note that a side-effect of this method is that the instance variable "fileName" of the restored bean is changed to the specified file name using the setFileName() method. This is because the original serialized file may have been copied to the file we are reading, so we need to make sure the file name reflects the actual file.

Specified by:

restoreFromFile in interface AbleSerializable

Parameters:

theFileName - The name of the file containing the serialized AbleBean.

Returns:

The de-serialized bean.

Throws:

java.lang.ClassNotFoundException - if any class file is not found

java.io.IOException - on any IO exception

handleAbleEvent

public void handleAbleEvent(AbleEvent theAbleEvent)
                     throws AbleException

Description copied from interface: AbleEventListener

Handles an Able event. Most implementations will check to see if the event should be processed synchronously (on the same thread as the caller) or asynchronously (on a separate thread).

Specified by:

handleAbleEvent in interface AbleEventListener

Parameters:

theAbleEvent - The event to handle.

Throws:

AbleException - If an error occurs.

processAbleEvent

public void processAbleEvent(AbleEvent theAbleEvent)
                      throws AbleException

Processes an Able event synchronously; that is, on the same thread as the caller.

This method is called by the AbleEventQueue when an event is removed from the queue for asynchronous processing. Note that this method also can be called directly from the handleAbleEvent() method described in the AbleEventListener interface when that method is given a synchronous event to handle.

Events posted to the AbleEventQueue are processed when the following conditions are all true:

• The queue's asynchronous thread of control is running.
• Able event posting is enabled, at least at the time of posting.
• An asynchronous AbleEvent is placed on the Able event queue through the handleAbleEvent() method.
• Able event processing is enabled.

In this implementation, "process an Able event" means to obtain from the event itself the name of a method in THIS class and then call that method, passing in any optional arguments, which are also obtained directly from the event. If the invoked method returns an Object, the object is simply ignored, as there is no way to return it to the caller.

Note that any exceptions are caught and logged. If the event is synchronous, the exception is converted to an AbleException and rethrown; if asynchronous, processing continues so that this method simply returns to the caller with no error indication. "Eating" exceptions from asynchronous events allows agents to continue processing asynchronously.

Specified by:

processAbleEvent in interface AbleEventQueueProcessor

Parameters:

theAbleEvent - The event to process.

Throws:

AbleException - If an error occurs.

See Also:

setAbleEventProcessingEnabled(int), startEnabledEventProcessing(), handleAbleEvent(AbleEvent)

processTimerEvent

public void processTimerEvent()
                       throws AbleException

Process a timer expiration event synchronously; that is, on the same thread as the caller.

This method is called by the AbleEventQueue whenever the following conditions are all true:

• The queue's asynchronous thread of control is running.
• Timer event processing is enabled.
• The amount of time specified in setSleepTime(long) has expired.

This base method has no default implementation. It provides only tracing.

Specified by:

processTimerEvent in interface AbleEventQueueProcessor

Throws:

AbleException - If an error occurs.

processNoEventProcessingEnabledSituation

public void processNoEventProcessingEnabledSituation()

Process the situation where neither timer nor Able event processing is enabled in the event queue, but the event queue's asynchronus thread of control has been started.

This method is called by an AbleEventQueue when the queue is neither enabled for timer processing nor Able event processing. When neither type of processing is enabled, the queue calls this method so that the event queue's container can log the situation and perhaps perform some other specialized processing. Upon return from this method the queue puts itself into a wait state which can only be interrupted by (1) turning either timer event processing or Able event processing on; (2) by suspending the thread by calling suspendEnabledEventProcessing(); or (3) by stopping the thread by calling quitEnabledEventProcessing().

In this implementation, the condition is simply logged and then the queue puts itself into a wait state.

Specified by:

processNoEventProcessingEnabledSituation in interface AbleEventQueueProcessor

sourceConnectionsOK

public boolean sourceConnectionsOK(java.util.Vector theObjectProcessList)

Check to see if the incoming connections are OK. This method is used to build the "processList" based on the connections between nodes in the graph.

Parameters:

theObjectProcessList - A Vector containing AbleBean objects already on the process list.

Returns:

true if sourceConnections are OK, false if not.