Chapter 33 Creating Service Components

Introduction

Service components perform background processing or provide common services for Jaguar clients and other Jaguar 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

What are service components?

Service components are like any other Jaguar component, except that:

They must implement the methods in the CtsServices::GenericService interface.
Instances are loaded and initialized when the Jaguar 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.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.See Chapter 32, "Using the Thread Manager" for more information.

The GenericService interface

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 Jaguar Manager.

Jaguar server 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 Jaguar 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 All Properties 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 a Jaguar 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 or the Jaguar 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.

WARNING!

Your run() method must either return immediately or call the Thread.sleep() Java method, the Jaguar 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.

stop() Called when the server is shutting down or when the component has been refreshed from Jaguar Manager (refresh stops the service and reloads it). The stop() method is provided so that you can stop the execution of the run() method in services that perform background processing.

Implementing other interfaces

Your component can implement additional interfaces. Jaguar 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, Jaguar 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 Jaguar calls the run() method.