Buffer


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.message.Message;
28  
29  /**
30   * This interface defines methods that must be implemented by a buffer. Buffers
31   * are used to store messages. It is possible to
32   * <ul>
33   * <li>add and remove messages</li>
34   * <li>get an indicator on stored messages</li>
35   * <li>get an indicator on the available space in the buffer</li>
36   * <li>get an indicator on messages available for removal</li>
37   * </ul>
38   * <p>
39   * <i>Note 1: </i> all the messages that are stored in a buffer are not always
40   * available for removal (e.g. when the buffer implements an ordering policy).
41   * <p>
42   * <i>Note 2: </i> the different indicators (stored messages, available space,
43   * and available messages) have no predetermined semantics: the indicator can be
44   * a number of messages, a number of bytes, etc.
45   */
46  public interface Buffer
47  {
48    /** The commonly used name to refer to this interface. */
49    String   ITF_NAME = "buffer";
50  
51    /**
52     * Returns an indicator on stored messages. The semantic of this indicator
53     * depends on the buffer implementation. Typical examples of indicators are
54     * the number of messages, the number of bytes, etc.
55     * 
56     * @return an indicator on stored messages.
57     */
58    int storedMessagesIndicator();
59  
60    /**
61     * Returns an indicator on available messages. The semantic of this indicator
62     * depends on the buffer implementation. Typical examples of indicators are
63     * the number of messages, the number of bytes, etc.
64     * 
65     * @return an indicator on available messages.
66     */
67    int availableMessagesIndicator();
68  
69    /**
70     * Returns an indicator on available space. The semantic of this indicator
71     * depends on the buffer implementation. Typical examples of indicators are
72     * the number of messages, the number of bytes, etc. <i>Note: </i> when the
73     * buffer has no maximum storage capabilities, this method must return
74     * <code>Integer.MAX_VALUE</code>.
75     * 
76     * @return an indicator on available space.
77     */
78    int availableSpaceIndicator();
79  
80    /**
81     * Adds the specified message to the buffer. This method may block if there is
82     * not enough space available.
83     * <p>
84     * Buffers may place limitations on what elements may be added to this buffer.
85     * In particular, some buffers require that messages contain particular
86     * chunks.
87     * 
88     * @param message message to be addedto be appended to this list.
89     * @throws InterruptedException if it is interrupted while adding the message.
90     */
91    void add(Message message) throws InterruptedException  ;
92  
93    /**
94     * Removes a message from the buffer. This method blocks if
95     * {@link #availableMessagesIndicator}returns <code>0</code>.
96     * 
97     * @return a message.
98     * @throws InterruptedException if it is interrupted while removing a message.
99     */
100   Message remove() throws InterruptedException  ;
101 
102   /**
103    * Gets a message from the buffer. This method blocks if
104    * {@link #availableMessagesIndicator}returns <code>0</code>.
105    * 
106    * @return a message.
107    * @throws InterruptedException if it is interrupted while removing a message.
108    */
109   Message get() throws InterruptedException  ;
110 
111 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags