Functionality of the EngineClientBean

The EngineClientBean provides a number of common methods and properties, like “host”, “port”, “verbose”, “connectionPollingInterval” and “beanConnected”. The full names are PROPERTY_HOST, PROPERTY_PORT, PROPERTY_VERBOSE, PROPERTY_CONNECTION_POLLING_INTERVAL and PROPERTY_BEAN_CONNECTED.

Each bean is capable of making its own connection to an event correlator and maintains that connection. That is, it can monitor that the connection is live throughout, and flag if the connection is dropped. This can occur if the network connection is lost or the remote correlator is terminated.

Changes to the value of the “host” or “port” properties will cause the bean to attempt to re-connect to an event correlator running on a new host/port. This re-connection will happen immediately if the bean was connected at the time of the property change, but will happen later in a “lazy” fashion if there was no existing connection at the time of the property change.

Beans also maintain a Boolean bound property called “beanConnected”. The value will be set to true following a successful connection to an Engine, and to false at disconnection. Once connected, a background thread will periodically ping the remote Engine. This background thread will also maintain the value of the “beanConnected”property each time it tests the connection.

Warning: The bound properties supported by this bean will notify all registered listeners from within a synchronized block. Listeners should not invoke methods that would wait for another thread to complete a call into this bean. For example, calls to System.exit(int) would cause a deadlock situation when the shutdown handler thread attempts to call the disconnect() method. Listeners on the “events” property or EventListeners added to Consumers may not re-enter the bean, even directly. When registering a consumer, if the async parameter is supplied and set to true, then the consumer’s listeners are called asynchronously – events are queued and delivered on a separate thread, and the EventListeners are permitted to call the EngineClientBean.

(See addConsumers in the Javadoc). Note that asynchronous consumers may be called after having been disconnected.

The EngineClientBean inherits the following methods:

void setHost(java.lang.String newHostValue) - Setter for the “host” property. This is the name of the host on which the correlator to be monitored is running. Changing this property will cause any existing connection to be lost. If there was an existing connection, then a new connection will be created.

void setPort(int newPortValue) - Setter for the “port” property. This is the port number on which the correlator to be monitored is listening. Changing this property will cause any existing connection to be lost. If there was an existing connection, then a new connection will be created.

void connectNow() - Manually request that the bean connects to the remote event correlator (or ‘server’). Repeated calls are permitted, and attempting to connect a bean that is already connected is identical to calling the pingServer() method. Note that other methods can implicitly cause a connection to be created.

void disconnect() - This method must always be called before quitting the program that is using the bean. If the method is not called, then an event correlator (or ‘engine’) could be left in a state where it is attempting to send events to a non-existent client (or ‘consumer’).

java.lang.String getHost() - Get the name of the host to be connected to. This is the name of the host on which the correlator to be monitored is running.

boolean getBeanConnected() - Get the “beanConnected”property’s value. This is the status of the bean - connected, or not connected. It indicates if the Bean has a valid instance of the underlying RPC interface.

public void setVerbose(boolean newVerboseValue) - Setter for the verbose property. When verbose is set to true, some methods (in subclasses) will print progress messages on stdout.

public boolean getVerbose() - Getter for the verbose property. When verbose is set to true, some methods (in subclasses) will print progress messages on stdout.

void setConnectionPollingInterval(int milliseconds) - Set the polling interval (in milliseconds) for the internal connection test thread. If the parameter is negative, then the default value will be used instead.

void pingServer() - Manually test if the remote engine process is alive and responding to client requests. This method makes a no-arg, void return, method call on the client interface of the engine. If a connection is not yet established, this method will request a connection. In the event that a connection cannot be established, or an error during the ping, an EngineException will be raised.

void addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) - Add a property change listener for a specific named property.

void removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) - Remove a property change listener for a specific named property.

Note: Starting with Release 3.0 the following EngineClientBean methods have been moved to the GenericComponentManagementBean; for more information see GenericComponentManagementBean.