KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > excalibur > event > Sink


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
12  * implied.
13  *
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 package org.apache.excalibur.event;
18
19 /**
20  * A Sink implements the end of a finite-length event queue where
21  * elements are enqueued. These operations can throw a
22  * <code>SinkException</code> if the sink is closed or becomes full, allowing
23  * event queues to support thresholding and backpressure.
24  *
25  * <p>
26  * The interface design is heavily influenced by
27  * <a HREF="mailto:mdw@cs.berkeley.edu">Matt Welsh</a>'s SandStorm server,
28  * his demonstration of the SEDA architecture. We have deviated where we
29  * felt the design differences where better.
30  * </p>
31  *
32  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
33  */
34 public interface Sink
35 {
36     String JavaDoc ROLE = Sink.class.getName();
37
38     /**
39      * Enqueues the given element onto the Sink.
40      *
41      * @param element The elements to enqueue
42      * @throws SinkFullException Indicates that the sink is temporarily full.
43      * @throws SinkClosedException Indicates that the sink is
44      * no longer being serviced.
45      */
46     void enqueue( Object JavaDoc element )
47         throws SinkException;
48
49     /**
50      * Given an array of elements, atomically enqueues all of the elements
51      * in the array. This guarantees that no other thread can interleave its
52      * own elements with those being inserted from this array. The
53      * implementation must enqueue all of the elements or none of them;
54      * if a SinkFullException or SinkClosedException is thrown, none of
55      * the elements will have been enqueued.
56      *
57      * @param elements The element array to enqueue
58      * @throws SinkFullException Indicates that the sink is temporarily full.
59      * @throws SinkClosedException Indicates that the sink is
60      * no longer being serviced.
61      *
62      */
63     void enqueue( Object JavaDoc[] elements )
64         throws SinkException;
65
66     /**
67      * Tries to enqueue an event, but instead of throwing exceptions, it
68      * returns a boolean value of whether the attempt was successful.
69      *
70      * @param element The element to attempt to enqueue
71      * @return <code>true</code> if successful, <code>false</code> if not.
72      */
73     boolean tryEnqueue( Object JavaDoc element );
74
75     /**
76      * Support for transactional enqueue.
77      *
78      * <p>This method allows a client to provisionally enqueue a number
79      * of elements onto the queue, and then later commit the enqueue (with
80      * a <code>commitEnqueue</code> call), or abort (with an
81      * <code>abortEnqueue</code> call). This mechanism can be used to
82      * perform "split-phase" enqueues, where a client first enqueues a
83      * set of elements on the queue and then performs some work to "fill in"
84      * those elements before performing a commit. This can also be used
85      * to perform multi-queue transactional enqueue operations, with an
86      * "all-or-nothing" strategy for enqueueing events on multiple Sinks.
87      * </p>
88      *
89      * <p>This method would generally be used in the following manner:</p>
90      * <pre>
91      * PreparedEnqueue enqueue = sink.prepareEnqueue(someElements);
92      * if (canCommit) {
93      * enqueue.commit();
94      * } else {
95      * enqueue.abort();
96      * }
97      * </pre>
98      *
99      * <p> Note that this method does <strong>not</strong> protect against
100      * "dangling prepares" -- that is, a prepare without an associated
101      * commit or abort operation. This method should be used with care.
102      * In particular, be sure that all code paths (such as exceptions)
103      * after a prepare include either a commit or an abort.</p>
104      *
105      * @param elements The element array to provisionally enqueue
106      * @return A <code>PreparedEnqueue</code> that may be used to commit or
107      * abort the provisional enqueue
108      * @throws SinkFullException Indicates that the sink is
109      * temporarily full and that the requested elements could not
110      * be provisionally enqueued.
111      * @throws SinkClosedException Indicates that the sink is
112      * no longer being serviced.
113      *
114      * @see PreparedEnqueue
115      */
116     PreparedEnqueue prepareEnqueue( Object JavaDoc[] elements )
117         throws SinkException;
118
119     /**
120      * Returns the length threshold of the sink. This is for informational
121      * purposes only; an implementation may allow more (or fewer) new
122      * entries to be enqueued than maxSize() - size(). This may be the
123      * case, for example, if the sink implements some form of dynamic
124      * thresholding, and does not always accurately report maxSize().
125      *
126      * @return -1 if the sink has no length threshold.
127      *
128      * @deprecated Use the EnqueuePredicate to control this instead.
129      */
130     int maxSize();
131
132     /**
133      * Returns true if this sink has reached its threshold; false otherwise.
134      * Like maxSize(), this is also informational, and isFull() returning
135      * false does not guarantee that future enqueue operations will succeed.
136      * Clearly, isFull() returning true does not guarantee that they will
137      * fail, since the Sink may be serviced in the meantime.
138      *
139      * @return true if the Sink is full
140      *
141      * @deprecated Use the EnqueuePredicate to control this instead
142      */
143     boolean isFull();
144
145     /**
146      * Returns the number of elements it can currently accept. This is
147      * typically the difference between <code>size()</code> and
148      * <code>maxSize()</code>. It will return -1 if the sink is unbounded.
149      *
150      * @return the number of elements the Sink can accept
151      *
152      * @deprecated Use the EnqueuePredicate to control this instead.
153      */
154     int canAccept();
155
156     /**
157      * Returns the number of elements waiting in this Sink.
158      *
159      * <p><span style="color: blue;"><i>Important:</i></span>
160      * The contract for this method was updated to account for any elements
161      * that were prepared for enqueueing. It provides a more predictable
162      * and consistent environment, as well as making it easier for
163      * EnqueuePredicates to account for those elements.
164      * </p>
165      *
166      * @return the number of elements in the Sink
167      */
168     int size();
169 }
170
Popular Tags