View Javadoc

1   package org.apache.turbine.util.pool;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  /***
20   * Efficient array-based bounded buffer class.
21   * Adapted from CPJ, chapter 8, which describes design.
22   * Originally written by Doug Lea and released into the public domain.
23   * <p>[<a href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html"> Introduction to this package. </a>] <p>
24   *
25   * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
26   * @version $Id: BoundedBuffer.java 264148 2005-08-29 14:21:04Z henning $
27   */
28  public class BoundedBuffer
29  {
30      /*** The default capacity. */
31      public static final int DEFAULT_CAPACITY = 1024;
32  
33      protected final Object[] buffer;      // the elements
34  
35      protected int takePtr = 0;            // circular indices
36      protected int putPtr = 0;
37  
38      protected int usedSlots = 0;          // length
39      protected int emptySlots;             // capacity - length
40  
41      /***
42       * Creates a buffer with the given capacity.
43       *
44       * @param capacity the capacity.
45       * @throws IllegalArgumentException if capacity less or equal to zero.
46       */
47      public BoundedBuffer(int capacity)
48              throws IllegalArgumentException
49      {
50          if (capacity <= 0)
51          {
52              throw new IllegalArgumentException(
53                      "Bounded Buffer must have capacity > 0!");
54          }
55  
56          buffer = new Object[capacity];
57          emptySlots = capacity;
58      }
59  
60      /***
61       * Creates a buffer with the default capacity
62       */
63      public BoundedBuffer()
64      {
65          this(DEFAULT_CAPACITY);
66      }
67  
68      /***
69       * Returns the number of elements in the buffer.
70       * This is only a snapshot value, that may change
71       * immediately after returning.
72       *
73       * @return the size.
74       */
75      public synchronized int size()
76      {
77          return usedSlots;
78      }
79  
80      /***
81       * Returns the capacity of the buffer.
82       *
83       * @return the capacity.
84       */
85      public int capacity()
86      {
87          return buffer.length;
88      }
89  
90      /***
91       * Peeks, but does not remove the top item from the buffer.
92       *
93       * @return the object or null.
94       */
95      public synchronized Object peek()
96      {
97          return (usedSlots > 0)
98                  ? buffer[takePtr] : null;
99      }
100 
101     /***
102      * Puts an item in the buffer only if there is capacity available.
103      *
104      * @param item the item to be inserted.
105      * @return true if accepted, else false.
106      */
107     public synchronized boolean offer(Object x)
108     {
109         if (x == null)
110         {
111             throw new IllegalArgumentException("Bounded Buffer cannot store a null object");
112         }
113 
114         if (emptySlots > 0)
115         {
116             --emptySlots;
117             buffer[putPtr] = x;
118             if (++putPtr >= buffer.length)
119             {
120                 putPtr = 0;
121             }
122             usedSlots++;
123             return true;
124         }
125         else
126         {
127             return false;
128         }
129     }
130 
131     /***
132      * Polls and removes the top item from the buffer if one is available.
133      *
134      * @return the oldest item from the buffer, or null if the buffer is empty.
135      */
136     public synchronized Object poll()
137     {
138         if (usedSlots > 0)
139         {
140             --usedSlots;
141             Object old = buffer[takePtr];
142             buffer[takePtr] = null;
143             if (++takePtr >= buffer.length)
144             {
145                 takePtr = 0;
146             }
147             emptySlots++;
148             return old;
149         }
150         else
151         {
152             return null;
153         }
154     }
155 }