001: /*
002: * Copyright 2002-2005 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.collections;
017:
018: import org.apache.commons.collections.buffer.BlockingBuffer;
019: import org.apache.commons.collections.buffer.PredicatedBuffer;
020: import org.apache.commons.collections.buffer.SynchronizedBuffer;
021: import org.apache.commons.collections.buffer.TransformedBuffer;
022: import org.apache.commons.collections.buffer.TypedBuffer;
023: import org.apache.commons.collections.buffer.UnmodifiableBuffer;
024: import org.apache.commons.collections.buffer.BoundedBuffer;
025:
026: /**
027: * Provides utility methods and decorators for {@link Buffer} instances.
028: *
029: * @since Commons Collections 2.1
030: * @version $Revision: 348808 $ $Date: 2005-11-24 21:35:09 +0000 (Thu, 24 Nov 2005) $
031: *
032: * @author Paul Jack
033: * @author Stephen Colebourne
034: */
035: public class BufferUtils {
036:
037: /**
038: * An empty unmodifiable buffer.
039: */
040: public static final Buffer EMPTY_BUFFER = UnmodifiableBuffer
041: .decorate(new ArrayStack(1));
042:
043: /**
044: * <code>BufferUtils</code> should not normally be instantiated.
045: */
046: public BufferUtils() {
047: }
048:
049: //-----------------------------------------------------------------------
050: /**
051: * Returns a synchronized buffer backed by the given buffer.
052: * Much like the synchronized collections returned by
053: * {@link java.util.Collections}, you must manually synchronize on
054: * the returned buffer's iterator to avoid non-deterministic behavior:
055: *
056: * <pre>
057: * Buffer b = BufferUtils.synchronizedBuffer(myBuffer);
058: * synchronized (b) {
059: * Iterator i = b.iterator();
060: * while (i.hasNext()) {
061: * process (i.next());
062: * }
063: * }
064: * </pre>
065: *
066: * @param buffer the buffer to synchronize, must not be null
067: * @return a synchronized buffer backed by that buffer
068: * @throws IllegalArgumentException if the Buffer is null
069: */
070: public static Buffer synchronizedBuffer(Buffer buffer) {
071: return SynchronizedBuffer.decorate(buffer);
072: }
073:
074: /**
075: * Returns a synchronized buffer backed by the given buffer that will
076: * block on {@link Buffer#get()} and {@link Buffer#remove()} operations.
077: * If the buffer is empty, then the {@link Buffer#get()} and
078: * {@link Buffer#remove()} operations will block until new elements
079: * are added to the buffer, rather than immediately throwing a
080: * <code>BufferUnderflowException</code>.
081: *
082: * @param buffer the buffer to synchronize, must not be null
083: * @return a blocking buffer backed by that buffer
084: * @throws IllegalArgumentException if the Buffer is null
085: */
086: public static Buffer blockingBuffer(Buffer buffer) {
087: return BlockingBuffer.decorate(buffer);
088: }
089:
090: /**
091: * Returns a synchronized buffer backed by the given buffer that will
092: * block on {@link Buffer#get()} and {@link Buffer#remove()} operations
093: * until <code>timeout</code> expires. If the buffer is empty, then the
094: * {@link Buffer#get()} and {@link Buffer#remove()} operations will block
095: * until new elements are added to the buffer, rather than immediately
096: * throwing a <code>BufferUnderflowException</code>.
097: *
098: * @param buffer the buffer to synchronize, must not be null
099: * @param timeoutMillis the timeout value in milliseconds, zero or less for no timeout
100: * @return a blocking buffer backed by that buffer
101: * @throws IllegalArgumentException if the Buffer is null
102: * @since Commons Collections 3.2
103: */
104: public static Buffer blockingBuffer(Buffer buffer,
105: long timeoutMillis) {
106: return BlockingBuffer.decorate(buffer, timeoutMillis);
107: }
108:
109: /**
110: * Returns a synchronized buffer backed by the given buffer that will
111: * block on {@link Buffer#add(Object)} and
112: * {@link Buffer#addAll(java.util.Collection)} until enough object(s) are
113: * removed from the buffer to allow the object(s) to be added and still
114: * maintain the maximum size.
115: *
116: * @param buffer the buffer to make bounded, must not be null
117: * @param maximumSize the maximum size
118: * @return a bounded buffer backed by the given buffer
119: * @throws IllegalArgumentException if the given buffer is null
120: * @since Commons Collections 3.2
121: */
122: public static Buffer boundedBuffer(Buffer buffer, int maximumSize) {
123: return BoundedBuffer.decorate(buffer, maximumSize);
124: }
125:
126: /**
127: * Returns a synchronized buffer backed by the given buffer that will
128: * block on {@link Buffer#add(Object)} and
129: * {@link Buffer#addAll(java.util.Collection)} until enough object(s) are
130: * removed from the buffer to allow the object(s) to be added and still
131: * maintain the maximum size or the timeout expires.
132: *
133: * @param buffer the buffer to make bounded, must not be null
134: * @param maximumSize the maximum size
135: * @param timeoutMillis the timeout value in milliseconds, zero or less for no timeout
136: * @return a bounded buffer backed by the given buffer
137: * @throws IllegalArgumentException if the given buffer is null
138: * @since Commons Collections 3.2
139: */
140: public static Buffer boundedBuffer(Buffer buffer, int maximumSize,
141: long timeoutMillis) {
142: return BoundedBuffer.decorate(buffer, maximumSize,
143: timeoutMillis);
144: }
145:
146: /**
147: * Returns an unmodifiable buffer backed by the given buffer.
148: *
149: * @param buffer the buffer to make unmodifiable, must not be null
150: * @return an unmodifiable buffer backed by that buffer
151: * @throws IllegalArgumentException if the Buffer is null
152: */
153: public static Buffer unmodifiableBuffer(Buffer buffer) {
154: return UnmodifiableBuffer.decorate(buffer);
155: }
156:
157: /**
158: * Returns a predicated (validating) buffer backed by the given buffer.
159: * <p>
160: * Only objects that pass the test in the given predicate can be added to the buffer.
161: * Trying to add an invalid object results in an IllegalArgumentException.
162: * It is important not to use the original buffer after invoking this method,
163: * as it is a backdoor for adding invalid objects.
164: *
165: * @param buffer the buffer to predicate, must not be null
166: * @param predicate the predicate used to evaluate new elements, must not be null
167: * @return a predicated buffer
168: * @throws IllegalArgumentException if the Buffer or Predicate is null
169: */
170: public static Buffer predicatedBuffer(Buffer buffer,
171: Predicate predicate) {
172: return PredicatedBuffer.decorate(buffer, predicate);
173: }
174:
175: /**
176: * Returns a typed buffer backed by the given buffer.
177: * <p>
178: * Only elements of the specified type can be added to the buffer.
179: *
180: * @param buffer the buffer to predicate, must not be null
181: * @param type the type to allow into the buffer, must not be null
182: * @return a typed buffer
183: * @throws IllegalArgumentException if the buffer or type is null
184: */
185: public static Buffer typedBuffer(Buffer buffer, Class type) {
186: return TypedBuffer.decorate(buffer, type);
187: }
188:
189: /**
190: * Returns a transformed buffer backed by the given buffer.
191: * <p>
192: * Each object is passed through the transformer as it is added to the
193: * Buffer. It is important not to use the original buffer after invoking this
194: * method, as it is a backdoor for adding untransformed objects.
195: *
196: * @param buffer the buffer to predicate, must not be null
197: * @param transformer the transformer for the buffer, must not be null
198: * @return a transformed buffer backed by the given buffer
199: * @throws IllegalArgumentException if the Buffer or Transformer is null
200: */
201: public static Buffer transformedBuffer(Buffer buffer,
202: Transformer transformer) {
203: return TransformedBuffer.decorate(buffer, transformer);
204: }
205:
206: }
|