001: /*
002:
003: Derby - Class org.apache.derby.iapi.services.daemon.DaemonService
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.services.daemon;
023:
024: import org.apache.derby.iapi.services.sanity.SanityManager;
025:
026: /**
027:
028: A DaemonService provides a background service which is suitable for
029: asynchronous I/O and general clean up. It should not be used as a general
030: worker thread for parallel execution. A DaemonService can be subscribe to by
031: many Serviceable objects and a DaemonService will call that object's
032: performWork from time to time. The performWork method is defined by the
033: client object and should be well behaved - in other words, it should not take
034: too long or hog too many resources or deadlock with anyone else. And it
035: cannot (should not) error out.
036:
037: <P>It is up to each <code>DaemonService</code> implementation to define its
038: level of service, including
039: <UL>
040: <LI>how quickly and how often the clients should expect to be be serviced
041: <LI>how the clients are prioritized
042: <LI>whether the clients need to tolerate spurious services
043: </UL>
044:
045: <P>MT - all routines on the interface must be MT-safe.
046:
047: @see Serviceable
048: */
049:
050: public interface DaemonService {
051: public static int TIMER_DELAY = 10000; // wake up once per TIMER_DELAY milli-second
052:
053: /**
054: Trace flag that can be used by Daemons to print stuff out
055: */
056: public static final String DaemonTrace = SanityManager.DEBUG ? "DaemonTrace"
057: : null;
058:
059: /**
060: Trace flag that can be used to turn off background daemons
061: If DaemonOff is set, background Daemon will not attempt to do anything.
062: */
063: public static final String DaemonOff = SanityManager.DEBUG ? "DaemonOff"
064: : null;
065:
066: /**
067: Add a new client that this daemon needs to service
068:
069: @param newClient a Serviceable object this daemon will service from time to time
070: @param onDemandOnly only service this client when it ask for service with a serviceNow request
071: @return a client number that uniquely identifies this client (this subscription)
072: */
073: public int subscribe(Serviceable newClient, boolean onDemandOnly);
074:
075: /**
076: Get rid of a client from the daemon. If a client is being serviced when
077: the call is made, the implementation may choose whether or not the call
078: should block until the client has completed its work. If the call does
079: not block, the client must be prepared to handle calls to its
080: <code>performWork()</code> method even after <code>unsubscribe()</code>
081: has returned.
082:
083: @param clientNumber the number that uniquely identify the client
084: */
085: public void unsubscribe(int clientNumber);
086:
087: /**
088: Service this subscription ASAP. Does not guarantee that the daemon
089: will actually do anything about it.
090:
091: @param clientNumber the number that uniquely identify the client
092: */
093: public void serviceNow(int clientNumber);
094:
095: /**
096: Request a one time service from the Daemon. Unless performWork returns
097: REQUEUE (see Serviceable), the daemon will service this client once
098: and then it will get rid of this client. Since no client number is
099: associated with this client, it cannot request to be serviced or be
100: unsubscribed.
101:
102: The work is always added to the deamon, regardless of the
103: state it returns.
104:
105: @param newClient the object that needs a one time service
106:
107: @param serviceNow if true, this client should be serviced ASAP, as if a
108: serviceNow has been issued. If false, then this client will be
109: serviced with the normal scheduled.
110:
111: @return true if the daemon indicates it is being overloaded,
112: false it's happy.
113: */
114: public boolean enqueue(Serviceable newClient, boolean serviceNow);
115:
116: /**
117: Pause. No new service is performed until a resume is issued.
118: */
119: public void pause();
120:
121: /**
122: Resume service after a pause
123: */
124: public void resume();
125:
126: /**
127: End this daemon service
128: */
129: public void stop();
130:
131: /**
132: Clear all the queued up work from this daemon. Subscriptions are not
133: affected.
134: */
135: public void clear();
136:
137: /*
138: *Wait until work in the high priorty queue is done.
139: */
140: public void waitUntilQueueIsEmpty();
141:
142: }
|