com.ibm.able
Class AbleDefaultAgent

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

All Implemented Interfaces:

AbleAgent, AbleBean, AbleBeanContainer, AbleDataBufferManager, AbleEventListener, AbleEventListenerManager, AbleEventQueueManager, AbleEventQueueProcessor, AblePropertyChangeManager, AbleSerializable, AbleUserDefinedFunctionManager, java.util.EventListener, java.beans.PropertyChangeListener, java.io.Serializable

Direct Known Subclasses:

AbleDecisionTreeClassifierAgent, AbleGeneticSearchAgent, AbleKnnClassifierAgent, AbleNaiveBayesClassifierAgent, AbleNaiveBayesClassifierAgent, AbleNeuralClassifierAgent, AbleNeuralClusteringAgent, AbleNeuralPredictionAgent, AblePetriNet, AbleRemoteDefaultAgent, AbleRuleAgent, AbleRuleBase, AbleScriptAgent, BaseAutotuneAdaptor, BaseAutotuneController, SimpleAbleAgent

public class AbleDefaultAgent

extends AbleObject

implements AbleAgent, java.beans.PropertyChangeListener, java.io.Serializable

The AbleDefaultAgent class provides an ABLE agent which can contain other agents and beans and supports event connections to other agents and beans. Most ABLE agents extend this class and override methods as necessary.

When process() is called on an agent, process is called on each bean in its processList, which is a subset of contained beans with dataflow enabled in connection sequence. Methods such as quitAll() and resumeAll() apply to all contained beans. The AbleDefaultAgent implementation:

1. Can contain at most one datasource with data flow enabled. When a new data source is enabled, the prior datasource is disabled.
2. Counts the number of AbleEvent.EOF events received from its active data source for learning agents.
3. Has an inputBuffer and an outputBuffer used when dataflow is enabled. The inputBuffer provides the input to the first bean in the processing list, and the last bean in the processing list provides the agent's outputBuffer.

Property change events are fired by the following methods:

setActiveDataSource(boolean) sends an AbleProperty.ActiveDataSource event.

setProcessList(java.util.Vector) sends an AbleProperty.ProcessList event.

addBean(com.ibm.able.AbleBean) sends an AbleProperty.Beans event, and, if the added bean is a active data source, an AbleProperty.DataFlowEnabled event.

removeBean(com.ibm.able.AbleBean) sends an AbleProperty.Beans event.

addUserDefinedFunction(com.ibm.able.AbleUserDefinedFunction) sends an AbleProperty.UserDefinedFunction event.

removeUserDefinedFunction(java.lang.String, int) sends an AbleProperty.UserDefinedFunction event.

setUserDefinedFunctions(java.util.Hashtable) sends an AbleProperty.UserDefinedFunction event.

setProcessList(java.util.Vector) sends an AbleProperty.ProcessList event.

See Also:

Serialized Form

Field Summary

protected boolean	activeDataSource Indicates if the agent contains an active data source.
static java.lang.String	defaultName The default name for an AbleDefaultAgent agent.
protected java.util.Vector	eventConnections A list of AbleEventConnection objects managed by this agent.
protected java.util.Hashtable	myBeans The list of AbleBean objects contained by this agent.
protected long	numEpochs An agent that contains a data source listens for AbleEvent.EOF events.
protected java.util.Vector	processList The list of objects to be processed in order during a process() call.
protected boolean	processListOK Indicates whether the processList needs to be computed.
protected java.util.Hashtable	userDefinedFunctions The list of registered AbleUserDefinedFunction objects managed by this agent.

Fields inherited from class com.ibm.able.AbleObject

changed, chgSupport, comment, dataFlowEnabled, destBufferConnections, eventQueue, fileName, inputBuffer, listeners, logger, name, outputBuffer, parent, properties, propertyConnectionMgr, sourceBufferConnections, state, stateChgSupport, trace

Constructor Summary

AbleDefaultAgent()
Construct an AbleDefaultAgent instance.

AbleDefaultAgent(java.lang.String theName)
Construct an AbleDefaultAgent with the specified name.

AbleDefaultAgent(java.lang.String theName, java.lang.String theComment)
Construct an AbleDefaultAgent with the specified name and comment.

