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. 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
      • 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.
      • 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.