KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * Copyright (C) The Apache Software Foundation. All rights reserved.
3  *
4  * This software is published under the terms of the Apache Software License
5  * version 1.1, a copy of which has been included with this distribution in
6  * the LICENSE.txt file.
7  */
8 package org.apache.avalon.excalibur.event;
9
10 /**
11  * A Source implements the end of a finite-length event queue where QueueElements
12  * are enqueued. These operations can throw a SourceException if the sink is
13  * closed or becomes full, allowing event queues to support thresholding and
14  * backpressure.
15  *
16  * @author <a HREF="mailto:bloritsch@apache.org">Berin Loritsch</a>
17  */
18 public interface Source {
19
20     /**
21      * Enqueues the given element onto the queue.
22      *
23      * @param element The <code>QueueElement</code> to enqueue
24      * @exception SourceFullException Indicates that the sink is temporarily full.
25      * @exception SourceClosedException Indicates that the sink is
26      * no longer being serviced.
27      */
28     void enqueue( QueueElement element )
29         throws SourceException;
30
31     /**
32      * Given an array of elements, atomically enqueues all of the elements
33      * in the array. This guarantees that no other thread can interleave its
34      * own elements with those being inserted from this array. The
35      * implementation must enqueue all of the elements or none of them;
36      * if a SourceFullException or SourceClosedException is thrown, none of
37      * the elements will have been enqueued.
38      *
39      * @param elements The element array to enqueue
40      * @exception SourceFullException Indicates that the sink is temporarily full.
41      * @exception SourceClosedException Indicates that the sink is
42      * no longer being serviced.
43      *
44      */
45     void enqueue( QueueElement[] elements )
46         throws SourceException;
47
48     /**
49      * Tries to enqueue an event, but instead of throwing exceptions, it returns
50      * a boolean value of whether the attempt was successful.
51      *
52      * @param element The element to attempt to enqueue
53      * @return <code>true</code> if successful, <code>false</code> if not.
54      */
55     boolean tryEnqueue( QueueElement element );
56
57     /**
58      * Support for transactional enqueue.
59      *
60      * <p>This method allows a client to provisionally enqueue a number
61      * of elements onto the queue, and then later commit the enqueue (with
62      * a <pre>commitEnqueue</code> call), or abort (with an
63      * <code>abortEnqueue</code> call). This mechanism can be used to
64      * perform "split-phase" enqueues, where a client first enqueues a
65      * set of elements on the queue and then performs some work to "fill in"
66      * those elements before performing a commit. This can also be used
67      * to perform multi-queue transactional enqueue operations, with an
68      * "all-or-nothing" strategy for enqueueing events on multiple queues.</p>
69      *
70      * <p>This method would generally be used in the following manner:</p>
71      * <pre>
72      * PreparedEnqueue enqueue = sink.prepareEnqueue(someElements);
73      * if (canCommit) {
74      * enqueue.commit();
75      * } else {
76      * enqueue.abort();
77      * }
78      * </pre>
79      *
80      * <p> Note that this method does <strong>not</strong> protect against
81      * "dangling prepares" -- that is, a prepare without an associated
82      * commit or abort operation. This method should be used with care.
83      * In particular, be sure that all code paths (such as exceptions)
84      * after a prepare include either a commit or an abort.</p>
85      *
86      * @param elements The element array to provisionally enqueue
87      * @return A <code>PreparedEnqueue</code that may be used to commit or abort
88      * the provisional enqueue
89      * @exception SourceFullException Indicates that the sink is temporarily full
90      * and that the requested elements could not be provisionally
91      * enqueued.
92      * @exception SourceClosedException Indicates that the sink is
93      * no longer being serviced.
94      *
95      * @see PreparedEnqueue
96      */
97     PreparedEnqueue prepareEnqueue( QueueElement[] elements )
98         throws SourceException;
99
100     /**
101      * Returns the number of elements waiting in this queue.
102      */
103     int size();
104
105
106     /**
107      * Returns the length threshold of the sink. This is for informational
108      * purposes only; an implementation may allow more (or fewer) new
109      * entries to be enqueued than maxSize() - size(). This may be the
110      * case, for example, if the sink implements some form of dynamic
111      * thresholding, and does not always accurately report maxSize().
112      *
113      * @return -1 if the sink has no length threshold.
114      */
115     int maxSize();
116
117     /**
118      * Returns true if this sink has reached its threshold; false otherwise.
119      * Like maxSize(), this is also informational, and isFull() returning
120      * false does not guarantee that future enqueue operations will succeed.
121      * Clearly, isFull() returning true does not guarantee that they will
122      * fail, since the queue may be serviced in the meantime.
123      */
124     boolean isFull();
125
126     /**
127      * Returns the number of QueueElements it can currently accept. This is
128      * typically the difference between <code>size()</code> and
129      * <code>maxSize()</code>. It will return -1 if the queue is unbounded.
130      */
131     int canAccept();
132
133 }
134
Popular Tags