KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sosnoski > util > queue > StringQueue


1 /*
2  * Copyright (c) 2000-2001 Sosnoski Software Solutions, Inc.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to deal
6  * in the Software without restriction, including without limitation the rights
7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8  * copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  */
22
23 package com.sosnoski.util.queue;
24
25 import java.util.Iterator JavaDoc;
26
27 import com.sosnoski.util.WrappedArrayIterator;
28
29 /**
30  * Growable circular queue of <code>String</code>s. This implementation is
31  * unsynchronized in order to provide the best possible performance for typical
32  * usage scenarios, so explicit synchronization must be implemented by a
33  * wrapper class or directly by the application in cases where instances are
34  * modified in a multithreaded environment. See the base classes for other
35  * details of the implementation.
36  *
37  * @author Dennis M. Sosnoski
38  * @version 1.1
39  */
40
41 public class StringQueue extends QueueBase
42 {
43     /** The underlying array used for storing the data. */
44     protected String JavaDoc[] m_baseArray;
45
46     /**
47      * Constructor with full specification.
48      *
49      * @param size number of elements initially allowed in queue
50      * @param growth maximum size increment for growing queue
51      */
52
53     public StringQueue(int size, int growth) {
54         super(size, growth, String JavaDoc.class);
55     }
56
57     /**
58      * Constructor with partial specification.
59      *
60      * @param size number of elements initially allowed in queue
61      */
62
63     public StringQueue(int size) {
64         super(size, String JavaDoc.class);
65     }
66
67     /**
68      * Default constructor.
69      */
70
71     public StringQueue() {
72         this(DEFAULT_SIZE);
73     }
74
75     /**
76      * Copy (clone) constructor.
77      *
78      * @param base instance being copied
79      */
80
81     public StringQueue(StringQueue base) {
82         super(base);
83     }
84
85     /**
86      * Get the backing array. This method is used by the type-agnostic base
87      * class code to access the array used for type-specific storage.
88      *
89      * @return backing array object
90      */
91
92     protected Object JavaDoc getArray() {
93         return m_baseArray;
94     }
95
96     /**
97      * Set the backing array. This method is used by the type-agnostic base
98      * class code to set the array used for type-specific storage.
99      *
100      * @param backing array object
101      */
102
103     protected void setArray(Object JavaDoc array) {
104         m_baseArray = (String JavaDoc[]) array;
105     }
106
107     /**
108      * Add an item at the end of the queue. If necessary, the array used for
109      * storing the queue data is grown before storing the added item.
110      *
111      * @param item item to be added
112      */
113
114     public void add(String JavaDoc item) {
115         int index = getAddIndex();
116         m_baseArray[index] = item;
117     }
118
119     /**
120      * Remove an item from the start of the queue.
121      *
122      * @return item removed from queue
123      * @exception IllegalStateException on attempt to remove an item from an
124      * empty queue
125      */
126
127     public String JavaDoc remove() {
128         int index = getRemoveIndex();
129         String JavaDoc item = m_baseArray[index];
130         m_baseArray[index] = null;
131         return item;
132     }
133
134     /**
135      * Return an iterator for the <code>String</code>s in this queue. The
136      * iterator returns all values in order, but is not "live". Values
137      * added to the queue during iteration will not be returned by the
138      * iteration, and any other changes to the queue while the iteration is
139      * in progress will give indeterminant results.
140      *
141      * @return iterator for values in queue
142      */
143
144     public final Iterator JavaDoc iterator() {
145         int end = m_fillOffset - 1;
146         if (end < 0) {
147             end = m_countLimit - 1;
148         }
149         return WrappedArrayIterator.buildIterator(m_baseArray,
150             m_emptyOffset, end);
151     }
152
153     /**
154      * Constructs and returns a simple array containing the same data as held
155      * in this growable array.
156      *
157      * @return array containing a copy of the data
158      */
159
160     public String JavaDoc[] toArray() {
161         return (String JavaDoc[]) buildArray(String JavaDoc.class);
162     }
163
164     /**
165      * Duplicates the object with the generic call.
166      *
167      * @return a copy of the object
168      */
169
170     public Object JavaDoc clone() {
171         return new StringQueue(this);
172     }
173 }
174
Popular Tags