KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > info > monitorenter > util > collections > IRingBuffer


1 /*
2  * IRingBuffer, an interface for implementations of a RingBuffer.
3  * Copyright (C) 2002 Achim Westermann, Achim.Westermann@gmx.de
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18  *
19  * If you modify or optimize the code in a useful way please let me know.
20  * Achim.Westermann@gmx.de
21  */
22
23 package info.monitorenter.util.collections;
24
25 /**
26  * Interface for implementations of RingBuffers.
27  * <p>
28  *
29  * @author <a HREF='mailto:Achim.Westermann@gmx.de'>Achim Westermann </a>
30  *
31  * @version $Revision: 1.1 $
32  */
33 public interface IRingBuffer extends java.io.Serializable JavaDoc {
34
35   /**
36    * Special exception related to ringbuffer operations.
37    * <p>
38    *
39    * @author <a HREF="mailto:Achim.Westermann@gmx.de">Achim Westermann </a>
40    *
41    * @version $Revision: 1.1 $
42    */
43   public final class RingBufferException extends RuntimeException JavaDoc {
44     /**
45      * Comment for <code>serialVersionUID</code>.
46      */
47     private static final long serialVersionUID = 3762255244691714610L;
48
49
50     /**
51      * Creates an instance with the given message.
52      * <p>
53      *
54      * @param msg
55      * the message of the exception.
56      */
57     protected RingBufferException(final String JavaDoc msg) {
58       super(msg);
59     }
60   }
61
62   /**
63    * Adds element to the RingBuffer.
64    * <p>
65    *
66    * If the buffer is full, an Exception will be thrown.
67    * <p>
68    *
69    * Note that <code>RingBufferException</code> does not need to be caught
70    * because it is an inheritant of <code>java.lang.RuntimeException</code>.
71    * Especially for the <code>Object add(Object element)</code>- method there
72    * may be an implementation that never throws <code>BUFFER_FULL</code> but
73    * returns the oldest element in case the buffer is full.
74    * <p>
75    *
76    * @param element
77    * the element to add.
78    *
79    * @return the instance that had to be removed in order to add the new one or
80    * null, if the capacity was not reached yet.
81    *
82    * @throws IRingBuffer.RingBufferException
83    * if the buffer cannot accept any more elements.
84    *
85    *
86    */
87   public Object JavaDoc add(final Object JavaDoc element) throws IRingBuffer.RingBufferException;
88
89   /**
90    * Clears the buffer without returning anything.
91    * <p>
92    * If the content is of no interest prefer using this method instead of
93    * {@link #removeAll()} as it may be implemented in a much faster way (
94    * <code>O(constant)</code> instead of <code>O(n)</code>).
95    * <p>
96    *
97    */
98   public void clear();
99
100   /**
101    * Returns the absolute amount of space in the buffer.
102    * <p>
103    *
104    * @return the absolute amount of space in the buffer.
105    */
106   public int getBufferSize();
107
108   /**
109    * Returns the oldest element from the buffer. This method does not remove the
110    * element.
111    * <p>
112    *
113    * @return the oldest element from the buffer.
114    *
115    * @throws IRingBuffer.RingBufferException
116    * if the buffer is empty.
117    */
118   public Object JavaDoc getOldest() throws IRingBuffer.RingBufferException;
119
120   /**
121    * Returns the last element added. This method does not remove the element.
122    * <p>
123    *
124    * @return the last element added.
125    *
126    * @throws IRingBuffer.RingBufferException
127    * if the buffer is empty.
128    */
129   public Object JavaDoc getYoungest() throws IRingBuffer.RingBufferException;
130
131   /**
132    * Tests wether no elements are stored in the buffer.
133    * <p>
134    *
135    * @return true if no element is stored in the buffer.
136    */
137   public boolean isEmpty();
138
139   /**
140    * Returns true if no more space in the buffer is available. This method
141    * should be used to test before calling {@link #add(Object)}.
142    * <p>
143    *
144    *
145    * @return true if no more space in the buffer is available.
146    */
147   public boolean isFull();
148
149   /**
150    * Returns an iterator starting from the first (youngest) to the last (oldest)
151    * element.
152    * <p>
153    *
154    * @return an iterator starting from the first (youngest) to the last (oldest)
155    * element.
156    */
157   public java.util.Iterator JavaDoc iteratorF2L();
158
159   /**
160    * Returns an iterator starting from the last (oldest) to the first (youngest)
161    * element.
162    *
163    * @return an iterator starting from the last (oldest) to the first (youngest)
164    * element.
165    */
166   public java.util.Iterator JavaDoc iteratorL2F();
167
168   /**
169    * Removes the oldest element from the buffer.
170    * <p>
171    *
172    * @return the removed oldest element from the buffer.
173    *
174    * @throws IRingBuffer.RingBufferException
175    * if the buffer is empty.
176    */
177   public Object JavaDoc remove() throws IRingBuffer.RingBufferException;
178
179   /**
180    * Clears the buffer. It will return all of it's stored elements.
181    * <p>
182    *
183    * @return all removed elements.
184    */
185   public Object JavaDoc[] removeAll();
186
187   /**
188    * Sets a new buffer- size.
189    * <p>
190    *
191    * Implementations may vary on handling the problem that the new size is
192    * smaller than the actual amount of elements in the buffer: <br>
193    * The oldest elements may be thrown away.
194    * <p>
195    * A new size is assigned but the elements "overhanging" are returned by the
196    * <code>Object remove()</code>- method first. This may take time until the
197    * buffer has its actual size again.
198    * <p>
199    *
200    * @param newSize
201    * the new buffer size to set.
202    */
203   public void setBufferSize(final int newSize);
204
205   /**
206    * Returns the actual amount of elements stored in the buffer.
207    * <p>
208    *
209    * @return the actual amount of elements stored in the buffer.
210    */
211   public int size();
212
213 }
214
Popular Tags