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.buffer;
018
019 import java.util.Collection;
020
021 /**
022 * CircularFifoBuffer is a first in first out buffer with a fixed size that
023 * replaces its oldest element if full.
024 * <p>
025 * The removal order of a <code>CircularFifoBuffer</code> is based on the
026 * insertion order; elements are removed in the same order in which they
027 * were added. The iteration order is the same as the removal order.
028 * <p>
029 * The {@link #add(Object)}, {@link #remove()} and {@link #get()} operations
030 * all perform in constant time. All other operations perform in linear
031 * time or worse.
032 * <p>
033 * Note that this implementation is not synchronized. The following can be
034 * used to provide synchronized access to your <code>CircularFifoBuffer</code>:
035 * <pre>
036 * Buffer fifo = BufferUtils.synchronizedBuffer(new CircularFifoBuffer());
037 * </pre>
038 * <p>
039 * This buffer prevents null objects from being added.
040 * <p>
041 * This class is Serializable from Commons Collections 3.1.
042 *
043 * @since Commons Collections 3.0
044 * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
045 *
046 * @author Stefano Fornari
047 * @author Stephen Colebourne
048 */
049 public class CircularFifoBuffer extends BoundedFifoBuffer {
050
051 /** Serialization version */
052 private static final long serialVersionUID = -8423413834657610406L;
053
054 /**
055 * Constructor that creates a buffer with the default size of 32.
056 */
057 public CircularFifoBuffer() {
058 super(32);
059 }
060
061 /**
062 * Constructor that creates a buffer with the specified size.
063 *
064 * @param size the size of the buffer (cannot be changed)
065 * @throws IllegalArgumentException if the size is less than 1
066 */
067 public CircularFifoBuffer(int size) {
068 super(size);
069 }
070
071 /**
072 * Constructor that creates a buffer from the specified collection.
073 * The collection size also sets the buffer size
074 *
075 * @param coll the collection to copy into the buffer, may not be null
076 * @throws NullPointerException if the collection is null
077 */
078 public CircularFifoBuffer(Collection coll) {
079 super(coll);
080 }
081
082 /**
083 * If the buffer is full, the least recently added element is discarded so
084 * that a new element can be inserted.
085 *
086 * @param element the element to add
087 * @return true, always
088 */
089 public boolean add(Object element) {
090 if (isFull()) {
091 remove();
092 }
093 return super.add(element);
094 }
095
096 }