01: /*
02:
03: Derby - Class org.apache.derby.iapi.services.daemon.DaemonFactory
04:
05: Licensed to the Apache Software Foundation (ASF) under one or more
06: contributor license agreements. See the NOTICE file distributed with
07: this work for additional information regarding copyright ownership.
08: The ASF licenses this file to you under the Apache License, Version 2.0
09: (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.error.StandardException;
25:
26: /**
27: Daemon Factory can create new DaemonService, which runs on seperate
28: background threads. One can use these DaemonService to handle background
29: clean up task by implementing Serviceable and subscribing to a DaemonService.
30:
31: A DaemonService is a background worker thread which does asynchronous I/O and
32: general clean up. It should not be used as a general worker thread for
33: parallel execution. A DaemonService can be subscribe to by many Serviceable
34: objects and a daemon will call that object's performWork from time to
35: time. These performWork method should be well behaved - in other words,
36: it should not take too long or hog too many resources or deadlock with
37: anyone else. And it cannot (should not) error out.
38:
39: The best way to use a daemon is to have an existing DaemonService and subscribe to it.
40: If you can't find an existing one, then make one thusly:
41:
42: DaemonService daemon = DaemonFactory.createNewDaemon();
43:
44: After you have a daemon, you can subscribe to it by
45: int myClientNumber = daemon.subscribe(serviceableObject);
46:
47: and ask it to run performWork for you ASAP by
48: daemon.serviceNow(myClientNumber);
49:
50: Or, for one time service, you can enqueue a Serviceable Object by
51: daemon.enqueue(serviceableObject, true); - urgent service
52: daemon.enqueue(serviceableObject, false); - non-urgent service
53:
54: @see DaemonService
55: @see Serviceable
56: */
57: public interface DaemonFactory {
58: /**
59: Create a new DaemonService with the default daemon timer delay.
60:
61: @exception StandardException Standard cloudscape error policy
62: */
63: public DaemonService createNewDaemon(String name)
64: throws StandardException;
65: }
|