Service components perform background processing or provide common services for EAServer clients and other EAServer components. For example, you might create service components to perform the following tasks:
Maintain cached copies of commonly used database tables
Move or replicate data between data sources during server idle time
Manage application-specific log files
Service components are like any other EAServer component, except that:
They must implement the methods in the CtsServices::GenericService interface.
Instances are loaded and initialized when the host server starts.
They can run independently of client interaction.
The Thread Manager and service components
You can use the Thread Manager as an alternative to creating
a service component to handle repetitive processing. You may find
the Thread Manager interface allows more design flexibility. For
example, you can suspend processing in services run by the Thread
Manager, and you can start threads at any time rather than only
at server start-up. Chapter 32, “Using the Thread Manager” describes
how to use the thread manager.
PowerBuilder developers can use the Thread Manager to develop more robust services. Since PowerBuilder components cannot support sharing and concurrency, you cannot develop a service that can be stopped or refreshed without using the Thread Manager. For more information, see the Application Techniques manual in the PowerBuilder documentation.
Your component implementation must implement all the methods in the CtsServices::GenericService interface. Your implementation does not need to explicitly implement the interface (that is, list it in the implements clause of the class declaration), and you do not need to list the interface in the component’s Interfaces folder in EAServer Manager.
EAServer calls the CtsServices::GenericService methods to indicate transitions in the service’s state:
start() Called to initialize the component when the server starts or when the component has been refreshed from EAServer Manager. This method typically initializes data structures and resources that the service requires. For example:
A service that writes to log files would open each file and cache each file handle as a class instance variable.
A service that caches tabular data from a remote database would open a connection to the database and create the data structures required to store tabular data in memory.
Service components that make intercomponent calls
If your start method makes intercomponent
calls, check the com.sybase.jaguar.server.bindrefresh property
for the servers where your component is installed. Use the Advanced
tab in the Server Properties dialog box to view and change this
property. This property must be set to “start” to
allow name service lookups in the start method
of service components. The default setting is “run”.
run() Called after the first invocation of start() returns. run() can loop and perform repetitive tasks as an EAServer background process. If the component does not perform background processing, run() can return immediately.
For services that perform background processing, run() should loop continuously while performing the service task. run() must periodically suspend its own execution by calling the Java java.lang.Thread.sleep() method, one of the Java Object.wait() methods, or the EAServer JagSleep C routine. These APIs suspend the current thread for a specified duration so that other threads may execute. run() should return after the server invokes the stop() method.
If you configure your service to run in multiple threads, EAServer calls run() concurrently in the specified number of threads.
WARNING! Your run() method must either return immediately or call one of the Object.wait() Java methods, the EAServer JagSleep C routine, or some other thread-aware implementation of sleep. Do not call the sleep system routine or any other routine that suspends process (and not thread) execution. If coding service components in PowerBuilder, code your component to call the JagSleep C routine; do not use the PowerBuilder timer event, which may suspend the EAServer process.
stop() Called when the server is shutting down or when the component has been refreshed from EAServer Manager (refresh stops the service and reloads it). EAServer calls the stop() method on a different thread than the run() method. Code in the stop() method should set a flag that indicates the the run() method should return.
stop() should also wake up sleeping run() threads if the language allows this. For example, in Java, call the Object.notifyAll() method to wake threads that called Object.wait() on the same monitor object. In languages that do not allow you to wake up sleeping threads, keep your sleep interval reasonably short. The service cannot be refreshed until all running threads return from the run() method; that is, if your sleep interval is one hour, it can take that long to refresh the service unless you add code to wake up sleeping threads.
Your component can implement additional interfaces. EAServer clients, servlets, and other components can execute a service component’s methods like those of any other component, with one exception: Clients cannot invoke methods on the service component until the start() method has returned. This restriction allows you to perform required initialization in start() without worrying about thread synchronization issues.
After start() returns, EAServer calls the run() method in its own thread. Client method invocations may arrive at this time as well. There is no guarantee that run() will have been called when a client method invocation occurs; the first client invocations may arrive before EAServer calls the run() method.
