KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > services > daemon > DaemonService


1 /*
2
3    Derby - Class org.apache.derby.iapi.services.daemon.DaemonService
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.iapi.services.daemon;
23
24 import org.apache.derby.iapi.services.sanity.SanityManager;
25
26 /**
27
28   A DaemonService provides a background service which is suitable for
29   asynchronous I/O and general clean up. It should not be used as a general
30   worker thread for parallel execution. A DaemonService can be subscribe to by
31   many Serviceable objects and a DaemonService will call that object's
32   performWork from time to time. The performWork method is defined by the
33   client object and should be well behaved - in other words, it should not take
34   too long or hog too many resources or deadlock with anyone else. And it
35   cannot (should not) error out.
36
37   <P>It is up to each <code>DaemonService</code> implementation to define its
38   level of service, including
39   <UL>
40   <LI>how quickly and how often the clients should expect to be be serviced
41   <LI>how the clients are prioritized
42   <LI>whether the clients need to tolerate spurious services
43   </UL>
44  
45   <P>MT - all routines on the interface must be MT-safe.
46
47   @see Serviceable
48 */
49
50 public interface DaemonService
51 {
52     public static int TIMER_DELAY = 10000; // wake up once per TIMER_DELAY milli-second
53
54
55     /**
56         Trace flag that can be used by Daemons to print stuff out
57     */
58     public static final String JavaDoc DaemonTrace = SanityManager.DEBUG ? "DaemonTrace" : null;
59
60     /**
61         Trace flag that can be used to turn off background daemons
62         If DaemonOff is set, background Daemon will not attempt to do anything.
63     */
64     public static final String JavaDoc DaemonOff = SanityManager.DEBUG ? "DaemonOff" : null;
65
66
67     /**
68         Add a new client that this daemon needs to service
69
70         @param newClient a Serviceable object this daemon will service from time to time
71         @param onDemandOnly only service this client when it ask for service with a serviceNow request
72         @return a client number that uniquely identifies this client (this subscription)
73     */
74     public int subscribe(Serviceable newClient, boolean onDemandOnly);
75
76
77     /**
78         Get rid of a client from the daemon. If a client is being serviced when
79         the call is made, the implementation may choose whether or not the call
80         should block until the client has completed its work. If the call does
81         not block, the client must be prepared to handle calls to its
82         <code>performWork()</code> method even after <code>unsubscribe()</code>
83         has returned.
84
85         @param clientNumber the number that uniquely identify the client
86     */
87     public void unsubscribe(int clientNumber);
88
89
90     /**
91         Service this subscription ASAP. Does not guarantee that the daemon
92         will actually do anything about it.
93
94         @param clientNumber the number that uniquely identify the client
95      */
96     public void serviceNow(int clientNumber);
97
98
99     /**
100         Request a one time service from the Daemon. Unless performWork returns
101         REQUEUE (see Serviceable), the daemon will service this client once
102         and then it will get rid of this client. Since no client number is
103         associated with this client, it cannot request to be serviced or be
104         unsubscribed.
105
106         The work is always added to the deamon, regardless of the
107         state it returns.
108
109         @param newClient the object that needs a one time service
110
111         @param serviceNow if true, this client should be serviced ASAP, as if a
112         serviceNow has been issued. If false, then this client will be
113         serviced with the normal scheduled.
114
115         @return true if the daemon indicates it is being overloaded,
116         false it's happy.
117     */
118     public boolean enqueue(Serviceable newClient, boolean serviceNow);
119
120     /**
121         Pause. No new service is performed until a resume is issued.
122     */
123     public void pause();
124     
125
126     /**
127         Resume service after a pause
128     */
129     public void resume();
130     
131
132     /**
133         End this daemon service
134      */
135     public void stop();
136
137     /**
138         Clear all the queued up work from this daemon. Subscriptions are not
139         affected.
140      */
141     public void clear();
142
143     /*
144      *Wait until work in the high priorty queue is done.
145      */
146     public void waitUntilQueueIsEmpty();
147     
148 }
149
150
Popular Tags