1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections.buffer;
18
19 import java.util.Collection;
20
21 /**
22 * CircularFifoBuffer is a first in first out buffer with a fixed size that
23 * replaces its oldest element if full.
24 * <p>
25 * The removal order of a {@link CircularFifoBuffer} is based on the
26 * insertion order; elements are removed in the same order in which they
27 * were added. The iteration order is the same as the removal order.
28 * <p>
29 * The {@link #add(Object)}, {@link #remove()} and {@link #get()} operations
30 * all perform in constant time. All other operations perform in linear
31 * time or worse.
32 * <p>
33 * Note that this implementation is not synchronized. The following can be
34 * used to provide synchronized access to your <code>CircularFifoBuffer</code>:
35 * <pre>
36 * Buffer fifo = BufferUtils.synchronizedBuffer(new CircularFifoBuffer());
37 * </pre>
38 * <p>
39 * This buffer prevents null objects from being added.
40 * <p>
41 * This class is Serializable from Commons Collections 3.1.
42 *
43 * @since 3.0
44 * @version $Id: CircularFifoBuffer.java 1429905 2013-01-07 17:15:14Z ggregory $
45 */
46 public class CircularFifoBuffer<E> extends BoundedFifoBuffer<E> {
47
48 /** Serialization version */
49 private static final long serialVersionUID = -8423413834657610406L;
50
51 /**
52 * Constructor that creates a buffer with the default size of 32.
53 */
54 public CircularFifoBuffer() {
55 super(32);
56 }
57
58 /**
59 * Constructor that creates a buffer with the specified size.
60 *
61 * @param size the size of the buffer (cannot be changed)
62 * @throws IllegalArgumentException if the size is less than 1
63 */
64 public CircularFifoBuffer(final int size) {
65 super(size);
66 }
67
68 /**
69 * Constructor that creates a buffer from the specified collection.
70 * The collection size also sets the buffer size
71 *
72 * @param coll the collection to copy into the buffer, may not be null
73 * @throws NullPointerException if the collection is null
74 */
75 public CircularFifoBuffer(final Collection<E> coll) {
76 super(coll);
77 }
78
79 /**
80 * If the buffer is full, the least recently added element is discarded so
81 * that a new element can be inserted.
82 *
83 * @param element the element to add
84 * @return true, always
85 */
86 @Override
87 public boolean add(final E element) {
88 if (isFull()) {
89 remove();
90 }
91 return super.add(element);
92 }
93
94 }