001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 package org.apache.commons.collections; 018 019 import org.apache.commons.collections.buffer.BlockingBuffer; 020 import org.apache.commons.collections.buffer.PredicatedBuffer; 021 import org.apache.commons.collections.buffer.SynchronizedBuffer; 022 import org.apache.commons.collections.buffer.TransformedBuffer; 023 import org.apache.commons.collections.buffer.TypedBuffer; 024 import org.apache.commons.collections.buffer.UnmodifiableBuffer; 025 import org.apache.commons.collections.buffer.BoundedBuffer; 026 027 /** 028 * Provides utility methods and decorators for {@link Buffer} instances. 029 * 030 * @since Commons Collections 2.1 031 * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $ 032 * 033 * @author Paul Jack 034 * @author Stephen Colebourne 035 */ 036 public class BufferUtils { 037 038 /** 039 * An empty unmodifiable buffer. 040 */ 041 public static final Buffer EMPTY_BUFFER = UnmodifiableBuffer.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, long timeoutMillis) { 105 return BlockingBuffer.decorate(buffer, timeoutMillis); 106 } 107 108 /** 109 * Returns a synchronized buffer backed by the given buffer that will 110 * block on {@link Buffer#add(Object)} and 111 * {@link Buffer#addAll(java.util.Collection)} until enough object(s) are 112 * removed from the buffer to allow the object(s) to be added and still 113 * maintain the maximum size. 114 * 115 * @param buffer the buffer to make bounded, must not be null 116 * @param maximumSize the maximum size 117 * @return a bounded buffer backed by the given buffer 118 * @throws IllegalArgumentException if the given buffer is null 119 * @since Commons Collections 3.2 120 */ 121 public static Buffer boundedBuffer(Buffer buffer, int maximumSize) { 122 return BoundedBuffer.decorate(buffer, maximumSize); 123 } 124 125 /** 126 * Returns a synchronized buffer backed by the given buffer that will 127 * block on {@link Buffer#add(Object)} and 128 * {@link Buffer#addAll(java.util.Collection)} until enough object(s) are 129 * removed from the buffer to allow the object(s) to be added and still 130 * maintain the maximum size or the timeout expires. 131 * 132 * @param buffer the buffer to make bounded, must not be null 133 * @param maximumSize the maximum size 134 * @param timeoutMillis the timeout value in milliseconds, zero or less for no timeout 135 * @return a bounded buffer backed by the given buffer 136 * @throws IllegalArgumentException if the given buffer is null 137 * @since Commons Collections 3.2 138 */ 139 public static Buffer boundedBuffer(Buffer buffer, int maximumSize, long timeoutMillis) { 140 return BoundedBuffer.decorate(buffer, maximumSize, timeoutMillis); 141 } 142 143 /** 144 * Returns an unmodifiable buffer backed by the given buffer. 145 * 146 * @param buffer the buffer to make unmodifiable, must not be null 147 * @return an unmodifiable buffer backed by that buffer 148 * @throws IllegalArgumentException if the Buffer is null 149 */ 150 public static Buffer unmodifiableBuffer(Buffer buffer) { 151 return UnmodifiableBuffer.decorate(buffer); 152 } 153 154 /** 155 * Returns a predicated (validating) buffer backed by the given buffer. 156 * <p> 157 * Only objects that pass the test in the given predicate can be added to the buffer. 158 * Trying to add an invalid object results in an IllegalArgumentException. 159 * It is important not to use the original buffer after invoking this method, 160 * as it is a backdoor for adding invalid objects. 161 * 162 * @param buffer the buffer to predicate, must not be null 163 * @param predicate the predicate used to evaluate new elements, must not be null 164 * @return a predicated buffer 165 * @throws IllegalArgumentException if the Buffer or Predicate is null 166 */ 167 public static Buffer predicatedBuffer(Buffer buffer, Predicate predicate) { 168 return PredicatedBuffer.decorate(buffer, predicate); 169 } 170 171 /** 172 * Returns a typed buffer backed by the given buffer. 173 * <p> 174 * Only elements of the specified type can be added to the buffer. 175 * 176 * @param buffer the buffer to predicate, must not be null 177 * @param type the type to allow into the buffer, must not be null 178 * @return a typed buffer 179 * @throws IllegalArgumentException if the buffer or type is null 180 */ 181 public static Buffer typedBuffer(Buffer buffer, Class type) { 182 return TypedBuffer.decorate(buffer, type); 183 } 184 185 /** 186 * Returns a transformed buffer backed by the given buffer. 187 * <p> 188 * Each object is passed through the transformer as it is added to the 189 * Buffer. It is important not to use the original buffer after invoking this 190 * method, as it is a backdoor for adding untransformed objects. 191 * 192 * @param buffer the buffer to predicate, must not be null 193 * @param transformer the transformer for the buffer, must not be null 194 * @return a transformed buffer backed by the given buffer 195 * @throws IllegalArgumentException if the Buffer or Transformer is null 196 */ 197 public static Buffer transformedBuffer(Buffer buffer, Transformer transformer) { 198 return TransformedBuffer.decorate(buffer, transformer); 199 } 200 201 }