KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > BufferUtils


1 /*
2  * Copyright 2002-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.collections;
17
18 import org.apache.commons.collections.buffer.BlockingBuffer;
19 import org.apache.commons.collections.buffer.PredicatedBuffer;
20 import org.apache.commons.collections.buffer.SynchronizedBuffer;
21 import org.apache.commons.collections.buffer.TransformedBuffer;
22 import org.apache.commons.collections.buffer.TypedBuffer;
23 import org.apache.commons.collections.buffer.UnmodifiableBuffer;
24
25 /**
26  * Provides utility methods and decorators for {@link Buffer} instances.
27  *
28  * @since Commons Collections 2.1
29  * @version $Revision: 1.20 $ $Date: 2004/04/01 20:12:00 $
30  *
31  * @author Paul Jack
32  * @author Stephen Colebourne
33  */
34 public class BufferUtils {
35
36     /**
37      * An empty unmodifiable buffer.
38      */
39     public static final Buffer EMPTY_BUFFER = UnmodifiableBuffer.decorate(new ArrayStack(1));
40     
41     /**
42      * <code>BufferUtils</code> should not normally be instantiated.
43      */
44     public BufferUtils() {
45     }
46
47     //-----------------------------------------------------------------------
48 /**
49      * Returns a synchronized buffer backed by the given buffer.
50      * Much like the synchronized collections returned by
51      * {@link java.util.Collections}, you must manually synchronize on
52      * the returned buffer's iterator to avoid non-deterministic behavior:
53      *
54      * <pre>
55      * Buffer b = BufferUtils.synchronizedBuffer(myBuffer);
56      * synchronized (b) {
57      * Iterator i = b.iterator();
58      * while (i.hasNext()) {
59      * process (i.next());
60      * }
61      * }
62      * </pre>
63      *
64      * @param buffer the buffer to synchronize, must not be null
65      * @return a synchronized buffer backed by that buffer
66      * @throws IllegalArgumentException if the Buffer is null
67      */
68     public static Buffer synchronizedBuffer(Buffer buffer) {
69         return SynchronizedBuffer.decorate(buffer);
70     }
71
72     /**
73      * Returns a synchronized buffer backed by the given buffer that will
74      * block on {@link Buffer#get()} and {@link Buffer#remove()} operations.
75      * If the buffer is empty, then the {@link Buffer#get()} and
76      * {@link Buffer#remove()} operations will block until new elements
77      * are added to the buffer, rather than immediately throwing a
78      * <code>BufferUnderflowException</code>.
79      *
80      * @param buffer the buffer to synchronize, must not be null
81      * @return a blocking buffer backed by that buffer
82      * @throws IllegalArgumentException if the Buffer is null
83      */
84     public static Buffer blockingBuffer(Buffer buffer) {
85         return BlockingBuffer.decorate(buffer);
86     }
87
88     /**
89      * Returns an unmodifiable buffer backed by the given buffer.
90      *
91      * @param buffer the buffer to make unmodifiable, must not be null
92      * @return an unmodifiable buffer backed by that buffer
93      * @throws IllegalArgumentException if the Buffer is null
94      */
95     public static Buffer unmodifiableBuffer(Buffer buffer) {
96         return UnmodifiableBuffer.decorate(buffer);
97     }
98
99     /**
100      * Returns a predicated (validating) buffer backed by the given buffer.
101      * <p>
102      * Only objects that pass the test in the given predicate can be added to the buffer.
103      * Trying to add an invalid object results in an IllegalArgumentException.
104      * It is important not to use the original buffer after invoking this method,
105      * as it is a backdoor for adding invalid objects.
106      *
107      * @param buffer the buffer to predicate, must not be null
108      * @param predicate the predicate used to evaluate new elements, must not be null
109      * @return a predicated buffer
110      * @throws IllegalArgumentException if the Buffer or Predicate is null
111      */
112     public static Buffer predicatedBuffer(Buffer buffer, Predicate predicate) {
113         return PredicatedBuffer.decorate(buffer, predicate);
114     }
115
116     /**
117      * Returns a typed buffer backed by the given buffer.
118      * <p>
119      * Only elements of the specified type can be added to the buffer.
120      *
121      * @param buffer the buffer to predicate, must not be null
122      * @param type the type to allow into the buffer, must not be null
123      * @return a typed buffer
124      * @throws IllegalArgumentException if the buffer or type is null
125      */
126     public static Buffer typedBuffer(Buffer buffer, Class JavaDoc type) {
127         return TypedBuffer.decorate(buffer, type);
128     }
129
130     /**
131      * Returns a transformed buffer backed by the given buffer.
132      * <p>
133      * Each object is passed through the transformer as it is added to the
134      * Buffer. It is important not to use the original buffer after invoking this
135      * method, as it is a backdoor for adding untransformed objects.
136      *
137      * @param buffer the buffer to predicate, must not be null
138      * @param transformer the transformer for the buffer, must not be null
139      * @return a transformed buffer backed by the given buffer
140      * @throws IllegalArgumentException if the Buffer or Transformer is null
141      */
142     public static Buffer transformedBuffer(Buffer buffer, Transformer transformer) {
143         return TransformedBuffer.decorate(buffer, transformer);
144     }
145     
146 }
147
Popular Tags