com.apama.services.scenario
Interface IScenarioService

public interface IScenarioService

IScenarioService is an interface that represents the public API to the ScenarioService.

Since this is an asynchronous service, there is a standard pattern that clients should normally follow to ensure they become aware of all Scenarios in the correlator.

If a listener is passed to the factory method, then that listener will be notified of all scenarios as they are discovered, and the client will not "miss" any scenarios. This is the recommended usage pattern.

If a listener is not passed to the factory method, then the following pattern must always be used:

1. First obtain an instance of the service via one of the static methods of the ScenarioServiceFactory
2. Next add one or more listeners such that the client will be notified of new scenarios as they are added.
3. Finally the client should call either getScenarios(), getScenarioIds() or getScenarioNames() to discover any scenarios that the service discovered before the client listener was added.

When a client listener receives a PropertyChangeEvent from this interface, the following describes the type of the [old/new] value that is passed with the event:

Property Name	Property Value
PROPERTY_SCENARIO_ADDED	IScenarioDefinition
PROPERTY_SCENARIO_REMOVED	IScenarioDefinition
PROPERTY_SCENARIO_SERVICE_UNLOADED	N/A (always null)
PROPERTY_SCENARIO_DISCOVERY_STATUS	DiscoveryStatusEnum

See Also:

ScenarioServiceConfig, ScenarioServiceFactory

Field Summary

static java.lang.String	CONFIG_ACKDATA_TIMEOUT Configuration property name specifying the the timeout between receiving an Acknowledge for an operation (Create, Edit, Delete) and seeing the response (Created, Edited, Delted) on the Data channel.
static java.lang.String	CONFIG_AUTO_INSTANCE_DISCOVERY Configuration property name specifying whether to automatically initiate discovery of all scenario instances upon creating a scenario service.
static java.lang.String	CONFIG_DISCONNECT_IF_SLOW Configuration property name specifying whether to connect to the data source signalling that we may be disconnected if we do not keep up with events.
static java.lang.String	CONFIG_FILTER_USER Configuration property name specifying whether to only list to updates for the specified user If present, the scenario(s) listened for must have the ConfigureUpdates property sendRawUser or sendThrottledUser set to true.
static java.lang.String	CONFIG_RECONNECT_PERIOD Configuration property name specifying how long to wait (in milliseconds, at a minimum) between reconnects.
static java.lang.String	CONFIG_SCENARIO_EXCLUSION_FILTER Configuration property name for specifying a Set of ScenarioID's (Strings) that the client wishes to exclude.
static java.lang.String	CONFIG_SCENARIO_INCLUSION_FILTER Configuration property name for specifying a Set of ScenarioID's (Strings) in which the client is interested.
static java.lang.String	CONFIG_STRONG_DATA_INBOUND_EVENT_QUEUE Configuration property name for specifying if the EventServiceChannels created for listening to ScenarioInstance updates (the 'Data' channel) should use strong or soft references to events in the inbound queue.
static java.lang.String	CONFIG_USE_RAW_DATA_CHANNEL Configuration property name for specifying if the EventServiceChannels created for listening to ScenarioInstance updates (the 'Data' channel) should be subscribed to the normal Data channel (possibly throttled), or the Raw Data channel (always unthrottled).
static long	DEFAULT_ACKDATA_TIMEOUT Default value for the configuration property that specifies the timeout for waiting for an operation response after the acknowledge (60000ms).
static boolean	DEFAULT_AUTO_INSTANCE_DISCOVERY Default value for automatic instance discovery (true)
static boolean	DEFAULT_DISCONNECT_IF_SLOW Default value for the boolean flag specifying if we should be disconnected if slow (false)
static long	DEFAULT_RECONNECT_PERIOD Default value for the reconnect period (0.0, meaning no time between reconnects)
static java.util.Set<java.lang.String>	DEFAULT_SCENARIO_EXCLUSION_FILTER Default value for the configuration property that specifies the optional scenario exclusion filter set (null).
static java.util.Set<java.lang.String>	DEFAULT_SCENARIO_INCLUSION_FILTER Default value for the configuration property that specifies the optional scenario inclusion filter set (null).
static boolean	DEFAULT_STRONG_DATA_INBOUND_EVENT_QUEUE Default value for the boolean flag specifying if the inbound event queues for 'Data' channels will use strong references (true).
static boolean	DEFAULT_USE_RAW_DATA_CHANNEL Default value for the boolean flag specifying if the 'Data' channel to subscribe to for a scenario will be the normal (possibly throttled) channel, or the 'Raw' (always unthrottled) channel (false).
static java.lang.String	PROP_DEFAULT_ACKDATA_TIMEOUT System property (in millisecond) to set the default AckData Timeout.
static java.lang.String	PROP_OVERRIDE_ACKDATA_TIMEOUT System property (in millisecond) to override AckData Timeout.
static java.lang.String	PROPERTY_SCENARIO_ADDED Property name for events fired that signal a new ScenarioDefinition has been added.
static java.lang.String	PROPERTY_SCENARIO_DISCOVERY_STATUS Property name for events fired that signal the status of the internal mechanism for discovering scenario definitions in the Correlator.
static java.lang.String	PROPERTY_SCENARIO_REMOVED Property name for events fired that signal an existing ScenarioDefinition has been removed.
static java.lang.String	PROPERTY_SCENARIO_SERVICE_UNLOADED Property name for events fired that signal the ScenarioService has been unloaded.
static java.lang.String	SYSPROP_FILTER_USER system property specifying whether to only list to updates for the specified user If present, the scenario(s) listened for must have the ConfigureUpdates property sendRawUser or sendThrottledUser set to true.

