ObjectQueue


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  ;
26  
27  import com.sosnoski.util.WrappedArrayIterator;
28  
29  /**
30   * Growable circular queue of <code>Object</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 ObjectQueue extends QueueBase
42  {
43      /** The underlying array used for storing the data. */
44      protected Object  [] 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 ObjectQueue(int size, int growth) {
54          super(size, growth, Object  .class);
55      }
56  
57      /**
58       * Constructor with partial specification.
59       *
60       * @param size number of elements initially allowed in queue
61       */
62  
63      public ObjectQueue(int size) {
64          super(size, Object  .class);
65      }
66  
67      /**
68       * Default constructor.
69       */
70  
71      public ObjectQueue() {
72          this(DEFAULT_SIZE);
73      }
74  
75      /**
76       * Copy (clone) constructor.
77       *
78       * @param base instance being copied
79       */
80  
81      public ObjectQueue(ObjectQueue 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   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   array) {
104         m_baseArray = (Object  []) 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(Object   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 Object   remove() {
128         int index = getRemoveIndex();
129         Object   item = m_baseArray[index];
130         m_baseArray[index] = null;
131         return item;
132     }
133 
134     /**
135      * Return an iterator for the <code>Object</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   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 Object  [] toArray() {
161         return (Object  []) buildArray(Object  .class);
162     }
163 
164     /**
165      * Constructs and returns a type-specific array containing the same data
166      * as held in this growable generic array. All values in this array must
167      * be assignment compatible with the specified type.
168      *
169      * @param type element type for constructed array
170      * @return array containing a copy of the data
171      */
172 
173     public Object  [] toArray(Class   type) {
174         return (Object  []) buildArray(type);
175     }
176 
177     /**
178      * Duplicates the object with the generic call.
179      *
180      * @return a copy of the object
181      */
182 
183     public Object   clone() {
184         return new ObjectQueue(this);
185     }
186 }
187
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags