com.apama.service.framework
Event ServiceInterface


The Service Interface is used in conjunction with the Service Framework Manager object to provide a two-phase startup mechanism for applications.

After all ServiceInterfaces have been created/injected, the Service Framework Manager waits for the user to activate the Service Framework (via the Activate() event). At that point, any instances of the Service Interface that need to be configured are called back.

Only after all Service Interface instances have responded to the configuration request will the second-phase be started by the Service Framework Manager broadcasting an AllInitialServicesInitialised event to this object.

The Service Interface object handles all communication with the Service Framework Manager. Users should not need to interact with the Service Framework Manager directly.
Since:
CMF 1.1.0
Version:
10.7
See Also:
com.apama.service.framework.ServiceFrameworkManager - The Service Framework Manager object
com.apama.config.Activate - The Service Framework activation request event
Routes:
com.apama.service.framework.ServiceParameters - 
Sends:
com.apama.service.framework.ServiceParameters - 

Action summary
 integeraddErrorCallback(action<com.apama.service.framework.ServiceInterfacecom.apama.utils.Error> cbError)

This action allows the application to add an error handling callback that will be called if an error occurs due to a request by the Service Interface.
 voidclearErrorCallbacks()

This action allows the application to remove all error callbacks that were added by the "addErrorCallback()" action.
 voiddefaultErrorCallback(com.apama.service.framework.ServiceInterface iface, com.apama.utils.Error error)

This is the default action that will be called by this instance of the Service Framework when an error is encountered.
 voiddefaultServiceInitialisedCb(integer currServiceId, dictionary<string, string> parameters, action<> configCb)

This is a default implementation of the ServiceInitialised callback function that the User normally provides to the "initialiseWithConfig()" action.
 voiddelete()

This action will delete/remove an instance of the Service Framework that is no longer required.
 voiddoNothing(integer serviceId)

This function does nothing. It is used by the legacy initialiseServiceInterface function to provide a boiler plate callback function on successful initialisation of the interface.
 booleangetBooleanParameter(dictionary<string, string> parameters, string name, boolean defaultValue)

Utility action to try to find and parse the boolean parameter 'name' in the parameter list, or return the default value on failure.
 floatgetFloatParameter(dictionary<string, string> parameters, string name, float defaultValue)

Utility action to try to find and parse the float parameter 'name' in the parameter list, or return the default value on failure.
 integergetIntegerParameter(dictionary<string, string> parameters, string name, integer defaultValue)

Utility action to try to find and parse the integer parameter 'name' in the parameter list, or return the default value on failure.
 voidgetServiceConfig(string serviceType, string serviceName, action<sequence<com.apama.service.framework.ServiceConfig>> serviceConfigCb)

This action will request the configuration (parameter dictionary and context) of services from the Service Framework manager.
 integergetServiceId()

Gets the ServiceId provided to the User on creation of this Service Interface instance.
 stringgetServiceName()

Gets the Service Name provided by the User on creation of this Service Interface instance.
 stringgetServiceType()

Gets the Service Type provided by the User on creation of this Service Interface instance.
 stringgetStringParameter(dictionary<string, string> parameters, string name, string defaultValue)

Utility action to try to find and parse the string parameter 'name' in the parameter list, or return the default value on failure.
 integerinitialise(string serviceType, string serviceName, context serviceMgrContext, action<integer> allServicesInitialisedCb)

The initialisation action that is used to create a Service Interface that can be used to provide a two-phase start-up mechanism in an application.
 integerinitialiseWithConfig(string serviceType, string serviceName, context serviceMgrContext, action<integer, dictionary<string, string>, action<>> serviceInitialisedCb, action<integer> allServicesInitialisedCb)

The initialisation action that is used to create a Service Interface that can be used to provide a two-phase startup mechanism in an application.
 voidremoveErrorCallback(integer refId)

This action allows the application to remove error callback that was added by the "addErrorCallback()" action using the reference Id provided.
 voidsetServiceManagerContext(context serviceManagerContext)

This action sets the context that the Service Framework Manager resides in.
 voidsetServiceParameters(string serviceType, string serviceName, dictionary<string, string> parameters)

This action will set parameter dictionary of services in the Service Framework manager.
 voidwaitForService(string serviceType, string serviceName, context serviceMgrContext, action<com.apama.service.framework.ServiceConfig> cbServiceReady)

This action will wait until the Service Framework has been activated, and the Service Name/Type provided has been fully initialised.
 
Action detail

addErrorCallback

integer addErrorCallback(action<com.apama.service.framework.ServiceInterfacecom.apama.utils.Error> cbError)
This action allows the application to add an error handling callback that will be called if an error occurs due to a request by the Service Interface.


iface The ServiceInterface
error An Error event
Parameters:
cbError - The Error callback.
Returns:
A reference Id that can be used to remove the callback at a later date
See Also:
com.apama.service.framework.ErrorConstants - 
com.apama.utils.Error - 
com.apama.service.framework.ServiceInterface#removeErrorCallback() - 

clearErrorCallbacks

void clearErrorCallbacks()
This action allows the application to remove all error callbacks that were added by the "addErrorCallback()" action.
See Also:
com.apama.service.framework.ServiceInterface#addErrorCallback() - 
com.apama.service.framework.ServiceInterface#removeErrorCallback() - 

defaultErrorCallback

void defaultErrorCallback(com.apama.service.framework.ServiceInterface iface, com.apama.utils.Error error)
This is the default action that will be called by this instance of the Service Framework when an error is encountered.
Parameters:
iface - The ServiceInterface
error - An error event
See Also:
com.apama.service.framework.ServiceInterface#addErrorCallback() - 

defaultServiceInitialisedCb

void defaultServiceInitialisedCb(integer currServiceId, dictionary<string, string> parameters, action<> configCb)
This is a default implementation of the ServiceInitialised callback function that the User normally provides to the "initialiseWithConfig()" action.

The default implementation simply responds immediately that the configuration was complete.
Parameters:
currServiceId - The ServiceId of the Service that was initialised.
parameters - The parameters for this Service.
configCb - This is the action that must be called after all configuration has been completed
See Also:
com.apama.service.framework.ServiceInterface#initialiseWithConfig() - This is the Public API Service initialisation function should be used instead if the Service needs to call the User back to provide configuration prior to the second phase.

delete

void delete()
This action will delete/remove an instance of the Service Framework that is no longer required.

doNothing

void doNothing(integer serviceId)
This function does nothing. It is used by the legacy initialiseServiceInterface function to provide a boiler plate callback function on successful initialisation of the interface.
Parameters:
serviceId

getBooleanParameter

boolean getBooleanParameter(dictionary<string, string> parameters, string name, boolean defaultValue)
Utility action to try to find and parse the boolean parameter 'name' in the parameter list, or return the default value on failure.
Parameters:
parameters - The parameter list to search.
name - The name of the parameter to find.
defaultValue - The default value if the parameter cannot be found or parsed.

getFloatParameter

float getFloatParameter(dictionary<string, string> parameters, string name, float defaultValue)
Utility action to try to find and parse the float parameter 'name' in the parameter list, or return the default value on failure.
Parameters:
parameters - The parameter list to search.
name - The name of the parameter to find.
defaultValue - The default value if the parameter cannot be found or parsed.

getIntegerParameter

integer getIntegerParameter(dictionary<string, string> parameters, string name, integer defaultValue)
Utility action to try to find and parse the integer parameter 'name' in the parameter list, or return the default value on failure.
Parameters:
parameters - The parameter list to search.
name - The name of the parameter to find.
defaultValue - The default value if the parameter cannot be found or parsed.

getServiceConfig

void getServiceConfig(string serviceType, string serviceName, action<sequence<com.apama.service.framework.ServiceConfig>> serviceConfigCb)
This action will request the configuration (parameter dictionary and context) of services from the Service Framework manager.

You can request the configuration for any specific service, or for all services of a type by leaving the service name parameter blank.
Parameters:
serviceType - The type of the service to request config for
serviceName - The name of the service to request config for. This may be left blank to request the config for all services of a type.
serviceConfigCb - This is the callback function that the User provides. It is called when the response is received from the Service Framework manager. The Callback function returns a sequence of ServiceConfig events if one or more Services exist that match the request
See Also:
com.apama.service.framework.ServiceConfig - The Service Config event

getServiceId

integer getServiceId()
Gets the ServiceId provided to the User on creation of this Service Interface instance.
Returns:
The ServiceId provided to the User on creation of this Service Interface instance

getServiceName

string getServiceName()
Gets the Service Name provided by the User on creation of this Service Interface instance.
Returns:
The Service Name provided by the User on creation of this Service Interface instance

getServiceType

string getServiceType()
Gets the Service Type provided by the User on creation of this Service Interface instance.
Returns:
The Service Type provided by the User on creation of this Service Interface instance

getStringParameter

string getStringParameter(dictionary<string, string> parameters, string name, string defaultValue)
Utility action to try to find and parse the string parameter 'name' in the parameter list, or return the default value on failure.
Parameters:
parameters - The parameter list to search.
name - The name of the parameter to find.
defaultValue - The default value if the parameter cannot be found or parsed.

initialise