Method Summary

void	addBean(AbleBean theAbleBean) Adds a bean to this container/agent.
static void	addBeans(AbleBeanContainer container, AbleBean[] theBeans) A convenience method to add a list of beans which calls addBean(AbleBean).
void	addEventConnection(AbleEventConnection theConnection) Adds an event connection.
void	addUserDefinedFunction(AbleUserDefinedFunction theUserDefinedFunction) Adds a specific user-defined function to the master list of user-defined functions.
protected void	buildProcessList() Examine the list of contained beans myBeans for dataflow connections, building a sequential processing list.
protected java.lang.String	clsNm() Returns the name of this class for easy inclusion in exceptions.
boolean	containsBean(AbleBean theAbleBean) Indicates if a specific bean is present.
boolean	containsBean(java.lang.String theName) Indicates if a bean with a specific name is present.
boolean	containsUserDefinedFunction(java.lang.String theUserDefinedFunctionName, int theArity) Indicates if the master list of user-defined functions contains a user-defined function with the specified name and arity.
protected void	debugTrace(java.lang.String theMessage) Log a trace message at level Able.TRC_LOW if Able.Debug is enabled.
static java.lang.String	generateUniqueName(AbleBeanContainer container, AbleBean bean) Generate a unique bean name by appending an underscore and an integer.
AbleBean	getBean(java.lang.String theName) Returns a bean with a specific name from this container.
java.util.Vector	getBeans() Returns a list of all contained beans.
AbleDataSource	getDataSource() Returns the current active DataSource from the contained beans, null if none.
java.util.Vector	getEventConnections() Returns event connections used by this agent.
long	getNumEpochs() Returns the number of training epochs, which is the number of times an active data source has had all its records processed.
java.util.Vector	getProcessList() Returns the sequential processing list for data buffer processing.
AbleUserDefinedFunction	getUserDefinedFunction(java.lang.String theUserDefinedFunctionName, int theArity) Returns the specified user-defined function
java.util.Hashtable	getUserDefinedFunctions() Returns the complete master list of user-defined functions registered with this function manager.
void	handleAbleEvent(AbleEvent theAbleEvent) Handles an Able event.
void	init() Initialize the agent.
void	initAllBeans() Initialize all contained beans, and this agent instance itself.
java.lang.Object	invokeUserDefinedFunction(java.lang.String theUserDefinedFunctionName, java.lang.Object[] theArgs) Invokes the actual method that the named user-defined function represents, passing in the array of argument objects.
boolean	isActiveDataSource() Indicates if this agent has an active data source.
void	process() Performs the main, synchronous, standard processing function performed by this bean.
void	propertyChange(java.beans.PropertyChangeEvent theEvent) Handle a propertyChange event.
void	quitAll() Quits all forms of processing for this bean.
void	quitEnabledEventProcessing() Stop the agent's asynchronous thread of control.
void	removeAllBeans() Removes all beans from this container.
void	removeAllConnections() Removes all Property, Buffer, and Event connections.
void	removeAllEventConnections() Remove all event connections.
void	removeBean(AbleBean theAbleBean) Removes a bean from this container, and sets the bean's parent to null.
void	removeBean(java.lang.String theName) A convenience method to remove a bean by name which calls removeBean(AbleBean).
static void	removeBeans(AbleBeanContainer container, AbleBean[] theBeans) A convenience method to remove a list of beans which calls removeBean(AbleBean).
void	removeEventConnection(AbleEventConnection theConnection) Removes an event connection.
void	removeUserDefinedFunction(java.lang.String theUserDefinedFunctionName, int theArity) Removes the named user-defined function from the master list of user-defined functions.
void	reset() Reset the agent to its "initialized" state.
void	resetAllBeans() Reset all beans in this container agent as required by AbleBeanContainer.
void	resumeAll() Resumes all of the bean's suspended asynchronous threads of control.
void	setActiveDataSource(boolean theState) Sets the flag indicating if this agent contains an active data source.
void	setDataFlowEnabled(boolean theDataFlowEnabledState) Sets the data flow processing state of the bean.
void	setProcessList(java.util.Vector theProcessList) Set the sequential list of beans to process.
void	setUserDefinedFunctions(java.util.Hashtable theUserDefinedFunctions) Sets the complete master list of user-defined functions for this function manager.
void	suspendAll() Temporarily suspends all of the bean's asynchronous threads of control.

