All Superinterfaces:

java.lang.AutoCloseable
```
public interface IScenarioService
extends java.lang.AutoCloseable
```
The Scenario Service is an API for interacting with Apama applications from custom clients and dashboards running outside the correlator.
For example, it can be used to listen for updates from applications that expose data through DataViews, or to create/edit/delete instances of queries.

Create an IScenarioService instance using the ScenarioServiceFactory. The PropertyChangeListener specified when the service is created will receive an asynchronous PROPERTY_SCENARIO_ADDED notification for each available IScenarioDefinition as soon as the service successfully connects to the correlator, which you can use to create/edit/delete scenario instances, or to add a listener for the parameters of each IScenarioInstance.

The Scenario Service is built on the IEventService and is thread-safe. Note that unlike other parts of the Apama API, Scenario Service listener callbacks can be invoked while locks internal to the Scenario Service are held. For this reason it is not safe to call Scenario Service methods while holding any application-defined lock that might also be acquired within a Scenario Service property change listener, as this may result in deadlock.

See Also:

ScenarioServiceConfig, ScenarioServiceFactory

Field Summary

Fields
Modifier and Type	Field	Description
`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.
`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

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method	Description
`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`	`close()`	Dispose this service and clean up resources.
`void`	`destroy()`	Deprecated. Replaced by `close()` as of Apama version 9.10
`void`	`dispose()`	Deprecated. Replaced by `close()` as of Apama version 9.10
`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. 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 a read-only property.

Returns:

a read-only view of the scenarioServiceConfig Map (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 a shallow copy (new Set) of the scenario Ids.

Returns:

A read-only 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 a shallow copy (new Set) of the scenario names.

Returns:

A read-only 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 a shallow copy (new List) of the scenarios.

Returns:

A read-only 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.

When a 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`

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. See addListener(PropertyChangeListener) for details about the property change events.

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

close
```
void close()
```
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.

This method is invoked automatically on objects managed by the try-with-resources statement.

Specified by:

close in interface java.lang.AutoCloseable

See Also:

AutoCloseable.close()

dispose
```
@Deprecated
void dispose()
```
Deprecated.
Replaced by close() as of Apama version 9.10

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
```
@Deprecated
void destroy()
```
Deprecated.
Replaced by close() as of Apama version 9.10

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.

Interface IScenarioService

Field Summary

Method Summary

Field Detail

DEFAULT_STRONG_DATA_INBOUND_EVENT_QUEUE

CONFIG_STRONG_DATA_INBOUND_EVENT_QUEUE

DEFAULT_USE_RAW_DATA_CHANNEL

CONFIG_USE_RAW_DATA_CHANNEL

DEFAULT_SCENARIO_INCLUSION_FILTER

CONFIG_SCENARIO_INCLUSION_FILTER

DEFAULT_SCENARIO_EXCLUSION_FILTER

CONFIG_SCENARIO_EXCLUSION_FILTER

DEFAULT_ACKDATA_TIMEOUT

PROP_DEFAULT_ACKDATA_TIMEOUT

PROP_OVERRIDE_ACKDATA_TIMEOUT

CONFIG_ACKDATA_TIMEOUT

DEFAULT_DISCONNECT_IF_SLOW

CONFIG_DISCONNECT_IF_SLOW

DEFAULT_RECONNECT_PERIOD

CONFIG_RECONNECT_PERIOD

CONFIG_FILTER_USER

SYSPROP_FILTER_USER

CONFIG_AUTO_INSTANCE_DISCOVERY

DEFAULT_AUTO_INSTANCE_DISCOVERY

PROPERTY_SCENARIO_ADDED

PROPERTY_SCENARIO_REMOVED

PROPERTY_SCENARIO_SERVICE_UNLOADED

PROPERTY_SCENARIO_DISCOVERY_STATUS

Method Detail

getConfig

getDiscoveryStatus

getEventService

getScenarioIds

getScenarioNames

getScenarios

getScenarioByName

getScenarioById

addListener

addListener

removeListener

removeListener

close

dispose

destroy

isDestroyed