integer initialise(string serviceType, string serviceName, context serviceMgrContext, action<integer> allServicesInitialisedCb)
The initialisation action that is used to create a Service Interface that can be used to provide a two-phase start-up mechanism in an application.
Parameters:
serviceType - Used as the first part of the logging prefix
serviceName - Concatenated with the serviceType to give the logging prefix
serviceMgrContext - The context where the ServiceFrameworkManager has been created
allServicesInitialisedCb - This is the callback function that the User provided in the Service initialisation function. This function will be called after the com.apama.config.Activate() event has been sent, and all Service that have been registered with the Service Framework Manager have been configured. The Callback function returns the ServiceId of the Service Interface that fully initialised
Returns:
A unique serviceId for this service
See Also:
com.apama.config.Activate - The Service Framework activation request event
com.apama.service.framework.ServiceInterface#initialiseWithConfig() - This Service initialisation function should be used instead if the Service needs to call the User back to provide configuration prior to the second phase.

initialiseWithConfig

integer initialiseWithConfig(string serviceType, string serviceName, context serviceMgrContext, action<integer, dictionary<string, string>, action<>> serviceInitialisedCb, action<integer> allServicesInitialisedCb)
The initialisation action that is used to create a Service Interface that can be used to provide a two-phase startup mechanism in an application.

This action is used where the Service to be created also needs to perform some configuration as part of the first-phase of the application startup.
Parameters:
serviceType - Used as the first part of the logging prefix
serviceName - Concatenated with the serviceType to give the logging prefix
serviceMgrContext - The context where the ServiceFrameworkManager has been created
serviceInitialisedCb - This is the callback function that the User provided in the Service initialisation function. This function will be called after the com.apama.config.Activate() event has been sent, and the Service has been registered/initialised by the Service Framework Manager. The Callback function returns both the ServiceId of the ServiceInterface that was initialised, and a callback function that must be called once the User has completed any configuration that was required. A default implementation of this function ("defaultServiceInitialisedCb()") is provided by the ServiceInterface object if required
allServicesInitialisedCb - This is the callback function that the User provided in the Service initialisation function. This function will be called after the com.apama.config.Activate() event has been sent, and all Service that have been registered with the Service Framework Manager have been configured. The Callback function returns the ServiceId of the Service Interface that fully initialised
Returns:
A unique serviceId for this service
See Also:
com.apama.config.Activate - The Service Framework activation request event
com.apama.service.framework.ServiceInterface#defaultServiceInitialisedCb() - This is a default implementation of the ServiceInitialised callback function.
com.apama.service.framework.ServiceInterface#initialise() - This Service initialisation function should be used instead if the Service does not need to call the user back to be configured prior to the second phase.

removeErrorCallback

void removeErrorCallback(integer refId)
This action allows the application to remove error callback that was added by the "addErrorCallback()" action using the reference Id provided.
Parameters:
refId - The reference ID as returned from the call to the "addErrorCallback()" action
See Also:
com.apama.service.framework.ServiceInterface#addErrorCallback() - 

setServiceManagerContext

void setServiceManagerContext(context serviceManagerContext)
This action sets the context that the Service Framework Manager resides in.
Parameters:
serviceManagerContext

setServiceParameters

void setServiceParameters(string serviceType, string serviceName, dictionary<string, string> parameters)
This action will set parameter dictionary of services in the Service Framework manager.

You can set the parameters for any specific service, or for all services of a type by leaving the service name parameter blank. The supplied parameters are merged with any already in the Service Framework manager.
Parameters:
serviceType - The type of the service to request config for
serviceName - The name of the service to request config for. This may be left blank to request the config for all services of a type.
parameters - The dictionary of key:value pair parameters to be set.
Routes:
com.apama.service.framework.ServiceParameters - 
Sends:
com.apama.service.framework.ServiceParameters - 

waitForService

void waitForService(string serviceType, string serviceName, context serviceMgrContext, action<com.apama.service.framework.ServiceConfig> cbServiceReady)
This action will wait until the Service Framework has been activated, and the Service Name/Type provided has been fully initialised.

The user-defined action will be called when a Service that matches the name and type requested has been registered and activated. This call back will also provide details of any configuration that was applied to that Service. If an error occurs and an error callback has not been provided, it will be logged to the Correlator log. If an error callback was provided, it will be called instead. In either case the action callback provided will not be called if an error occurred.
Parameters:
serviceType - The type of the service to request config for
serviceName - The name of the service to request config for. This may be left blank to request the config for all services of a type.
serviceMgrContext - The context that the Service Framework Manager service resides in (typically the main context)
cbServiceReady - This action callback is provided by the User and is called when the Service Name/Type requested is ready