A service is a process on its own: anything that is executable and can access the Symphony API can implement a service. The service does not initiate any actions on its own. Symphony triggers all service actions.
Service containers and service instances
You create your service by extending the ServiceContainer class and implementing the required handler methods.
A running instance of a ServiceContainer is called a service instance.
Symphony assigns a number of service instances to a session according to policy, session priority, and the number of tasks in the session.
A service instance can be used to service different sessions within the same application. That is, Symphony does not need to destroy an existing service instance and start a new service instance to serve different sessions within the same application.
Service structure
The onInvoke ( ) method in ServiceContainer( ) is the only required method. All other methods are optional.
Do not do anything in your service until you:
Create a service container
Call run on the service container
When the application calls the ServiceContainer run( ) method, the service instance process registers with Symphony. The service instance is given a certain time to register before it is considered to have timed out. If your application does lengthy operations before calling the ServiceContainer run( ) method, your service instance may not be able to register before the time out expires. This is considered a failure to start the service instance.
The following diagram indicates the structure of a service with all methods implemented, in the order that they need to be implemented. Note method pairs: if you use onCreateService(), you must also use onDestroyService().

API method
|
Description
|
Action system takes
|
onCreateService( )
|
Optional. Use this method to perform any required environment set up when your service is initialized.
|
Symphony invokes onCreateService() just after it launches the service instance to initialize the service instance.
This method is called once per service instance that is started.
If the onCreateService method hangs, you should configure a timeout. To verify if the method is hanging:
Run soamview resource to show that the resource is assigned to the session.
Run soamview session -a to show that the session deserves the resource but the resource is not assigned to it
|
onDestroyService()
|
Optional. Use this method to clean up a service instance before it is destroyed.
|
Symphony invokes onDestroyService() to clean up the service instance when a service instance is ending its lifecycle, provided that onCreateService() has been called and has returned without exception.
Note: This method will not be called if a service instance crashes or exits or if a timeout occurs.
|
onSessionEnter( )
|
Optional. Use this method to load session common data into memory.
|
Symphony invokes onSessionEnter() when a service instance is assigned to a session.
Note: Note that if there is no common data in createSession( ), onSessionEnter( ) is not called.
|
onSessionUpdate( )
|
Optional. Use this method to load session updated common data into memory.
|
Symphony invokes onSessionUpdate() when a session-specific update has been propagated to the service instance.
Note: Note that if there is no common data in createSession( ), onSessionUpdate( ) is not called.
|
onSessionLeave()
|
Optional. Use this method to free up session common data that was loaded into memory with onSessionEnter().
|
Symphony invokes onSessionLeave() to do session-specific uninitialization when the service instance is unassigned from the session, provided that onSessionEnter() has been called and has returned without exception.
Note: This method will not be called if a service instance crashes or exits, a timeout occurs, or there is no common data in createSession( ).
|
onInvoke( )
|
Required. Use this method to compute a task.
|
Symphony invokes onInvoke() to compute a task. This method is called once for every input message that is sent to the service instance.
The method can be called in the same service instance multiple times to compute multiple tasks for the same session or for different sessions.
|
Service main( )
The service main() is the entry point to the service. Create the container and run it.
Restrictions
Do not implement any service initialization before calling the ServiceContainer::run() method. If any service initialization needs to be done, implement the onCreateService() handler for your service container.
Do not implement any service uninitialization after calling the ServiceContainer::run() method. If any service uninitialization is required, implement the onDestroyService() handler for your service container since there is no guarantee that the remaining code in main() will be executed after calling ServiceContainer::run(). Also, in some cases, the remaining code can even cause an orphan service instance if the code cannot be finished.