Method Summary

void	addListener(java.beans.PropertyChangeListener listener) Add a PropertyChangeListener that will be notified of changes to any bound property of this object.
void	addListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Add a PropertyChangeListener that will be notified of changes to a specific named bound property of this object.
void	destroy() Identical to the dispose() method, retained for backwards compatibility only.
void	dispose() Dispose this service and clean up resources.
java.util.Map<java.lang.String,java.lang.Object>	getConfig() Get the configuration properties that define the requested operating semantics of this instance of the service.
DiscoveryStatusEnum	getDiscoveryStatus() Get the status of the internal scenario discovery process.
IEventService	getEventService() Get the underlying EventService that is being used by this ScenarioService.
IScenarioDefinition	getScenarioById(java.lang.String scenarioId) Get a ScenarioDefinition for a specific scenario, using the ScenarioId as the lookup key.
IScenarioDefinition	getScenarioByName(java.lang.String scenarioDisplayName) Get a ScenarioDefinition for a specific scenario, using the Display Name as the lookup key.
java.util.Set<java.lang.String>	getScenarioIds() Get the IDs of all known scenarios (not instances) in the correlator.
java.util.Set<java.lang.String>	getScenarioNames() Get the Display Names of all known scenarios (not instances) in the correlator.
java.util.List<IScenarioDefinition>	getScenarios() Get the ScenarioDefinitions of all known scenarios in the correlator.
boolean	isDestroyed() Determine if this service is disposed.
void	removeListener(java.beans.PropertyChangeListener listener) Remove a PropertyChangeListener that was to be notified of changes to any bound property of this object.
void	removeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Remove a PropertyChangeListener that was to be notified of changes to a specific named bound property of this object.

Field Detail

DEFAULT_STRONG_DATA_INBOUND_EVENT_QUEUE

static final boolean DEFAULT_STRONG_DATA_INBOUND_EVENT_QUEUE

Default value for the boolean flag specifying if the inbound event queues for 'Data' channels will use strong references (true).

See Also:

Constant Field Values

CONFIG_STRONG_DATA_INBOUND_EVENT_QUEUE

static final java.lang.String CONFIG_STRONG_DATA_INBOUND_EVENT_QUEUE

Configuration property name for specifying if the EventServiceChannels created for listening to ScenarioInstance updates (the 'Data' channel) should use strong or soft references to events in the inbound queue. This property will (for 'Data' channels only) override any value set for the property IEventServiceChannel.CONFIG_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES.

See Also:

DEFAULT_STRONG_DATA_INBOUND_EVENT_QUEUE, Constant Field Values

DEFAULT_USE_RAW_DATA_CHANNEL

static final boolean DEFAULT_USE_RAW_DATA_CHANNEL

Default value for the boolean flag specifying if the 'Data' channel to subscribe to for a scenario will be the normal (possibly throttled) channel, or the 'Raw' (always unthrottled) channel (false).

See Also:

Constant Field Values

CONFIG_USE_RAW_DATA_CHANNEL

static final java.lang.String CONFIG_USE_RAW_DATA_CHANNEL

Configuration property name for specifying if the EventServiceChannels created for listening to ScenarioInstance updates (the 'Data' channel) should be subscribed to the normal Data channel (possibly throttled), or the Raw Data channel (always unthrottled).

See Also:

DEFAULT_USE_RAW_DATA_CHANNEL, Constant Field Values

DEFAULT_SCENARIO_INCLUSION_FILTER

static final java.util.Set<java.lang.String> DEFAULT_SCENARIO_INCLUSION_FILTER

Default value for the configuration property that specifies the optional scenario inclusion filter set (null).

CONFIG_SCENARIO_INCLUSION_FILTER

static final java.lang.String CONFIG_SCENARIO_INCLUSION_FILTER

Configuration property name for specifying a Set of ScenarioID's (Strings) in which the client is interested. If the Set is null or empty, then the scenarios are unfiltered, and the service will register an interest in all scenarios. If the Set contains any items, then the service will ignore all scenarios except those in the Set.

Note: If this property is non-null then the exclusion filter (CONFIG_SCENARIO_EXCLUSION_FILTER) will be entirely ignored.

See Also:

DEFAULT_SCENARIO_INCLUSION_FILTER, DEFAULT_SCENARIO_EXCLUSION_FILTER, CONFIG_SCENARIO_EXCLUSION_FILTER, Constant Field Values

DEFAULT_SCENARIO_EXCLUSION_FILTER

static final java.util.Set<java.lang.String> DEFAULT_SCENARIO_EXCLUSION_FILTER

Default value for the configuration property that specifies the optional scenario exclusion filter set (null).

CONFIG_SCENARIO_EXCLUSION_FILTER

static final java.lang.String CONFIG_SCENARIO_EXCLUSION_FILTER

Configuration property name for specifying a Set of ScenarioID's (Strings) that the client wishes to exclude. If the Set is null or empty, then the scenarios are unfiltered, and the service will register an interest in all scenarios. If the Set contains any items, then the service will ignore all scenarios in the Set.

Note: If the CONFIG_SCENARIO_INCLUSION_FILTER is non-null then this exclusion filter will be entirely ignored.

See Also:

DEFAULT_SCENARIO_EXCLUSION_FILTER, DEFAULT_SCENARIO_INCLUSION_FILTER, CONFIG_SCENARIO_INCLUSION_FILTER, Constant Field Values

DEFAULT_ACKDATA_TIMEOUT

static final long DEFAULT_ACKDATA_TIMEOUT

Default value for the configuration property that specifies the timeout for waiting for an operation response after the acknowledge (60000ms). This determines how skewed the Data and Control channels have to be for an operation to fail.

See Also:

PROP_DEFAULT_ACKDATA_TIMEOUT, Constant Field Values

PROP_DEFAULT_ACKDATA_TIMEOUT

static final java.lang.String PROP_DEFAULT_ACKDATA_TIMEOUT

System property (in millisecond) to set the default AckData Timeout. If this property is defined, then its value will be used instead of the hard-coded DEFAULT_ACKDATA_TIMEOUT

See Also:

DEFAULT_ACKDATA_TIMEOUT, PROP_OVERRIDE_ACKDATA_TIMEOUT

PROP_OVERRIDE_ACKDATA_TIMEOUT

static final java.lang.String PROP_OVERRIDE_ACKDATA_TIMEOUT

System property (in millisecond) to override AckData Timeout. If this property is defined, then its value will be used at runtime. This value will supersede the CONFIG_ACKDATA_TIMEOUT and PROP_DEFAULT_ACKDATA_TIMEOUT_MS property setting.

See Also:

DEFAULT_ACKDATA_TIMEOUT, CONFIG_ACKDATA_TIMEOUT, PROP_DEFAULT_ACKDATA_TIMEOUT

CONFIG_ACKDATA_TIMEOUT

static final java.lang.String CONFIG_ACKDATA_TIMEOUT

Configuration property name specifying the the timeout between receiving an Acknowledge for an operation (Create, Edit, Delete) and seeing the response (Created, Edited, Delted) on the Data channel. This determines how skewed the Data and Control channels have to be for an operation to fail.

See Also:

DEFAULT_ACKDATA_TIMEOUT, Constant Field Values

DEFAULT_DISCONNECT_IF_SLOW

static final boolean DEFAULT_DISCONNECT_IF_SLOW

Default value for the boolean flag specifying if we should be disconnected if slow (false)

See Also:

Constant Field Values

CONFIG_DISCONNECT_IF_SLOW

static final java.lang.String CONFIG_DISCONNECT_IF_SLOW

Configuration property name specifying whether to connect to the data source signalling that we may be disconnected if we do not keep up with events. Only the first connection's disconnectSlow property is respected; further connections to a component will re-use an existing connection's policy.

See Also:

Constant Field Values

DEFAULT_RECONNECT_PERIOD

static final long DEFAULT_RECONNECT_PERIOD

Default value for the reconnect period (0.0, meaning no time between reconnects)

See Also:

Constant Field Values

CONFIG_RECONNECT_PERIOD

static final java.lang.String CONFIG_RECONNECT_PERIOD

Configuration property name specifying how long to wait (in milliseconds, at a minimum) between reconnects.

See Also:

Constant Field Values

CONFIG_FILTER_USER

static final java.lang.String CONFIG_FILTER_USER

Configuration property name specifying whether to only list to updates for the specified user If present, the scenario(s) listened for must have the ConfigureUpdates property sendRawUser or sendThrottledUser set to true.

See Also:

Constant Field Values

SYSPROP_FILTER_USER

static final java.lang.String SYSPROP_FILTER_USER

system property specifying whether to only list to updates for the specified user If present, the scenario(s) listened for must have the ConfigureUpdates property sendRawUser or sendThrottledUser set to true.

See Also:

Constant Field Values

CONFIG_AUTO_INSTANCE_DISCOVERY

static final java.lang.String CONFIG_AUTO_INSTANCE_DISCOVERY

Configuration property name specifying whether to automatically initiate discovery of all scenario instances upon creating a scenario service.

See Also:

Constant Field Values

DEFAULT_AUTO_INSTANCE_DISCOVERY

static final boolean DEFAULT_AUTO_INSTANCE_DISCOVERY

Default value for automatic instance discovery (true)

See Also:

Constant Field Values

PROPERTY_SCENARIO_ADDED

static final java.lang.String PROPERTY_SCENARIO_ADDED

Property name for events fired that signal a new ScenarioDefinition has been added.

See Also:

Constant Field Values

PROPERTY_SCENARIO_REMOVED

static final java.lang.String PROPERTY_SCENARIO_REMOVED

Property name for events fired that signal an existing ScenarioDefinition has been removed.

See Also:

Constant Field Values

PROPERTY_SCENARIO_SERVICE_UNLOADED

static final java.lang.String PROPERTY_SCENARIO_SERVICE_UNLOADED

Property name for events fired that signal the ScenarioService has been unloaded.

See Also:

Constant Field Values

PROPERTY_SCENARIO_DISCOVERY_STATUS

static final java.lang.String PROPERTY_SCENARIO_DISCOVERY_STATUS

Property name for events fired that signal the status of the internal mechanism for discovering scenario definitions in the Correlator.

See Also:

DiscoveryStatusEnum, Constant Field Values

Method Detail

getConfig

java.util.Map<java.lang.String,java.lang.Object> getConfig()

Get the configuration properties that define the requested operating semantics of this instance of the service.

This is an read-only property.

Returns:

an unmodifiable view of the scenarioServiceConfig Map. (A view of the Map specified when the service was created, or an empty Map if none was specified.).

getDiscoveryStatus

DiscoveryStatusEnum getDiscoveryStatus()

Get the status of the internal scenario discovery process.

Returns:

a static instance of the enum class DiscoveryStatusEnum to indicate the status.

getEventService

IEventService getEventService()

Get the underlying EventService that is being used by this ScenarioService.

Returns:

The EventService interface.

getScenarioIds