Methods inherited from class com.ibm.able.AbleObject

addAbleEventListener, addDestBufferConnection, addPropertyChangeListener, addPropertyConnection, addSourceBufferConnection, addStateChangeListener, dataChanged, firePropertyChange, flushAbleEventQueue, getAbleEventListeners, getAbleEventProcessingEnabled, getAbleEventQueueSize, getComment, getDestBufferConnections, getFileName, getInputBuffer, getInputBuffer, getInputBufferAsString, getInputBufferAsStringArray, getInputBufferContents, getLogger, getName, getOutputBuffer, getOutputBuffer, getOutputBufferAsString, getOutputBufferAsStringArray, getOutputBufferContents, getParent, getProperties, getProperty, getPropertyChangeListeners, getPropertyConnectionManager, getSleepTime, getSourceBufferConnections, getState, getTraceLogger, hasInputBuffer, hasOutputBuffer, init, isAbleEventPostingEnabled, isAbleEventProcessingEnabled, isChanged, isConnectable, isDataFlowEnabled, isTimerEventProcessingEnabled, notifyAbleEventListeners, process, processAbleEvent, processBufferConnections, processNoEventProcessingEnabledSituation, processTimerEvent, removeAbleEventListener, removeAllAbleEventListeners, removeAllBufferConnections, removeAllPropertyConnections, removeDestBufferConnection, removeProperty, removePropertyChangeListener, removePropertyConnection, removeSourceBufferConnection, removeStateChangeListener, restartEnabledEventProcessing, restoreFromFile, restoreFromFile, restoreFromSerializedFile, restoreFromStream, resumeEnabledEventProcessing, saveToFile, saveToFile, setAbleEventProcessingEnabled, setChanged, setComment, setFileName, setInputBuffer, setInputBuffer, setLogger, setName, setOutputBuffer, setOutputBuffer, setParent, setProperties, setProperty, setSleepTime, setState, setTimerEventProcessingEnabled, setTraceLogger, sourceConnectionsOK, startEnabledEventProcessing, suspendEnabledEventProcessing

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.ibm.able.AbleBean

getComment, getLogger, getName, getParent, getProperties, getProperty, getState, getTraceLogger, init, isChanged, process, removeProperty, setChanged, setComment, setLogger, setName, setParent, setProperties, setProperty, setState, setTraceLogger

Methods inherited from interface com.ibm.able.AbleDataBufferManager

addDestBufferConnection, addSourceBufferConnection, getDestBufferConnections, getInputBuffer, getInputBuffer, getInputBufferAsString, getInputBufferAsStringArray, getInputBufferContents, getOutputBuffer, getOutputBuffer, getOutputBufferAsString, getOutputBufferAsStringArray, getOutputBufferContents, getSourceBufferConnections, hasInputBuffer, hasOutputBuffer, isConnectable, isDataFlowEnabled, processBufferConnections, removeAllBufferConnections, removeDestBufferConnection, removeSourceBufferConnection, setInputBuffer, setInputBuffer, setOutputBuffer, setOutputBuffer

Methods inherited from interface com.ibm.able.AbleEventListenerManager

addAbleEventListener, dataChanged, getAbleEventListeners, notifyAbleEventListeners, removeAbleEventListener

Methods inherited from interface com.ibm.able.AbleEventQueueManager

flushAbleEventQueue, getAbleEventProcessingEnabled, getAbleEventQueueSize, getSleepTime, isAbleEventPostingEnabled, isAbleEventProcessingEnabled, isTimerEventProcessingEnabled, restartEnabledEventProcessing, resumeEnabledEventProcessing, setAbleEventProcessingEnabled, setSleepTime, setTimerEventProcessingEnabled, startEnabledEventProcessing, suspendEnabledEventProcessing

Methods inherited from interface com.ibm.able.AbleEventQueueProcessor

processAbleEvent, processNoEventProcessingEnabledSituation, processTimerEvent

