The Apama ScenarioService API is layered on top of the EventService API which is described in EventService API.

The ScenarioService API provides an external interface to DataViews and queries. For historical reasons, both DataViews and queries are represented as "scenarios" in this API.

For a full reference of the ScenarioService API in the different languages, refer to the following:

For examples of using the ScenarioService API, see the following directories of your Apama installation:

The ScenarioService API mainly consists of the following interfaces:

The IScenarioService interface is used to establish communication with the correlator and to provide access to the scenario definitions in the correlator. The ScenarioServiceFactory class is used to create the ScenarioService object that implements the interface:

The API also provides a helper ScenarioServiceConfig class that is used to build a properties map used by the ScenarioServiceFactory when creating a new ScenarioService object:

The ScenarioService object provides methods to get the IDs/names of all known scenarios (not instances) in the correlator. It also provides methods to get the ScenarioDefinition instances for all known scenarios (not instances) or for specific scenarios.

The ScenarioService object provides the capability to register listeners to get notified of all scenarios in the correlator as they are discovered. The listener can be passed when creating a ScenarioService object or it can be manually added later. If the listener is manually added after the ScenarioService object has been created, then the application must manually call methods to discover any scenarios that the service discovered before the application listener was added. Listeners are also notified for other properties. Listeners can be added which get notified only when some specific property is changed. See the Javadoc or .NET documentation for a full list of the supported properties.

If the ScenarioService is no longer needed, a cleanup should be performed by calling close() for Java or Dispose() for .NET, which will disconnect it and also ensure that any started background threads have been terminated.

The IScenarioDefinition interface is used to represent a scenario (not an instance) that is running in the correlator. ScenarioDefinition instances are obtained by calling the appropriate methods on the ScenarioService.

The ScenarioDefinition object provides methods to obtain meta-information about the scenario, such as the scenario's input and output parameter names and types. The object also provides methods to access all or specific instances, create new instances, and add and remove listeners for property changes.

The IScenarioInstance interface is used to represent a single instance of a scenario. The ScenarioInstance is returned by methods of the ScenarioDefinition object that are used to discover and create new scenario instances. The ScenarioInstance has methods to get/set the values of the instance's parameters as well as to delete the instance. The interface also has methods to add and remove listeners for property changes.

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