Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.iapi.services.daemon.DaemonService

A DaemonService provides a background service which is suitable for asynchronous I/O and general clean up. It should not be used as a general worker thread for parallel execution. A DaemonService can be subscribe to by many Serviceable objects and a DaemonService will call that object's performWork from time to time. The performWork method is defined by the client object and should be well behaved - in other words, it should not take too long or hog too many resources or deadlock with anyone else. And it cannot (should not) error out.

It is up to each DaemonService implementation to define its level of service, including

how quickly and how often the clients should expect to be be serviced
how the clients are prioritized
whether the clients need to tolerate spurious services

MT - all routines on the interface must be MT-safe.

Field Summary

Modifier and Type	Field and Description
public static final String	DaemonOff Trace flag that can be used to turn off background daemons If DaemonOff is set, background Daemon will not attempt to do anything.
public static final String	DaemonTrace Trace flag that can be used by Daemons to print stuff out
public static final int	TIMER_DELAY

Method Summary

Modifier and Type	Method and Description
public void	clear() Clear all the queued up work from this daemon.
public boolean	Returns: true if the daemon indicates it is being overloaded, false it's happy. enqueue(Serviceable the object that needs a one time service newClient, boolean if true, this client should be serviced ASAP, as if a serviceNow has been issued. If false, then this client will be serviced with the normal scheduled. serviceNow) Request a one time service from the Daemon.
public void	pause() Pause.
public void	resume() Resume service after a pause
public void	serviceNow(int the number that uniquely identifies the client clientNumber) Service this subscription ASAP.
public void	stop() End this daemon service
public int	Returns: a client number that uniquely identifies this client (this subscription) subscribe(Serviceable a Serviceable object this daemon will service from time to time newClient, boolean only service this client when it ask for service with a serviceNow request onDemandOnly) Add a new client that this daemon needs to service
public void	unsubscribe(int the number that uniquely identify the client clientNumber) Get rid of a client from the daemon.
public void	waitUntilQueueIsEmpty()

Field Detail

DaemonOff	back to summary
public static final String DaemonOff Trace flag that can be used to turn off background daemons If DaemonOff is set, background Daemon will not attempt to do anything.

DaemonTrace	back to summary
public static final String DaemonTrace Trace flag that can be used by Daemons to print stuff out

TIMER_DELAY	back to summary
public static final int TIMER_DELAY

Method Detail

clear	back to summary
public void clear() Clear all the queued up work from this daemon. Subscriptions are not affected.

enqueue	back to summary
public boolean enqueue(Serviceable newClient, boolean serviceNow) Request a one time service from the Daemon. Unless performWork returns REQUEUE (see Serviceable), the daemon will service this client once and then it will get rid of this client. Since no client number is associated with this client, it cannot request to be serviced or be unsubscribed. The work is always added to the deamon, regardless of the state it returns. Parameters newClient:Serviceable the object that needs a one time service serviceNow:boolean if true, this client should be serviced ASAP, as if a serviceNow has been issued. If false, then this client will be serviced with the normal scheduled. Returns:boolean true if the daemon indicates it is being overloaded, false it's happy.

enqueue

back to summary

public boolean enqueue(Serviceable newClient, boolean serviceNow)

Request a one time service from the Daemon. Unless performWork returns REQUEUE (see Serviceable), the daemon will service this client once and then it will get rid of this client. Since no client number is associated with this client, it cannot request to be serviced or be unsubscribed. The work is always added to the deamon, regardless of the state it returns.

Parameters

newClient:Serviceable: the object that needs a one time service
serviceNow:boolean: if true, this client should be serviced ASAP, as if a serviceNow has been issued. If false, then this client will be serviced with the normal scheduled.

Returns:boolean

true if the daemon indicates it is being overloaded, false it's happy.

pause	back to summary
public void pause() Pause. No new service is performed until a resume is issued.

resume	back to summary
public void resume() Resume service after a pause

serviceNow back to summary

serviceNow	back to summary
public void serviceNow(int clientNumber) Service this subscription ASAP. When this method is called, the subscriber's `performWork()` method is guaranteed to be invoked at some point in the future. However, there is no guarantee that a subscriber's `performWork()` is called the same number of times as the subscriber calls this method. More precisely, if a subscriber is waiting for this daemon service to invoke its `performWork()` method, the daemon service may, but is not required to, ignore requests from that subscriber until the `performWork()` method has been invoked. Parameters clientNumber:int the number that uniquely identifies the client

public void serviceNow(int clientNumber)

Service this subscription ASAP. When this method is called, the subscriber's performWork() method is guaranteed to be invoked at some point in the future. However, there is no guarantee that a subscriber's performWork() is called the same number of times as the subscriber calls this method. More precisely, if a subscriber is waiting for this daemon service to invoke its performWork() method, the daemon service may, but is not required to, ignore requests from that subscriber until the performWork() method has been invoked.

Parameters

clientNumber:int: the number that uniquely identifies the client

stop	back to summary
public void stop() End this daemon service

subscribe	back to summary
public int subscribe(Serviceable newClient, boolean onDemandOnly) Add a new client that this daemon needs to service Parameters newClient:Serviceable a Serviceable object this daemon will service from time to time onDemandOnly:boolean only service this client when it ask for service with a serviceNow request Returns:int a client number that uniquely identifies this client (this subscription)

back to summary

public int subscribe(Serviceable newClient, boolean onDemandOnly)

Add a new client that this daemon needs to service

Parameters

newClient:Serviceable: a Serviceable object this daemon will service from time to time
onDemandOnly:boolean: only service this client when it ask for service with a serviceNow request

Returns:int

a client number that uniquely identifies this client (this subscription)

unsubscribe back to summary

unsubscribe	back to summary
public void unsubscribe(int clientNumber) Get rid of a client from the daemon. If a client is being serviced when the call is made, the implementation may choose whether or not the call should block until the client has completed its work. If the call does not block, the client must be prepared to handle calls to its `performWork()` method even after `unsubscribe()` has returned. Parameters clientNumber:int the number that uniquely identify the client

public void unsubscribe(int clientNumber)

Get rid of a client from the daemon. If a client is being serviced when the call is made, the implementation may choose whether or not the call should block until the client has completed its work. If the call does not block, the client must be prepared to handle calls to its performWork() method even after unsubscribe() has returned.

Parameters

clientNumber:int: the number that uniquely identify the client

waitUntilQueueIsEmpty	back to summary
public void waitUntilQueueIsEmpty()

public Interface DaemonService

Field Summary

Method Summary

Field Detail

Method Detail