Methods inherited from interface com.ibm.able.AblePropertyChangeManager

addPropertyChangeListener, addPropertyConnection, getPropertyChangeListeners, getPropertyConnectionManager, removeAllPropertyConnections, removePropertyChangeListener, removePropertyConnection

Methods inherited from interface com.ibm.able.AbleSerializable

getFileName, restoreFromFile, restoreFromFile, saveToFile, saveToFile, setFileName

Methods inherited from interface com.ibm.able.AbleBeanContainer

getName

Field Detail

defaultName

public static final java.lang.String defaultName

The default name for an AbleDefaultAgent agent.

myBeans

protected java.util.Hashtable myBeans

The list of AbleBean objects contained by this agent.

activeDataSource

protected boolean activeDataSource

Indicates if the agent contains an active data source. This field is initialized to false.

eventConnections

protected java.util.Vector eventConnections

A list of AbleEventConnection objects managed by this agent.

processList

protected transient java.util.Vector processList

The list of objects to be processed in order during a process() call.

processListOK

protected transient boolean processListOK

Indicates whether the processList needs to be computed. This field is initialized to false, indicating the list is to be computed before processing or access.

numEpochs

protected long numEpochs

An agent that contains a data source listens for AbleEvent.EOF events. It increments the epoch count for each such event. This is used by machine learning agents. This field is initialized to zero (0).

userDefinedFunctions

protected java.util.Hashtable userDefinedFunctions

The list of registered AbleUserDefinedFunction objects managed by this agent.

Constructor Detail

AbleDefaultAgent

public AbleDefaultAgent()
                 throws AbleException

Construct an AbleDefaultAgent instance.

Throws:

AbleException - If an error occurs.

AbleDefaultAgent

public AbleDefaultAgent(java.lang.String theName)
                 throws AbleException

Construct an AbleDefaultAgent with the specified name.

Parameters:

theName - The name of the agent.

Throws:

AbleException - If an error occurs.

AbleDefaultAgent

public AbleDefaultAgent(java.lang.String theName,
                        java.lang.String theComment)
                 throws AbleException

Construct an AbleDefaultAgent with the specified name and comment.

Parameters:

theName - The name of the agent.

theComment - A comment for the agent.

Throws:

AbleException - If an error occurs.

Method Detail

setActiveDataSource

public void setActiveDataSource(boolean theState)
                         throws AbleException

Description copied from interface: AbleAgent

Sets the flag indicating if this agent contains an active data source.

Specified by:

setActiveDataSource in interface AbleAgent

Parameters:

theState - The state is true if the agent contains an active data source, and false otherwise.

Throws:

AbleException - If an error occurs.

isActiveDataSource

public boolean isActiveDataSource()
                           throws AbleException

Description copied from interface: AbleAgent

Indicates if this agent has an active data source.

Specified by:

isActiveDataSource in interface AbleAgent

Returns:

true if agent contains an active data source; false otherwise.

Throws:

AbleException - If an error occurs.

getDataSource

public AbleDataSource getDataSource()
                             throws AbleException

Description copied from interface: AbleAgent

Returns the current active DataSource from the contained beans, null if none.

Specified by:

getDataSource in interface AbleAgent

Returns:

The current active data source

Throws:

AbleException - If an error occurs.

getEventConnections

public java.util.Vector getEventConnections()

Description copied from interface: AbleAgent

Returns event connections used by this agent.

Specified by:

getEventConnections in interface AbleAgent

Returns:

Vector of AbleEventConnection objects. If there are no event connections, a Vector of 0 elements will be returned.

See Also:

AbleEventConnection

addEventConnection

public void addEventConnection(AbleEventConnection theConnection)
                        throws AbleException

Description copied from interface: AbleAgent

Adds an event connection.

Specified by:

addEventConnection in interface AbleAgent

Parameters:

theConnection - The connection to add.

Throws:

AbleException - If an error occurs.

removeEventConnection

public void removeEventConnection(AbleEventConnection theConnection)
                           throws AbleException

Description copied from interface: AbleAgent

Removes an event connection.

Specified by:

removeEventConnection in interface AbleAgent

Parameters:

theConnection - The connection to remove.

