Scenario Service API

Info
Note: This API is deprecated and will be removed in a future release.

Scenarios are a simple abstraction for interacting with an Apama application using create/read/update/delete (CRUD) operations.

Each scenario is defined by a unique identifier and display name, and a list of named input and/or output parameters and their types. Multiple instances of each scenario can be created, each with their own input parameter values. Scenario instances can subsequently be edited or deleted. Instances can produce a series of updates as their output parameter values change, and also have an “owner” and a “state” which can be RUNNING, ENDED or FAILED.

Apama queries use the scenario abstraction to support creating, editing and deleting instances of each query, but do not generate any outputs.

Info
Note: Apama queries are deprecated and will be removed in a future release.

Scenarios that provide a read-only view of data - generating outputs but not allowing external clients to create, edit or delete instances - are called DataViews. DataViews can be used to expose data from many parts of an Apama application, including from MemoryStore tables (see Exposing in-memory or persistent data as DataViews), and from EPL applications that use Apama’s DataView EPL API, which is also known as the DataView Service (see Making application data available to clients).

Apama provides a Scenario Service API in Java and .NET for working with scenarios programmatically in external clients such as custom user interfaces. For manually interacting with scenarios, Apama provides a Scenario Browser view in Apama Plugin for Eclipse (see also Using the Scenario Browser view) and a standalone tool. The Apama Scenario Service API is layered on top of the EventService API which is described in Event Service API.

If you have scenarios that update frequently, you might need to reduce the frequency of update events sent by the correlator. See Controlling the update frequency.

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

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

  • samples\engine_client\java\ScenarioService
  • samples\engine_client\dotnet\ScenarioService

The key elements

The Scenario Service API mainly consists of the following interfaces:

  • IScenarioService

    For Java, this is com.apama.services.scenario.IScenarioService.

    For .NET, this is Apama.Services.Scenario.IScenarioService.

  • IScenarioDefinition

    For Java, this is com.apama.services.scenario.IScenarioDefinition.

    For .NET, this is Apama.Services.Scenario.IScenarioDefinition.

  • IScenarioInstance

    For Java, this is com.apama.services.scenario.IScenarioInstance.

    For .NET, this is Apama.Services.Scenario.IScenarioInstance.

ScenarioService

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:

  • For Java, the factory class is com.apama.services.scenario.ScenarioServiceFactory.
  • For .NET, the factory class is Apama.Services.Scenario.ScenarioServiceFactory.

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:

  • For Java, the helper class is com.apama.services.scenario.ScenarioServiceConfig.
  • For .NET, the helper class is Apama.Services.Scenario.ScenarioServiceConfig.

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.

ScenarioDefinition

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.

ScenarioInstance

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.

To protect the security of personal data of the users who created instances of scenarios, see Protecting personal data in Apama applications.

Thread safety

The Scenario Service API is thread-safe. Note that unlike other parts of the Apama API, Scenario Service listener callbacks may 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 a deadlock.