Interface IScenarioService
-
- 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
. ThePropertyChangeListener
specified when the service is created will receive an asynchronousPROPERTY_SCENARIO_ADDED
notification for each availableIScenarioDefinition
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 eachIScenarioInstance
.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 byclose()
as of Apama version 9.10void
dispose()
Deprecated.Replaced byclose()
as of Apama version 9.10java.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 propertyIEventServiceChannel.CONFIG_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES
.
-
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).
-
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.
-
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.
-
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.
-
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
-
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.
-
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. SeeaddListener(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 interfacejava.lang.AutoCloseable
- See Also:
AutoCloseable.close()
-
dispose
@Deprecated void dispose()
Deprecated.Replaced byclose()
as of Apama version 9.10Dispose 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 byclose()
as of Apama version 9.10Identical to thedispose()
method, retained for backwards compatibility only.
-
isDestroyed
boolean isDestroyed()
Determine if this service is disposed.- Returns:
- true if already disposed, false otherwise.
-
-