Throws:

AbleException - If an error occurs. The implementor may choose to throw an exception if the connection does not exist.

removeAllEventConnections

public void removeAllEventConnections()
                               throws AbleException

Description copied from interface: AbleAgent

Remove all event connections.

Specified by:

removeAllEventConnections in interface AbleAgent

Throws:

AbleException - If an error occurs.

setProcessList

public void setProcessList(java.util.Vector theProcessList)
                    throws AbleException

Description copied from interface: AbleAgent

Set the sequential list of beans to process. While the agent will maintain this list as beans are added and removed, it may be that some applications would prefer to set the list directly whether to control the overhead, or explicitly sequence the list. For example, the active datasource may be connected to three beans. After the datasource is processed, the sequence in which those three beans are processed is arbitrary. It may be that your agent would want a specific sequence, and in that case it would be appropriate to use this method rather than rely on the default sequence.

A property change event is fired to registered listeners.

Specified by:

setProcessList in interface AbleAgent

Parameters:

theProcessList - The list of beans in the sequence to be processed.

Throws:

AbleException - If an error occurs.

getProcessList

public java.util.Vector getProcessList()
                                throws AbleException

Description copied from interface: AbleAgent

Returns the sequential processing list for data buffer processing. If there is an active datasource, it is the first bean in the list.

Specified by:

getProcessList in interface AbleAgent

Returns:

The ordered list of beans to process.

Throws:

AbleException - If an error occurs.

getNumEpochs

public long getNumEpochs()
                  throws AbleException

Description copied from interface: AbleAgent

Returns the number of training epochs, which is the number of times an active data source has had all its records processed. An agent's reset method should set this value back to zero. An agent which does require epoch count should return zero.

Specified by:

getNumEpochs in interface AbleAgent

Returns:

The number of epochs.

Throws:

AbleException - If an error occurs.

removeAllConnections

public void removeAllConnections()
                          throws AbleException

Removes all Property, Buffer, and Event connections. Both Event connections and listeners are removed.

Specified by:

removeAllConnections in interface AbleBean

Overrides:

removeAllConnections in class AbleObject

Throws:

AbleException - If an error occurs.

See Also:

AbleObject.removeAllAbleEventListeners(), AbleObject.removeAllBufferConnections(), AbleObject.removeAllPropertyConnections()

reset

public void reset()
           throws AbleException

Reset the agent to its "initialized" state.

In this implementation, the reset() call is propagated to all DataFlowEnabled AbleBeans contained within this agent. The property numEpochs is reset to 0.

Specified by:

reset in interface AbleBean

Overrides:

reset in class AbleObject

Throws:

AbleException - If an error occurs when resetting a contained bean. All errors are collected and insert into the exception so that one bean's error does not prevent another from being reset.

See Also:

AbleBean.reset()

resetAllBeans

public void resetAllBeans()
                   throws AbleException

Reset all beans in this container agent as required by AbleBeanContainer. Since this implementation of reset itself performs the same function, it simply calls reset.

Specified by:

resetAllBeans in interface AbleBeanContainer

Throws:

AbleException - If an error occurs.

See Also:

reset(), AbleBeanContainer.resetAllBeans()

initAllBeans

public void initAllBeans()
                  throws AbleException

Initialize all contained beans, and this agent instance itself. The agent state changes only if all contained beans initialize without throwing an exception.

Specified by:

initAllBeans in interface AbleBeanContainer

Throws:

AbleException - From the first bean that fails to initialize.

init

public void init()
          throws AbleException

Initialize the agent. This implementation simply calls super.init() to set the agent state.

Contained beans are not initialized explicitly because some agents manage their contained beans directly. To initialize all contained beans, use initAllBeans().

Specified by:

init in interface AbleBean

Overrides:

init in class AbleObject

Throws:

AbleException

See Also:

AbleObject.init()

process

public void process()
             throws AbleException

Performs the main, synchronous, standard processing function performed by this bean. An AbleEvent.DATACHANGED event is propagated to registered listeners.

In this implementation, a single processing step is performed by walking through the process list and calling the process() method on each DataFlowEnabled AbleBean contained within this agent. If the agent itself is DataFlowEnabled, its inputBuffer is passed to the first bean in the process list, and the outputBuffer from the last bean in the process list populates the agent's outputBuffer.

