com.apama.engine.beans.interfaces
Interface ReceiveConsumerOperationsInterface

All Known Subinterfaces:
EngineClientInterface
All Known Implementing Classes:
EngineClientBean

public interface ReceiveConsumerOperationsInterface

ReceiveConsumerOperationsInterface is an interface providing the ability to create consumers for receiving events from an Apama server component.


Field Summary
static java.lang.String PROPERTY_ALL_CONSUMERS_CONNECTED
          The string name of the bound property that is used to indicate if the bean and all individual named consumers are connected (typically "allConsumersConnected", but this constant should be used to be sure).
 
Method Summary
 ConsumerOperationsInterface addConsumer(java.lang.String uniqueName, java.lang.String... channels)
          Add a new uniquely-named consumer that listens on a specified set of channels.
 ConsumerOperationsInterface addConsumer(java.lang.String uniqueName, java.lang.String[] channels, boolean disconnectSlow)
          Add a new uniquely-named consumer that listens on a specified set of channels.
 ConsumerOperationsInterface addConsumer(java.lang.String uniqueName, java.lang.String[] channels, boolean disconnectSlow, boolean async)
          Add a new uniquely-named consumer that listens on a specified set of channels.
 ConsumerOperationsInterface[] getAllConsumers()
          Get all existing uniquely-named consumers.
 ConsumerOperationsInterface getConsumer(java.lang.String uniqueName)
          Get an existing uniquely-named consumer.
 boolean isAllConsumersConnected()
          Determine if the bean and existing uniquely-named consumers are connected.
 void removeAllConsumers()
          Remove and disconnect all existing uniquely-named consumers.
 void removeConsumer(java.lang.String uniqueName)
          Remove and disconnect any existing uniquely-named consumer.
 

Field Detail

PROPERTY_ALL_CONSUMERS_CONNECTED

static final java.lang.String PROPERTY_ALL_CONSUMERS_CONNECTED
The string name of the bound property that is used to indicate if the bean and all individual named consumers are connected (typically "allConsumersConnected", but this constant should be used to be sure).

Note that this property applies only to individual named consumers, and NOT to the single receiver. From 5.0 onwards this property also takes into account whether the bean itself is connected, and will always be false when the bean is not connected, even if no consumers were added.

See Also:
Constant Field Values
Method Detail

addConsumer

ConsumerOperationsInterface addConsumer(java.lang.String uniqueName,
                                        java.lang.String... channels)
                                        throws EngineException
Add a new uniquely-named consumer that listens on a specified set of channels. The consumer will default to not disconnecting if slow and being synchronous (i.e. cannot re-enter the EngineClientBean)

Parameters:
uniqueName - the unique name for the new consumer.
channels - The list of channels on which the consumer should receive events. Must be non-null, and contain no null elements.
Returns:
the new consumer.
Throws:
EngineException - if the consumer cannot be added (e.g. if the name is not unique), or if the channels parameter is invalid.

addConsumer

ConsumerOperationsInterface addConsumer(java.lang.String uniqueName,
                                        java.lang.String[] channels,
                                        boolean disconnectSlow)
                                        throws EngineException
Add a new uniquely-named consumer that listens on a specified set of channels. The consumer will default to being synchronous (i.e. cannot re-enter the EngineClientBean)

Parameters:
uniqueName - the unique name for the new consumer.
channels - the list of channels on which the consumer should receive events. Must be non-null, and contain no null elements.
disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first consumer's disconnectSlow value is used; subsequent consumers to the same correlator (even if via different EngineManagement objects) share the connection and thus the disconnect behaviour.
Returns:
the new consumer.
Throws:
EngineException - if the consumer cannot be added (e.g. if the name is not unique), or if the channels parameter is invalid.

addConsumer

ConsumerOperationsInterface addConsumer(java.lang.String uniqueName,
                                        java.lang.String[] channels,
                                        boolean disconnectSlow,
                                        boolean async)
                                        throws EngineException
Add a new uniquely-named consumer that listens on a specified set of channels.

Parameters:
uniqueName - the unique name for the new consumer.
channels - the list of channels on which the consumer should receive events. Must be non-null, and contain no null elements.
disconnectSlow - Whether we should be disconnected if we don't keep up. Only the first consumer's disconnectSlow value is used; subsequent consumers to the same correlator (even if via different EngineManagement objects) share the connection and thus the disconnect behaviour.
async - Whether the consumer is asynchronous. If it is, events are queued and delivered in a separate thread, and EventListeners of the consumer can perform re-entrant calls to the bean. EventListeners of asynchronous consumers may be called after having been disconnected.
Returns:
the new consumer.
Throws:
EngineException - if the consumer cannot be added (e.g. if the name is not unique), or if the channels parameter is invalid.

getConsumer

ConsumerOperationsInterface getConsumer(java.lang.String uniqueName)
Get an existing uniquely-named consumer.

Parameters:
uniqueName - the unique-name of an existing consumer.
Returns:
the existing consumer, or null if one cannot be found with the specified name.

getAllConsumers

ConsumerOperationsInterface[] getAllConsumers()
Get all existing uniquely-named consumers.

Returns:
the array of all existing consumers.

isAllConsumersConnected

boolean isAllConsumersConnected()
Determine if the bean and existing uniquely-named consumers are connected.

This is a bound property, so clients may also listen for property changes to ReceiveConsumerOperationsInterface.PROPERTY_ALL_CONSUMERS_CONNECTED. If no named consumers have been added, this property is identical to isBeanConnected.

The method name may sound odd, but "is" is the accepted method-name prefix for testing boolean properties.

Returns:
true if the bean and all the named consumers are connected, false otherwise.

removeConsumer

void removeConsumer(java.lang.String uniqueName)
                    throws EngineException
Remove and disconnect any existing uniquely-named consumer. If the consumer is asynchronous, it may still be called after this method has returned; otherwise, the removeConsumer will wait for any calls into the consumer to complete.

Parameters:
uniqueName - the unique-name of an existing consumer.
Throws:
EngineException - if there are problems with removing the consumer.

removeAllConsumers

void removeAllConsumers()
                        throws EngineException
Remove and disconnect all existing uniquely-named consumers. If a consumer is asynchronous, it may still be called after this method has returned; otherwise, the removeConsumer will wait for any calls into the consumer to complete.

Throws:
EngineException - if there are problems while removing any of the consumers.


Submit a bug or feature
Copyright (c) 2013 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or Terracotta Inc., San Francisco, CA, USA, and/or Software AG (Canada) Inc., Cambridge, Ontario, Canada, and/or, Software AG (UK) Ltd., Derby, United Kingdom, and/or Software A.G. (Israel) Ltd., Or-Yehuda, Israel and/or their licensors. Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG