com.apama.services.scenario
Interface IScenarioDefinition

public interface IScenarioDefinition

IScenarioDefinition is the public interface for a class that represents a Scenario (not an instance).

This interface provides an API for obtaining meta-information about a scenario (parameter names, types, constraints, etc), and for creating new instances of the scenario.

Each input parameter has an associated set of optional validation constraints, expressed as an XML string. The current implementation of the Scenario Service does not enforce these constraints, but provides access to them such that a client may enforce them outside of the service. The XML is useful to drive 3rd-party validation libraries, such as the Jakarta Commons Validator.

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_INSTANCE_ADDED	IScenarioInstance
PROPERTY_INSTANCE_DIED	IScenarioInstance
PROPERTY_INSTANCE_EDITED	IScenarioInstance
PROPERTY_INSTANCE_UPDATED	IScenarioInstance
PROPERTY_INSTANCE_REMOVED	IScenarioInstance
PROPERTY_INSTANCE_STATE_CHANGE	IScenarioInstance
PROPERTY_INSTANCE_DISCOVERY_STATUS	DiscoveryStatusEnum

Field Summary

static java.lang.String	PROPERTY_INSTANCE_ADDED Property name for events fired that signal a new ScenarioInstance has been added.
static java.lang.String	PROPERTY_INSTANCE_DIED Property name for events fired that signal a ScenarioInstance has died unexpectedly.
static java.lang.String	PROPERTY_INSTANCE_DISCOVERY_STATUS Property name for events fired that signal the status of the internal mechanism for discovering scenario instances in the Correlator.
static java.lang.String	PROPERTY_INSTANCE_EDITED Property name for events fired that signal a ScenarioInstance has been edited.
static java.lang.String	PROPERTY_INSTANCE_REMOVED Property name for events fired that signal an existing ScenarioInstance has been removed.
static java.lang.String	PROPERTY_INSTANCE_STATE_CHANGE Property name for events fired that signal an existing ScenarioInstance has changed state.
static java.lang.String	PROPERTY_INSTANCE_UPDATED Property name for events fired that signal a ScenarioInstance has been updated.

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.
IScenarioInstance	createInstance(java.lang.String owner) Create a new instance of this scenario, using default values for all input paramters.
IScenarioInstance	createInstance(java.lang.String owner, java.util.Map<java.lang.String,java.lang.Object> inputParameters) Create a new instance of this scenario, with the supplied values for input paramters.
IScenarioInstance	createInstance(java.lang.String owner, java.util.Map<java.lang.String,java.lang.Object> inputParameters, java.beans.PropertyChangeListener listener) Create a new instance of this Scenario, with the supplied values for input paramters, and atomically add a listener.
IScenarioInstance	createInstance(java.lang.String owner, java.util.Map<java.lang.String,java.lang.Object> inputParameters, java.lang.String property, java.beans.PropertyChangeListener listener) Create a new instance of this Scenario, with the supplied values for input paramters, and atomically add a listener.
java.lang.String	getDescription() Get the description of the scenario.
DiscoveryStatusEnum	getDiscoveryStatus() Get the status of the internal scenario instance discovery process.
java.lang.String	getDisplayName() Get the display name of the scenario.
java.lang.String	getId() Get the ID of the scenario.
java.util.List<java.lang.String>	getInputParameterConstraints() Get the constraints of all input parameters for the scenario.
java.util.List<java.lang.Object>	getInputParameterDefaults() Get the default values of all input parameters for the scenario.
java.util.Set<java.lang.String>	getInputParameterNames() Get the names of all input parameters for the scenario.
java.util.List<ParameterTypeEnum>	getInputParameterTypes() Get the types of all input parameters for the scenario.
IScenarioInstance	getInstance(long instanceId) Get a single specific instance of this scenario, by instance ID.
java.util.List<IScenarioInstance>	getInstances() Get all instances of this scenario.
java.util.List<IScenarioInstance>	getInstancesForOwner(java.lang.String owner) Get all instances of this scenario for a specific owner.
java.util.Set<java.lang.String>	getOutputParameterNames() Get the names of all output parameters for the scenario.
java.util.List<ParameterTypeEnum>	getOutputParameterTypes() Get the types of all output parameters for the scenario.
boolean	isInputParameter(java.lang.String parameterName) Test if a specific named parameter is an input parameter.
boolean	isOutputParameter(java.lang.String parameterName) Test if a specific named parameter is an output parameter.
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.
void	requestInstances() Initiate requesting instances.

Field Detail

PROPERTY_INSTANCE_ADDED

static final java.lang.String PROPERTY_INSTANCE_ADDED

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

See Also:

Constant Field Values

PROPERTY_INSTANCE_DIED

static final java.lang.String PROPERTY_INSTANCE_DIED

Property name for events fired that signal a ScenarioInstance has died unexpectedly.

See Also:

Constant Field Values

PROPERTY_INSTANCE_EDITED

static final java.lang.String PROPERTY_INSTANCE_EDITED