java.util.Set<java.lang.String> getScenarioIds()

Get the IDs of all known scenarios (not instances) in the correlator.

The returned Set is the result of a Map.keySet() method call, and is hence backed by the original Map.

Returns:

A Set of the IDs of all of the scenarios. Each item is a String.

See Also:

IScenarioDefinition.getId()

getScenarioNames

java.util.Set<java.lang.String> getScenarioNames()

Get the Display Names of all known scenarios (not instances) in the correlator.

The returned Set is the result of a Map.keySet() method call, and is hence backed by the original Map.

Returns:

A Set of the Display Names of all of the scenarios. Each item is a String.

See Also:

IScenarioDefinition.getDisplayName()

getScenarios

java.util.List<IScenarioDefinition> getScenarios()

Get the ScenarioDefinitions of all known scenarios in the correlator.

The returned List is populated with the result of a Map.values() method call, but is not backed by the original Map.

Returns:

A List of the ScenarioDefinitions of all of the scenarios. Each item is an IScenarioDefinition.

getScenarioByName

IScenarioDefinition getScenarioByName(java.lang.String scenarioDisplayName)

Get a ScenarioDefinition for a specific scenario, using the Display Name as the lookup key.

Parameters:

scenarioDisplayName - the ID of the scenario for which the IScenarioDefinition is required.

Returns:

The ScenarioDefinition interface for the requested scenario.

getScenarioById

IScenarioDefinition getScenarioById(java.lang.String scenarioId)

Get a ScenarioDefinition for a specific scenario, using the ScenarioId as the lookup key.

Parameters:

scenarioId - the ID of the scenario for which the IScenarioDefinition is required.

Returns:

The ScenarioDefinition interface for the requested scenario.

addListener

void addListener(java.beans.PropertyChangeListener listener)

Add a PropertyChangeListener that will be notified of changes to any bound property of this object.

Parameters:

listener - The listener to be notified.

See Also:

PROPERTY_SCENARIO_ADDED, PROPERTY_SCENARIO_REMOVED, PROPERTY_SCENARIO_SERVICE_UNLOADED, PROPERTY_SCENARIO_DISCOVERY_STATUS

addListener

void addListener(java.lang.String propertyName,
                 java.beans.PropertyChangeListener listener)

Add a PropertyChangeListener that will be notified of changes to a specific named bound property of this object.

Parameters:

propertyName - The name of a specific property.

listener - The listener to be notified.

See Also:

PROPERTY_SCENARIO_ADDED, PROPERTY_SCENARIO_REMOVED, PROPERTY_SCENARIO_SERVICE_UNLOADED, PROPERTY_SCENARIO_DISCOVERY_STATUS

removeListener

void removeListener(java.beans.PropertyChangeListener listener)

Remove a PropertyChangeListener that was to be notified of changes to any bound property of this object.

Parameters:

listener - The listener to be removed.

See Also:

PROPERTY_SCENARIO_ADDED, PROPERTY_SCENARIO_REMOVED, PROPERTY_SCENARIO_SERVICE_UNLOADED, PROPERTY_SCENARIO_DISCOVERY_STATUS

removeListener

void removeListener(java.lang.String propertyName,
                    java.beans.PropertyChangeListener listener)

Remove a PropertyChangeListener that was to be notified of changes to a specific named bound property of this object.

Parameters:

propertyName - The name of a specific property.

listener - The listener to be removed.

See Also:

PROPERTY_SCENARIO_ADDED, PROPERTY_SCENARIO_REMOVED, PROPERTY_SCENARIO_SERVICE_UNLOADED, PROPERTY_SCENARIO_DISCOVERY_STATUS

dispose

void dispose()

Dispose this service and clean up resources.

This will simulate a SenarioServiceUnloaded and cause all EventServiceChannels to be removed and disconnected from the correlator. If an EventService was created implicitly, it also be disposed by this call.

Java client applications should destroy any created scenario services once they are finished using them. To avoid deadlock, this method should never be invoked synchronously from any ScenarioService listener.

destroy

void destroy()

Identical to the dispose() method, retained for backwards compatibility only.

isDestroyed

boolean isDestroyed()

Determine if this service is disposed.

Returns:

true if already disposed, false otherwise.