001: /*
002:
003: Derby - Class org.apache.derby.iapi.services.daemon.Serviceable
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.context.ContextManager;
025: import org.apache.derby.iapi.error.StandardException;
026:
027: /**
028: To use a DaemonService, one implements the Serviceable interface. Only one
029: DaemonService will call this at any given time. However, if this Serviceable
030: object subscribes to or enqueues to the DeamonService multiple times, then
031: multiple DaemonService threads may call this Serviceable object at the same
032: time. The Serviceable object must decide what synchronization it needs to
033: provide depending on what work it needs to do.
034:
035: The Serviceable interface does not provide a way to pass a work object to
036: identify what work needs to be done, it is assumed that the Serviceable
037: object knows that. If a Serviceable object has different work for the
038: DaemonService to do, it must somehow encapsulate or identify the different
039: work by an intermediary object which implements the Serviceable interface and
040: which can an identify the different work and pass it along to the object that
041: can deal with them.
042: */
043:
044: public interface Serviceable {
045:
046: /**
047: Do whatever it is that you want the daemon to do for you. There may be
048: multiple daemon objects on different thread calling performWork at the
049: same time.
050:
051: The DaemonService will always call performWork with a context manager
052: set up. the DaemonService will clean up the context if an exception is
053: thrown. However, it is up to performWork to manage its own
054: transaction. If you start a transaction in performWork, you
055: <B>must</B> commit or abort it at the end. You may leave the
056: transaction open so that other serviceable may use the transaction and
057: context without starting a new one. On the same token, there may
058: already be an opened transaction on the context. Serviceable
059: performWork should always check the state of the context before use.
060:
061: A Serviceable object should be well behaved while it is performing the
062: daemon work, i.e., it should not take too many resources or hog the CPU
063: for too long or deadlock with anyone else.
064:
065: @param context the contextManager set up by the DaemonService. There
066: may or may not be the necessary context on it, depending on which other
067: Serviceable object it has done work for.
068: @return the return status is only significant if the Serviceable client
069: was enqueued instead of subscribed. For subscribed client, the return
070: status is ignored. For enqueue client, it returns DONE or REQUEUE. If
071: a REQUEUEd is returned, it would be desirable if this should not be
072: serviceASAP, although no harm is done if this still maintains that this
073: should be serviced ASAP ...
074:
075: @exception StandardException Standard cloudscape exception policy
076:
077: <P>MT - depends on the work. Be wary of multiple DaemonService thread
078: calling at the same time if you subscribe or enqueue multiple times.
079: */
080: public int performWork(ContextManager context)
081: throws StandardException;
082:
083: /** return status for performWork - only meaningful for enqueued client */
084: public static int DONE = 1; // the daemon work is finished, the
085: // DaemonService can get rid of this client
086: public static int REQUEUE = 2;// the daemon work is not finished, requeue
087:
088: // the request to be serviced again later.
089:
090: /**
091: If this work should be done as soon as possible, then return true.
092: If it doesn't make any difference if it is done sooner rather than
093: later, then return false.
094:
095: The difference is whether or not the daemon service will be notified to
096: work on this when this work is enqueued or subscribed, in case the
097: serviceable work is put together but not sent to the daemon service
098: directly, like in post commit processing
099:
100: <P>MT - MT safe
101: */
102: public boolean serviceASAP();
103:
104: /**
105: If this work should be done immediately on the user thread then return true.
106: If it doesn't make any difference if this work is done on a the user thread
107: immediately or if it is performed by another thread asynchronously
108: later, then return false.
109: */
110: public boolean serviceImmediately();
111:
112: }
|