Specified by:

process in interface AbleBean

Overrides:

process in class AbleObject

Throws:

AbleException - If an error occurs. Errors from each contained bean are accumulated.

See Also:

AbleObject.inputBuffer, AbleObject.outputBuffer, AbleBean.process()

setDataFlowEnabled

public void setDataFlowEnabled(boolean theDataFlowEnabledState)

Description copied from interface: AbleDataBufferManager

Sets the data flow processing state of the bean. A bean implementing AbleBeanContainer should recalculate its processing list.

Specified by:

setDataFlowEnabled in interface AbleDataBufferManager

Overrides:

setDataFlowEnabled in class AbleObject

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.

quitEnabledEventProcessing

public void quitEnabledEventProcessing()
                                throws AbleException

Stop the agent's asynchronous thread of control. The bean's state changes to AbleState.Unknown.

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.

In this implementation, the quit request is propagated to all AbleBean objects contained within this agent, since it doesn't make sense to quit this object without quitting all the contained objects, too.

Specified by:

quitEnabledEventProcessing in interface AbleEventQueueManager

Overrides:

quitEnabledEventProcessing in class AbleObject

Throws:

AbleException - If an error occurs. While the quit request is propagated to all beans, any errors are accumlated so that each bean is quit.

See Also:

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

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

Overrides:

quitAll in class AbleObject

Throws:

AbleException

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

Overrides:

suspendAll in class AbleObject

Throws:

AbleException

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

Overrides:

resumeAll in class AbleObject

Throws:

AbleException

handleAbleEvent

public void handleAbleEvent(AbleEvent theAbleEvent)
                     throws AbleException

Handles an Able event. If the event is of type AbleEvent.EOF, the numEpochs parameter is incrememented.

In this implementation, special processing occurs for EOF on the active data source. All other events are passed up to the superclass (AbleObject) for processing.

Specified by:

handleAbleEvent in interface AbleEventListener

Overrides:

handleAbleEvent in class AbleObject

Parameters:

theAbleEvent - The event to handle.

Throws:

AbleException - If an error occurs.

addBean

public void addBean(AbleBean theAbleBean)
             throws AbleException

Adds a bean to this container/agent. The following special processing is performed:

1. If the bean to be added is null or is already contained in this agent, this action is ignored.
2. If there is already a bean with the same name, a unique name will be generated by appending an underscore and integer. The integer will be start with a value of 1 and be incremented until a unique name is found. The bean will be renamed.
3. This agent will listen for property changes sent from the contained bean.
4. If the bean is an AbleDataSource, an event connection between the bean and this agent will be constructed. Only one data source can be data flow enabled in a container at one time, so if the added bean is an an active data source, a previously active contained data source will be made inactive.
5. The processList will be recalculated on its next access or use.

Note that if the bean to be added has a current parent, the bean will be removed from that parent because an ABLE bean can have only one parent at a time. This method will set the specified bean's parent to be this agent.

Specified by:

addBean in interface AbleBeanContainer

Parameters:

theAbleBean - The bean to be added to this container.

Throws:

AbleException - If an error occurs.

generateUniqueName

public static java.lang.String generateUniqueName(AbleBeanContainer container,
                                                  AbleBean bean)

Generate a unique bean name by appending an underscore and an integer. For example, if a bean named myBean is the only bean contained, return myBean_1 if the container includes beans named myBean and myBean_1, adding a bean named myBean will return myBean_2.

Parameters:

container - The bean container which contains the names in use.

bean - The bean to be added to this container.

Returns:

A name which is not the name of a bean currently present in the container.

removeBean

public void removeBean(AbleBean theAbleBean)
                throws AbleException

Removes a bean from this container, and sets the bean's parent to null. The following special processing is performed:

1. If the bean to be removed is null or is not contained in this agent, this action is ignored.
2. A property change event will be fired, causing the property listener between the bean and the container to be removed.
3. Any existing event connection between the bean and this agent will be removed.
4. The processList will be recalculated on its next access or use.

Specified by:

