Source code: org/apache/derby/iapi/services/daemon/Serviceable.java
1 /*
2
3 Derby - Class org.apache.derby.iapi.services.daemon.Serviceable
4
5 Copyright 1997, 2004 The Apache Software Foundation or its licensors, as applicable.
6
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
10
11 http://www.apache.org/licenses/LICENSE-2.0
12
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18
19 */
20
21 package org.apache.derby.iapi.services.daemon;
22
23 import org.apache.derby.iapi.services.context.ContextManager;
24 import org.apache.derby.iapi.error.StandardException;
25
26 /**
27 To use a DaemonService, one implements the Serviceable interface. Only one
28 DaemonService will call this at any given time. However, if this Serviceable
29 object subscribes to or enqueues to the DeamonService multiple times, then
30 multiple DaemonService threads may call this Serviceable object at the same
31 time. The Serviceable object must decide what synchronization it needs to
32 provide depending on what work it needs to do.
33
34 The Serviceable interface does not provide a way to pass a work object to
35 identify what work needs to be done, it is assumed that the Serviceable
36 object knows that. If a Serviceable object has different work for the
37 DaemonService to do, it must somehow encapsulate or identify the different
38 work by an intermediary object which implements the Serviceable interface and
39 which can an identify the different work and pass it along to the object that
40 can deal with them.
41 */
42
43 public interface Serviceable {
44
45 /**
46 Do whatever it is that you want the daemon to do for you. There may be
47 multiple daemon objects on different thread calling performWork at the
48 same time.
49
50 The DaemonService will always call performWork with a context manager
51 set up. the DaemonService will clean up the context if an exception is
52 thrown. However, it is up to performWork to manage its own
53 transaction. If you start a transaction in performWork, you
54 <B>must</B> commit or abort it at the end. You may leave the
55 transaction open so that other serviceable may use the transaction and
56 context without starting a new one. On the same token, there may
57 already be an opened transaction on the context. Serviceable
58 performWork should always check the state of the context before use.
59
60 A Serviceable object should be well behaved while it is performing the
61 daemon work, i.e., it should not take too many resources or hog the CPU
62 for too long or deadlock with anyone else.
63
64 @param context the contextManager set up by the DaemonService. There
65 may or may not be the necessary context on it, depending on which other
66 Serviceable object it has done work for.
67 @return the return status is only significant if the Serviceable client
68 was enqueued instead of subscribed. For subscribed client, the return
69 status is ignored. For enqueue client, it returns DONE or REQUEUE. If
70 a REQUEUEd is returned, it would be desirable if this should not be
71 serviceASAP, although no harm is done if this still maintains that this
72 should be serviced ASAP ...
73
74 @exception StandardException Standard cloudscape exception policy
75
76 <P>MT - depends on the work. Be wary of multiple DaemonService thread
77 calling at the same time if you subscribe or enqueue multiple times.
78 */
79 public int performWork(ContextManager context) throws StandardException;
80
81
82 /** return status for performWork - only meaningful for enqueued client */
83 public static int DONE = 1; // the daemon work is finished, the
84 // DaemonService can get rid of this client
85 public static int REQUEUE = 2;// the daemon work is not finished, requeue
86 // the request to be serviced again later.
87
88
89
90 /**
91 If this work should be done as soon as possible, then return true.
92 If it doesn't make any difference if it is done sooner rather than
93 later, then return false.
94
95 The difference is whether or not the daemon service will be notified to
96 work on this when this work is enqueued or subscribed, in case the
97 serviceable work is put together but not sent to the daemon service
98 directly, like in post commit processing
99
100 <P>MT - MT safe
101 */
102 public boolean serviceASAP();
103
104
105 /**
106 If this work should be done immediately on the user thread then return true.
107 If it doesn't make any difference if this work is done on a the user thread
108 immediately or if it is performed by another thread asynchronously
109 later, then return false.
110 */
111 public boolean serviceImmediately();
112
113 }
114