KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > net > sf > jga > util > CachingIterator


1 // ============================================================================
2 // $Id: CachingIterator.java,v 1.9 2005/08/02 23:45:22 davidahall Exp $
3 // Copyright (c) 2003-2005 David A. Hall
4 // ============================================================================
5 // The contents of this file are subject to the Common Development and
6 // Distribution License (CDDL), Version 1.0 (the License); you may not use this
7 // file except in compliance with the License. You should have received a copy
8 // of the the License along with this file: if not, a copy of the License is
9 // available from Sun Microsystems, Inc.
10 //
11 // http://www.sun.com/cddl/cddl.html
12 //
13 // From time to time, the license steward (initially Sun Microsystems, Inc.) may
14 // publish revised and/or new versions of the License. You may not use,
15 // distribute, or otherwise make this file available under subsequent versions
16 // of the License.
17 //
18 // Alternatively, the contents of this file may be used under the terms of the
19 // GNU Lesser General Public License Version 2.1 or later (the "LGPL"), in which
20 // case the provisions of the LGPL are applicable instead of those above. If you
21 // wish to allow use of your version of this file only under the terms of the
22 // LGPL, and not to allow others to use your version of this file under the
23 // terms of the CDDL, indicate your decision by deleting the provisions above
24 // and replace them with the notice and other provisions required by the LGPL.
25 // If you do not delete the provisions above, a recipient may use your version
26 // of this file under the terms of either the CDDL or the LGPL.
27 //
28 // This library is distributed in the hope that it will be useful,
29 // but WITHOUT ANY WARRANTY; without even the implied warranty of
30 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
31 // ============================================================================
32
33 package net.sf.jga.util;
34
35 import java.lang.reflect.Array JavaDoc;
36 import java.util.ArrayList JavaDoc;
37 import java.util.NoSuchElementException JavaDoc;
38 import java.util.Iterator JavaDoc;
39
40 /**
41  * Iterator that allows the program to retain the last few elements returned.
42  * <p>
43  * Copyright &copy; 2003-2005 David A. Hall
44  *
45  * @author <a HREF="mailto:davidahall@users.sf.net">David A. Hall</a>
46  */
47
48 public class CachingIterator<T> implements Iterator JavaDoc<T>, Iterable JavaDoc<T> {
49     // The base iterator
50 private Iterator JavaDoc<? extends T> _base;
51
52     // ring buffer, to hold the elements that have been consumed
53 private Object JavaDoc[] _cache;
54
55     // index of the buffer's base element. Once the ring buffer loops around,
56 // the base pointer indicates the logical
57 private int _baseptr = 0;
58
59     // number of elements in the buffer
60 private int _cnt = 0;
61
62     // size of the buffer
63 private int _size;
64
65     /**
66      * Builds a CachingIterator that can retain 1 element.
67      */
68       
69     public CachingIterator (Iterator JavaDoc<? extends T> base) {
70         this(base, 1);
71     }
72
73     /**
74      * Builds a CachingIterator that can retain the given number of elements.
75      *
76      * @throws IllegalArgumentException if max <= 0.
77      */
78       
79     public CachingIterator (Iterator JavaDoc<? extends T> base, int max) {
80         if (max <= 0)
81             throw new IllegalArgumentException JavaDoc();
82         
83         _base = (base != null) ? base : new EmptyIterator<T>();
84         _size = max;
85
86         _cache = new Object JavaDoc[_size];
87     }
88
89     /**
90      * Returns true if there have been at least N elements consumed from the
91      * underlying iterator.
92      */
93
94     public boolean hasCached(int n) {
95         return n > 0 && n <= _cnt;
96     }
97     
98     /**
99      * Returns the Nth previous element consumed from the underlying iterator.
100      */
101
102     public T cached(int n) {
103         if (n <= 0 || n > _cnt || n > _size)
104             throw new NoSuchElementException JavaDoc();
105
106         // @SuppressWarnings
107 // The buffer array is private, and the only things that we ever put
108 // into it are known to be T objects because they are read from an
109 // Iterator<? extends T>, so we know that the cast is always valid
110
111         return (T) _cache[(_baseptr +_size - n) % _size];
112     }
113     
114     /**
115      * Returns the cache size
116      */
117     public int getCacheSize() {
118         return _size;
119     }
120     
121     /**
122      * Returns the number of elements in the cache
123      */
124     public int getCacheCount() {
125         return _cnt;
126     }
127     
128     // - - - - - - - - - - -
129 // Iterable<T> interface
130 // - - - - - - - - - - -
131
132     public Iterator JavaDoc<T> iterator() { return this; }
133     
134     // - - - - - - - - - - -
135 // Iterator<T> interface
136 // - - - - - - - - - - -
137
138     public boolean hasNext() {
139         return _base.hasNext();
140     }
141
142     public T next() {
143         if (_cnt < _size)
144             ++_cnt;
145         
146         int n = _baseptr;
147         _baseptr = ++_baseptr % _size;
148         _cache[n] =_base.next();
149
150         // @SuppressWarnings
151 // The buffer array is private, and the only things that we ever put
152 // into it are known to be T objects because they are read from an
153 // Iterator<? extends T>, so we know that the cast is always valid
154
155         return (T) _cache[n];
156     }
157
158
159     /**
160      * Removes the last item returned from the base iterator, if the base
161      * iterator supports the remove operation. The item is not removed from
162      * the cache.
163      * @throws UnsupportedOperationException if the base iterator does not
164      * support the remove() operation
165      */
166     public void remove() {
167         _base.remove();
168     }
169 }
170
Popular Tags