removeBean in interface AbleBeanContainer

Parameters:

theAbleBean - A bean that is to be removed from this container.

Throws:

AbleException - If an error occurs.

removeBean

public void removeBean(java.lang.String theName)
                throws AbleException

A convenience method to remove a bean by name which calls removeBean(AbleBean).

Specified by:

removeBean in interface AbleBeanContainer

Parameters:

theName - A name of a bean that is to be removed from this container.

Throws:

AbleException - If an error occurs.

removeBeans

public static void removeBeans(AbleBeanContainer container,
                               AbleBean[] theBeans)
                        throws AbleException

A convenience method to remove a list of beans which calls removeBean(AbleBean).

Parameters:

container - The container from which beans are to be removed.

theBeans - A list of beans to be removed from the container.

Throws:

AbleException - If an error occurs.

addBeans

public static void addBeans(AbleBeanContainer container,
                            AbleBean[] theBeans)
                     throws AbleException

A convenience method to add a list of beans which calls addBean(AbleBean).

Parameters:

container - The container to which beans are to be added.

theBeans - A list of beans to be added to the container.

Throws:

AbleException - If an error occurs.

removeAllBeans

public void removeAllBeans()
                    throws AbleException

Description copied from interface: AbleBeanContainer

Removes all beans from this container. Sets each bean's parent to null.

Specified by:

removeAllBeans in interface AbleBeanContainer

Throws:

AbleException - If an error occurs.

containsBean

public boolean containsBean(AbleBean theAbleBean)

Description copied from interface: AbleBeanContainer

Indicates if a specific bean is present. The determination is done by using AbleBean equality.

Specified by:

containsBean in interface AbleBeanContainer

Parameters:

theAbleBean - A bean that to find in this container.

Returns:

true if the specific bean is present, false otherwise.

containsBean

public boolean containsBean(java.lang.String theName)

Description copied from interface: AbleBeanContainer

Indicates if a bean with a specific name is present. The determination is done by comparing bean names.

Specified by:

containsBean in interface AbleBeanContainer

Parameters:

theName - The specific name of a bean to find in this container.

Returns:

true if the named bean is present, false otherwise.

getBean

public AbleBean getBean(java.lang.String theName)

Description copied from interface: AbleBeanContainer

Returns a bean with a specific name from this container.

Specified by:

getBean in interface AbleBeanContainer

Parameters:

theName - The specific name of a bean to be returned.

Returns:

A reference to the found bean, or null if the bean is not contained.

getBeans

public java.util.Vector getBeans()

Description copied from interface: AbleBeanContainer

Returns a list of all contained beans.

Specified by:

getBeans in interface AbleBeanContainer

Returns:

All contained beans. Note that the result may be empty, and that there is no implied order to the list elements.

addUserDefinedFunction

public void addUserDefinedFunction(AbleUserDefinedFunction theUserDefinedFunction)

Description copied from interface: AbleUserDefinedFunctionManager

Adds a specific user-defined function to the master list of user-defined functions.

Specified by:

addUserDefinedFunction in interface AbleUserDefinedFunctionManager

Parameters:

theUserDefinedFunction - The user-defined function to be added to the master list.

removeUserDefinedFunction

public void removeUserDefinedFunction(java.lang.String theUserDefinedFunctionName,
                                      int theArity)

Description copied from interface: AbleUserDefinedFunctionManager

Removes the named user-defined function from the master list of user-defined functions.

Specified by:

removeUserDefinedFunction in interface AbleUserDefinedFunctionManager

Parameters:

theUserDefinedFunctionName - The name of the user-defined function to be removed from the master list.

theArity - The number of arguments expected by the named function.

containsUserDefinedFunction

public boolean containsUserDefinedFunction(java.lang.String theUserDefinedFunctionName,
                                           int theArity)

Description copied from interface: AbleUserDefinedFunctionManager

Indicates if the master list of user-defined functions contains a user-defined function with the specified name and arity.

Specified by:

containsUserDefinedFunction in interface AbleUserDefinedFunctionManager

Parameters:

theUserDefinedFunctionName - The name of a user-defined function that might be in the master list.

theArity - The number of arguments expected by the named function.

Returns:

