--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.services.daemon.DaemonService\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.services.daemon;\r
+\r
+import org.apache.derby.iapi.services.sanity.SanityManager;\r
+\r
+/** \r
+\r
+ A DaemonService provides a background service which is suitable for\r
+ asynchronous I/O and general clean up. It should not be used as a general\r
+ worker thread for parallel execution. A DaemonService can be subscribe to by\r
+ many Serviceable objects and a DaemonService will call that object's\r
+ performWork from time to time. The performWork method is defined by the\r
+ client object and should be well behaved - in other words, it should not take\r
+ too long or hog too many resources or deadlock with anyone else. And it\r
+ cannot (should not) error out.\r
+\r
+ <P>It is up to each <code>DaemonService</code> implementation to define its\r
+ level of service, including\r
+ <UL>\r
+ <LI>how quickly and how often the clients should expect to be be serviced\r
+ <LI>how the clients are prioritized\r
+ <LI>whether the clients need to tolerate spurious services\r
+ </UL>\r
+ \r
+ <P>MT - all routines on the interface must be MT-safe.\r
+\r
+ @see Serviceable\r
+*/\r
+\r
+public interface DaemonService \r
+{\r
+ public static int TIMER_DELAY = 10000; // wake up once per TIMER_DELAY milli-second\r
+\r
+\r
+ /**\r
+ Trace flag that can be used by Daemons to print stuff out\r
+ */\r
+ public static final String DaemonTrace = SanityManager.DEBUG ? "DaemonTrace" : null;\r
+\r
+ /**\r
+ Trace flag that can be used to turn off background daemons\r
+ If DaemonOff is set, background Daemon will not attempt to do anything.\r
+ */\r
+ public static final String DaemonOff = SanityManager.DEBUG ? "DaemonOff" : null;\r
+\r
+\r
+ /**\r
+ Add a new client that this daemon needs to service\r
+\r
+ @param newClient a Serviceable object this daemon will service from time to time\r
+ @param onDemandOnly only service this client when it ask for service with a serviceNow request\r
+ @return a client number that uniquely identifies this client (this subscription) \r
+ */\r
+ public int subscribe(Serviceable newClient, boolean onDemandOnly);\r
+\r
+\r
+ /**\r
+ Get rid of a client from the daemon. If a client is being serviced when\r
+ the call is made, the implementation may choose whether or not the call\r
+ should block until the client has completed its work. If the call does\r
+ not block, the client must be prepared to handle calls to its\r
+ <code>performWork()</code> method even after <code>unsubscribe()</code>\r
+ has returned.\r
+\r
+ @param clientNumber the number that uniquely identify the client\r
+ */\r
+ public void unsubscribe(int clientNumber);\r
+\r
+\r
+ /**\r
+ Service this subscription ASAP. Does not guarantee that the daemon\r
+ will actually do anything about it.\r
+\r
+ @param clientNumber the number that uniquely identify the client\r
+ */\r
+ public void serviceNow(int clientNumber);\r
+\r
+\r
+ /**\r
+ Request a one time service from the Daemon. Unless performWork returns\r
+ REQUEUE (see Serviceable), the daemon will service this client once\r
+ and then it will get rid of this client. Since no client number is\r
+ associated with this client, it cannot request to be serviced or be\r
+ unsubscribed. \r
+\r
+ The work is always added to the deamon, regardless of the\r
+ state it returns.\r
+\r
+ @param newClient the object that needs a one time service\r
+\r
+ @param serviceNow if true, this client should be serviced ASAP, as if a\r
+ serviceNow has been issued. If false, then this client will be\r
+ serviced with the normal scheduled.\r
+\r
+ @return true if the daemon indicates it is being overloaded,\r
+ false it's happy.\r
+ */\r
+ public boolean enqueue(Serviceable newClient, boolean serviceNow);\r
+\r
+ /**\r
+ Pause. No new service is performed until a resume is issued.\r
+ */\r
+ public void pause();\r
+ \r
+\r
+ /**\r
+ Resume service after a pause\r
+ */\r
+ public void resume();\r
+ \r
+\r
+ /**\r
+ End this daemon service\r
+ */\r
+ public void stop();\r
+\r
+ /**\r
+ Clear all the queued up work from this daemon. Subscriptions are not\r
+ affected. \r
+ */\r
+ public void clear();\r
+\r
+ /*\r
+ *Wait until work in the high priorty queue is done.\r
+ */ \r
+ public void waitUntilQueueIsEmpty();\r
+ \r
+}\r
+\r