Property name for events fired that signal a ScenarioInstance has been edited.

See Also:

Constant Field Values

PROPERTY_INSTANCE_UPDATED

static final java.lang.String PROPERTY_INSTANCE_UPDATED

Property name for events fired that signal a ScenarioInstance has been updated.

See Also:

Constant Field Values

PROPERTY_INSTANCE_REMOVED

static final java.lang.String PROPERTY_INSTANCE_REMOVED

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

See Also:

Constant Field Values

PROPERTY_INSTANCE_STATE_CHANGE

static final java.lang.String PROPERTY_INSTANCE_STATE_CHANGE

Property name for events fired that signal an existing ScenarioInstance has changed state.

See Also:

InstanceStateEnum, Constant Field Values

PROPERTY_INSTANCE_DISCOVERY_STATUS

static final java.lang.String PROPERTY_INSTANCE_DISCOVERY_STATUS

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

See Also:

DiscoveryStatusEnum, Constant Field Values

Method Detail

getDiscoveryStatus

DiscoveryStatusEnum getDiscoveryStatus()

Get the status of the internal scenario instance discovery process.

Returns:

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

requestInstances

void requestInstances()

Initiate requesting instances. This is called automatically when the scenario is discovered after creating the scenario service after listeners on the service have been fired unless the IScenarioService.CONFIG_AUTO_INSTANCE_DISCOVERY is set to false. If the discovery status is not PENDING, this is a no-op.

getId

java.lang.String getId()

Get the ID of the scenario.

This is the ID of the scenario, not of an instance. This ID is unique within the Correlator.

Typically, the scenarioID will be a string derived from the scenario name that was used when the user saved the scenario from Scenario Manager. This ID is also the same as the namespace/package used for auto-generated MonitorScript for the scenario.
e.g. If the user saved the scenario with the name "limit-order", the ID would be "Scenario_limit$002dorder".

Returns:

The scenario ID.

getDisplayName

java.lang.String getDisplayName()

Get the display name of the scenario.

Returns:

The display name.

getDescription

java.lang.String getDescription()

Get the description of the scenario. This is not a formal description, but a human readable description provided by the scenario author.

Returns:

The human readable description.

getInstances

java.util.List<IScenarioInstance> getInstances()

Get all instances of this scenario.

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

Returns:

The List (possibly empty) of all instances of this scenario. Each item is an IScenarioInstance.

getInstance

IScenarioInstance getInstance(long instanceId)

Get a single specific instance of this scenario, by instance ID.

Parameters:

instanceId - The ID of the required instance.

Returns:

The specific instance.

getInstancesForOwner

java.util.List<IScenarioInstance> getInstancesForOwner(java.lang.String owner)

Get all instances of this scenario for a specific owner.

Parameters:

owner - The owner for which instances are required.

Returns:

The List (possibly empty) of all instances for the specific owner. Each item is an IScenarioInstance.

getInputParameterNames

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

Get the names of all input parameters for the scenario.

Returns:

The ordered Set (possibly empty) of all input field names - order is as required by the MonitorScript events. Each item is a String.

getOutputParameterNames

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

Get the names of all output parameters for the scenario.

Returns:

The ordered Set (possibly empty) of all output field names - order is as required by the MonitorScript events. Each item is a String.

getInputParameterTypes

java.util.List<ParameterTypeEnum> getInputParameterTypes()

Get the types of all input parameters for the scenario. Note that these are not Java types, but the types of the scenario parameters.

Returns:

The List (possibly empty) of all input field types. Each item is a ParameterTypeEnum.

See Also:

ParameterTypeEnum

getOutputParameterTypes

java.util.List<ParameterTypeEnum> getOutputParameterTypes()

Get the types of all output parameters for the scenario. Note that these are not Java types, but the types of the scenario parameters.

Returns:

The List (possibly empty) of all output field types. Each item is a ParameterTypeEnum.

See Also:

ParameterTypeEnum

getInputParameterConstraints

java.util.List<java.lang.String> getInputParameterConstraints()

Get the constraints of all input parameters for the scenario. Each input parameter has an associated set of optional validation constraints, expressed as an XML string. The current implementation of the Scenario Service does not enforce these constraints, but provides access to them such that a client may enforce them outside of the service.

Returns:

The List (possibly empty) of all input field constraints. Each item is a String (XML).

getInputParameterDefaults

java.util.List<java.lang.Object> getInputParameterDefaults()

Get the default values of all input parameters for the scenario.

Returns:

The List (possibly empty) of all input field default values. Each item is an Object of the correct Java type.

See Also:

ParameterTypeEnum

isInputParameter

boolean isInputParameter(java.lang.String parameterName)

Test if a specific named parameter is an input parameter.

Parameters:

parameterName - The name of a paramter to be tested.

Returns:

true if the named parameter is an input parameter, false otherwise.

isOutputParameter

boolean isOutputParameter(java.lang.String parameterName)

Test if a specific named parameter is an output parameter.

Parameters:

parameterName - The name of a paramter to be tested.

Returns:

true if the named parameter is an output parameter, false otherwise.

createInstance

IScenarioInstance createInstance(java.lang.String owner)
                                 throws InvalidInputParameterException,
                                        IllegalCallingThreadException

Create a new instance of this scenario, using default values for all input paramters. If an instance cannot be created for any reason (other than invalid input parameters), the return value will be null.

Parameters:

owner - id of the owner of this Scenario.

Returns:

The newly created instance, or null if the creation failed.

Throws:

InvalidInputParameterException - when any of the inputParameters is invalid. Note that future versions of this API may also throw this exception to indicate constraint violations.

IllegalCallingThreadException - if called from the data processing thread (i.e. from a PropertyChangeListener listening to an instance or definition).

createInstance

IScenarioInstance createInstance(java.lang.String owner,
                                 java.util.Map<java.lang.String,java.lang.Object> inputParameters)
                                 throws InvalidInputParameterException,
                                        IllegalCallingThreadException

Create a new instance of this scenario, with the supplied values for input paramters. Any input parameters not supplied will take default values. If an instance cannot be created for any reason (other than invalid input parameters), the return value will be null.

Parameters:

owner - id of the owner of this Scenario.

inputParameters - contains mappings from input parameter name to initial values.

Returns:

The newly created instance, or null if the creation failed.

Throws:

InvalidInputParameterException - when any of the inputParameters is invalid. Note that future versions of this API may also throw this exception to indicate constraint violations.

IllegalCallingThreadException - if called from the data processing thread (i.e. from a PropertyChangeListener listening to an instance or definition).

createInstance

IScenarioInstance createInstance(java.lang.String owner,
                                 java.util.Map<java.lang.String,java.lang.Object> inputParameters,
                                 java.beans.PropertyChangeListener listener)
                                 throws InvalidInputParameterException,
                                        IllegalCallingThreadException

Create a new instance of this Scenario, with the supplied values for input paramters, and atomically add a listener. Any input parameters not supplied will take default values. If an instance cannot be created for any reason (other than invalid input parameters), the return value will be null.

Parameters:

owner - id of the owner of this Scenario.

inputParameters - contains mappings from input parameter name to initial values.

listener - a listener (all properties) to register atomically to the instance.

Returns:

The newly created instance, or null if the creation failed.

Throws:

InvalidInputParameterException - when any of the inputParameters is invalid. Note that future versions of this API may also throw this exception to indicate constraint violations.

IllegalCallingThreadException - if called from the data processing thread (i.e. from a PropertyChangeListener listening to an instance or definition).

createInstance

IScenarioInstance createInstance(java.lang.String owner,
                                 java.util.Map<java.lang.String,java.lang.Object> inputParameters,
                                 java.lang.String property,
                                 java.beans.PropertyChangeListener listener)
                                 throws InvalidInputParameterException,
                                        IllegalCallingThreadException

Create a new instance of this Scenario, with the supplied values for input paramters, and atomically add a listener. Any input parameters not supplied will take default values. If an instance cannot be created for any reason (other than invalid input parameters), the return value will be null.

Parameters:

owner - id of the owner of this Scenario.

inputParameters - contains mappings from input parameter name to initial values.

property - the property the listener listens to.

listener - a listener to register atomically to the instance.

Returns:

The newly created instance, or null if the creation failed.

Throws:

InvalidInputParameterException - when any of the inputParameters is invalid. Note that future versions of this API may also throw this exception to indicate constraint violations.

IllegalCallingThreadException - if called from the data processing thread (i.e. from a PropertyChangeListener listening to an instance or definition).

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_INSTANCE_DISCOVERY_STATUS, PROPERTY_INSTANCE_ADDED, PROPERTY_INSTANCE_REMOVED, PROPERTY_INSTANCE_EDITED, PROPERTY_INSTANCE_UPDATED, PROPERTY_INSTANCE_DIED, PROPERTY_INSTANCE_STATE_CHANGE

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_INSTANCE_DISCOVERY_STATUS, PROPERTY_INSTANCE_ADDED, PROPERTY_INSTANCE_REMOVED, PROPERTY_INSTANCE_EDITED, PROPERTY_INSTANCE_UPDATED, PROPERTY_INSTANCE_DIED, PROPERTY_INSTANCE_STATE_CHANGE

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_INSTANCE_DISCOVERY_STATUS, PROPERTY_INSTANCE_ADDED, PROPERTY_INSTANCE_REMOVED, PROPERTY_INSTANCE_EDITED, PROPERTY_INSTANCE_UPDATED, PROPERTY_INSTANCE_DIED, PROPERTY_INSTANCE_STATE_CHANGE

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_INSTANCE_DISCOVERY_STATUS, PROPERTY_INSTANCE_ADDED, PROPERTY_INSTANCE_REMOVED, PROPERTY_INSTANCE_EDITED, PROPERTY_INSTANCE_UPDATED, PROPERTY_INSTANCE_DIED, PROPERTY_INSTANCE_STATE_CHANGE