true if a user-defined function with the specified name and number of arguments exists in the master list; false otherwise.

getUserDefinedFunction

public AbleUserDefinedFunction getUserDefinedFunction(java.lang.String theUserDefinedFunctionName,
                                                      int theArity)

Description copied from interface: AbleUserDefinedFunctionManager

Returns the specified user-defined function

Specified by:

getUserDefinedFunction in interface AbleUserDefinedFunctionManager

Parameters:

theUserDefinedFunctionName - The name of a user-defined function that might be in the master list.

theArity - The number of arguments expected by the named function.

Returns:

The specified user defined function object; null if not found.

invokeUserDefinedFunction

public java.lang.Object invokeUserDefinedFunction(java.lang.String theUserDefinedFunctionName,
                                                  java.lang.Object[] theArgs)
                                           throws AbleException,
                                                  java.lang.NoSuchMethodException,
                                                  java.lang.reflect.InvocationTargetException,
                                                  java.lang.IllegalAccessException,
                                                  java.lang.SecurityException

Description copied from interface: AbleUserDefinedFunctionManager

Invokes the actual method that the named user-defined function represents, passing in the array of argument objects.

Specified by:

invokeUserDefinedFunction in interface AbleUserDefinedFunctionManager

Parameters:

theUserDefinedFunctionName - The name of the user-defined function containing an encapsulated method.

theArgs - An array of arguments expected by the encapsulated method.

Returns:

The invoked method's return value. This may be null. If the invoked method returns a primitive, the primitive is turned into a corresponding Object; for example, a double becomes a Double.

Throws:

AbleException - If any other error occurs.

java.lang.IllegalAccessException - If the method is not public or otherwise accessible.

java.lang.reflect.InvocationTargetException - If an exception was thrown by the invoked method.

java.lang.NoSuchMethodException - If the method or method signature is not defined in the encapsulated source object.

java.lang.SecurityException - If the invoker lacks authority to invoke the method.

setUserDefinedFunctions

public void setUserDefinedFunctions(java.util.Hashtable theUserDefinedFunctions)

Description copied from interface: AbleUserDefinedFunctionManager

Sets the complete master list of user-defined functions for this function manager.

Specified by:

setUserDefinedFunctions in interface AbleUserDefinedFunctionManager

Parameters:

theUserDefinedFunctions - A list of AbleUserDefinedFunction objects. This list completely replaces the current list. The input list is cloned.

getUserDefinedFunctions

public java.util.Hashtable getUserDefinedFunctions()

Description copied from interface: AbleUserDefinedFunctionManager

Returns the complete master list of user-defined functions registered with this function manager.

Specified by:

getUserDefinedFunctions in interface AbleUserDefinedFunctionManager

Returns:

A copy of the list of all registered UserDefinedFunction objects.

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent theEvent)

Handle a propertyChange event. Events which cause special processing are:

1. An AbleProperty.DataFlowEnabled event, which occurs when data flow is enabled, causes any other AbleDataSource objects contained to set dataflow off, and will cause the process list to be reconstructed on its next use or access.
2. An AbleProperty.Name event, which occurs when a bean name is changed, will cause this parent to update its list of contained beans which uses the name as the key. If the new name is not unique, a unique name is generated.
3. An AbleProperty.SourceBufferConnections event, which occurs a buffer connection is added or deleted, will cause the process list to be reconstructed on its next use or access.

Specified by:

propertyChange in interface java.beans.PropertyChangeListener

Parameters:

theEvent - The property change event.

buildProcessList

protected void buildProcessList()
                         throws AbleException

Examine the list of contained beans myBeans for dataflow connections, building a sequential processing list. Lists all datasource objects first starting with the one enabled for data flow, then all data buffer-connected objects in sequence, regardless of if they are on or off.

Throws:

AbleException - If an error occurs.

debugTrace

protected void debugTrace(java.lang.String theMessage)

Log a trace message at level Able.TRC_LOW if Able.Debug is enabled. Take no action if disabled.

Parameters:

theMessage - A String containing text to be traced.

clsNm

protected java.lang.String clsNm()

Returns the name of this class for easy inclusion in exceptions.

Returns:

The name of this class.