AbstractBufferImpl


1   /**
2    * Dream
3    * Copyright (C) 2003-2004 INRIA Rhone-Alpes
4    *
5    * This library is free software; you can redistribute it and/or
6    * modify it under the terms of the GNU Lesser General Public
7    * License as published by the Free Software Foundation; either
8    * version 2 of the License, or (at your option) any later version.
9    *
10   * This library is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13   * Lesser General Public License for more details.
14   *
15   * You should have received a copy of the GNU Lesser General Public
16   * License along with this library; if not, write to the Free Software
17   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18   *
19   * Contact: dream@objectweb.org
20   *
21   * Initial developer(s): Vivien Quema
22   * Contributor(s): 
23   */
24  
25  package org.objectweb.dream.queue;
26  
27  import org.objectweb.dream.AbstractComponent;
28  import org.objectweb.dream.message.Message;
29  import org.objectweb.dream.message.manager.MessageManager;
30  import org.objectweb.dream.util.Error;
31  import org.objectweb.fractal.api.NoSuchInterfaceException;
32  import org.objectweb.fractal.api.control.IllegalBindingException;
33  import org.objectweb.fractal.api.control.IllegalLifeCycleException;
34  
35  /**
36   * Abstract implementation of a buffer. It implements
37   * {@link PushQueueAttributeController},{@link Buffer},
38   * {@link BufferAddFirstLast}, and {@link BufferRemoveFirstLast}interfaces.
39   * <p>
40   * Implementations of <code>add</code>, and <code>remove</code> methods
41   * (and their variants: <code>addFirst</code>,<code>addLast</code>,
42   * <code>removeFirst</code>,<code>removeLast</code>,
43   * <code>getFirst</code>, and <code>getLast</code>) are implemented as
44   * follows
45   * <ul>
46   * <li>The <code>add</code> method checks for available space and then calls
47   * the <code>doAdd</code> method to add the message to the buffer.</li>
48   * <li>The <code>remove</code> method checks for available messages and then
49   * calls the <code>doRemove</code> method to remove a message from the buffer.
50   * </li>
51   * </ul>
52   * <p>
53   * Buffer developers can inherit this class. They must implement several
54   * methods:
55   * <ul>
56   * <li><code>canAdd(message)</code> returns a boolean indicating whether the
57   * given message can be added into the buffer.</li>
58   * <li><code>doAdd(message)</code> adds the given message into the buffer.
59   * </li>
60   * <li><code>hasAvailableMessage()</code> returns a boolean indicating
61   * whether there is an available message.</li>
62   * <li><code>doRemove()</code> removes a message from the buffer.</li>
63   * <li>etc.</li>
64   * </ul>
65   * <p>
66   * Moreover developers must use the
67   * <code>incrementAvailableMessagesIndicator</code> and
68   * <code>incrementStoredMessagesIndicator</code> methods to increment
69   * indicators on stored messages, available messages and available space.
70   * <p>
71   * <i>Note: </i> the <code>add</code>,<code>remove</code>,
72   * <code>addFirst</code>,<code>addLast</code>,<code>removeFirst</code>,
73   * <code>removeLast</code>,<code>getFirst</code>, and
74   * <code>getLast</code> methods should not be overriden.
75   */
76  public abstract class AbstractBufferImpl extends AbstractComponent
77      implements
78        Buffer,
79        BufferAddFirstLast,
80        BufferRemoveFirstLast,
81        QueueAttributeController
82  {
83  
84    /** The <code>MessageManager</code> client interface. */
85    protected MessageManager messageManagerItf;
86  
87    /** The maximal capacity of the buffer. */
88    protected int            maxCapacity                = 0;
89  
90    /**
91     * An indicator on available messages into the buffer. This indicator should
92     * only be updated using the <code>incrementAvailableMessagesIndicator</code>
93     * method.
94     */
95    protected int            availableMessagesIndicator = 0;
96  
97    /**
98     * An indicator on stored messages into the buffer. This indicator should only
99     * be updated using the <code>incrementStoredMessagesIndicator</code>
100    * method.
101    */
102   protected int            storedMessagesIndicator    = 0;
103 
104   /** A lock object. */
105   protected final Object     lock                       = new Object  ();
106 
107   // ---------------------------------------------------------------------------
108   // Implementation of the Buffer interface.
109   // ---------------------------------------------------------------------------
110 
111   /**
112    * @see org.objectweb.dream.queue.Buffer#availableMessagesIndicator()
113    */
114   public int availableMessagesIndicator()
115   {
116     return availableMessagesIndicator;
117   }
118 
119   /**
120    * @see org.objectweb.dream.queue.Buffer#storedMessagesIndicator()
121    */
122   public int storedMessagesIndicator()
123   {
124     return storedMessagesIndicator;
125   }
126 
127   /**
128    * @see org.objectweb.dream.queue.Buffer#availableSpaceIndicator()
129    */
130   public int availableSpaceIndicator()
131   {
132     if (maxCapacity <= 0)
133     {
134       return Integer.MAX_VALUE;
135     }
136     else
137     {
138       return maxCapacity - storedMessagesIndicator;
139     }
140   }
141 
142   /**
143    * This method should not be overriden.
144    * 
145    * @see org.objectweb.dream.queue.Buffer#add(org.objectweb.dream.message.Message)
146    */
147   public void add(Message message) throws InterruptedException  
148   {
149     synchronized (lock)
150     {
151       while (!canAdd(message))
152       {
153         lock.wait();
154       }
155       doAdd(message);
156     }
157   }
158 
159   /**
160    * This method should not be overriden.
161    * 
162    * @see org.objectweb.dream.queue.Buffer#remove()
163    */
164   public Message remove() throws InterruptedException  
165   {
166     synchronized (lock)
167     {
168       while (!hasAvailableMessage())
169       {
170         lock.wait();
171       }
172       return doRemove();
173     }
174   }
175 
176   /**
177    * This method should not be overriden.
178    * 
179    * @see org.objectweb.dream.queue.Buffer#get()
180    */
181   public Message get() throws InterruptedException  
182   {
183     synchronized (lock)
184     {
185       while (!hasAvailableMessage())
186       {
187         lock.wait();
188       }
189       return doGet();
190     }
191   }
192 
193   /**
194    * @see org.objectweb.dream.queue.BufferAddFirstLast#addFirst(org.objectweb.dream.message.Message)
195    */
196   public void addFirst(Message message) throws InterruptedException  
197   {
198     synchronized (lock)
199     {
200       while (!canAdd(message))
201       {
202         lock.wait();
203       }
204       doAddFirst(message);
205     }
206   }
207 
208   /**
209    * @see org.objectweb.dream.queue.BufferAddFirstLast#addLast(org.objectweb.dream.message.Message)
210    */
211   public void addLast(Message message) throws InterruptedException  
212   {
213     synchronized (lock)
214     {
215       while (!canAdd(message))
216       {
217         lock.wait();
218       }
219       doAddLast(message);
220     }
221   }
222 
223   /**
224    * @see org.objectweb.dream.queue.BufferRemoveFirstLast#getFirst()
225    */
226   public Message getFirst() throws InterruptedException  
227   {
228     synchronized (lock)
229     {
230       while (!hasAvailableMessage())
231       {
232         lock.wait();
233       }
234       return doGetFirst();
235     }
236   }
237 
238   /**
239    * @see org.objectweb.dream.queue.BufferRemoveFirstLast#getLast()
240    */
241   public Message getLast() throws InterruptedException  
242   {
243     synchronized (lock)
244     {
245       while (!hasAvailableMessage())
246       {
247         lock.wait();
248       }
249       return doGetLast();
250     }
251   }
252 
253   /**
254    * @see org.objectweb.dream.queue.BufferRemoveFirstLast#removeFirst()
255    */
256   public Message removeFirst() throws InterruptedException  
257   {
258     synchronized (lock)
259     {
260       while (!hasAvailableMessage())
261       {
262         lock.wait();
263       }
264       return doRemoveFirst();
265     }
266   }
267 
268   /**
269    * @see org.objectweb.dream.queue.BufferRemoveFirstLast#removeLast()
270    */
271   public Message removeLast() throws InterruptedException  
272   {
273     synchronized (lock)
274     {
275       while (!hasAvailableMessage())
276       {
277         lock.wait();
278       }
279       return doRemoveLast();
280     }
281   }
282 
283   // ---------------------------------------------------------------------------
284   // Utility methods.
285   // ---------------------------------------------------------------------------
286 
287   /**
288    * Increments the indicator on available messages.
289    * 
290    * @param delta the delta that must be added to previous indicator.
291    */
292   protected void incrementAvailableMessagesIndicator(int delta)
293   {
294     synchronized (lock)
295     {
296       availableMessagesIndicator += delta;
297       lock.notifyAll();
298     }
299   }
300 
301   /**
302    * Increments the indicator on stored messages.
303    * 
304    * @param delta the delta that must be added to previous indicator.
305    */
306   protected void incrementStoredMessagesIndicator(int delta)
307   {
308     synchronized (lock)
309     {
310       storedMessagesIndicator += delta;
311       lock.notifyAll();
312     }
313   }
314 
315   // ---------------------------------------------------------------------------
316   // Methods that must be implemented by concrete super classes.
317   // ---------------------------------------------------------------------------
318 
319   /**
320    * Checks whether the given message can be added into the buffer.
321    * 
322    * @param message the message to be tested.
323    * @return <code>true</code> if the message can be added.
324    */
325   protected abstract boolean canAdd(Message message);
326 
327   /**
328    * Adds a message to the buffer. This method should not check if there is
329    * enough available space provided it has already been done in the
330    * {@link #add}method.
331    * 
332    * @param message the message to be added.
333    */
334   protected abstract void doAdd(Message message);
335 
336   /**
337    * Checks whether there is an available message.
338    * 
339    * @return <code>true</code> if there is an available message.
340    */
341   protected abstract boolean hasAvailableMessage();
342 
343   /**
344    * Removes a message from the buffer. This method should not check if there is
345    * a message available provided it has already been done in the
346    * {@link #remove}method.
347    * 
348    * @return a message.
349    */
350   protected abstract Message doRemove();
351 
352   /**
353    * Gets a message from the buffer. This method should not check if there is a
354    * message available provided it has already been done in the {@link #remove}
355    * method.
356    * 
357    * @return a message.
358    */
359   protected abstract Message doGet();
360 
361   // ---------------------------------------------------------------------------
362   // Methods that may be overriden by concrete super classes.
363   // ---------------------------------------------------------------------------
364 
365   /**
366    * Adds a message to the beginning of the buffer. This method should not check
367    * if there is enough available space provided it has already been done in the
368    * {@link #add}method.
369    * 
370    * @param message the message to be added.
371    */
372   protected void doAddFirst(Message message)
373   {
374     Error.bug(logger, new UnsupportedOperationException  (
375         "This method is not implemented"));
376   }
377 
378   /**
379    * Adds a message to end of the buffer. This method should not check if there
380    * is enough available space provided it has already been done in the
381    * {@link #add}method.
382    * 
383    * @param message the message to be added.
384    */
385   protected void doAddLast(Message message)
386   {
387     Error.bug(logger, new UnsupportedOperationException  (
388         "This method is not implemented"));
389   }
390 
391   /**
392    * Gets the first message from the buffer. This method should not check if
393    * there is a message available provided it has already been done in the
394    * {@link #remove}method.
395    * 
396    * @return a message.
397    */
398   protected Message doGetFirst()
399   {
400     Error.bug(logger, new UnsupportedOperationException  (
401         "This method is not implemented"));
402     return null;
403   }
404 
405   /**
406    * Gets the last message from the buffer. This method should not check if
407    * there is a message available provided it has already been done in the
408    * {@link #remove}method.
409    * 
410    * @return a message.
411    */
412   protected Message doGetLast()
413   {
414     Error.bug(logger, new UnsupportedOperationException  (
415         "This method is not implemented"));
416     return null;
417   }
418 
419   /**
420    * Removes the first message from the buffer. This method should not check if
421    * there is a message available provided it has already been done in the
422    * {@link #remove}method.
423    * 
424    * @return a message.
425    */
426   protected Message doRemoveFirst()
427   {
428     Error.bug(logger, new UnsupportedOperationException  (
429         "This method is not implemented"));
430     return null;
431   }
432 
433   /**
434    * Removes the last message from the buffer. This method should not check if
435    * there is a message available provided it has already been done in the
436    * {@link #remove}method.
437    * 
438    * @return a message.
439    */
440   protected Message doRemoveLast()
441   {
442     Error.bug(logger, new UnsupportedOperationException  (
443         "This method is not implemented"));
444     return null;
445   }
446 
447   // ---------------------------------------------------------------------------
448   // Implementation of the QueueAttributeController interface.
449   // ---------------------------------------------------------------------------
450 
451   /**
452    * @see QueueAttributeController#getMaxCapacity()
453    */
454   public int getMaxCapacity()
455   {
456     synchronized (lock)
457     {
458       return maxCapacity;
459     }
460   }
461 
462   /**
463    * @see QueueAttributeController#setMaxCapacity(int)
464    */
465   public void setMaxCapacity(int maxCapacity)
466   {
467     synchronized (lock)
468     {
469       int previousCapacity = this.maxCapacity;
470       this.maxCapacity = maxCapacity;
471       if (maxCapacity > previousCapacity)
472       {
473         // notify blocking add methods.
474         lock.notifyAll();
475       }
476     }
477   }
478 
479   /**
480    * @see org.objectweb.dream.queue.QueueAttributeController#getCurrentSize()
481    */
482   public int getCurrentSize()
483   {
484     return storedMessagesIndicator;
485   }
486 
487   // ---------------------------------------------------------------------------
488   // Implementation of the BindingController interface.
489   // ---------------------------------------------------------------------------
490 
491   /**
492    * @see org.objectweb.fractal.api.control.BindingController#bindFc(String,
493    *      Object)
494    */
495   public synchronized void bindFc(String   clientItfName, Object   serverItf)
496       throws NoSuchInterfaceException, IllegalBindingException,
497       IllegalLifeCycleException
498   {
499     super.bindFc(clientItfName, serverItf);
500     if (clientItfName.equals(MessageManager.ITF_NAME))
501     {
502       messageManagerItf = (MessageManager) serverItf;
503     }
504   }
505 
506   /**
507    * @see org.objectweb.fractal.api.control.BindingController#listFc()
508    */
509   public String  [] listFc()
510   {
511     return new String  []{MessageManager.ITF_NAME};
512   }
513 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags