KickJava   Java API By Example, From Geeks To Geeks.

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


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