KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > fr > dyade > aaa > agent > MessageQueue


1 /*
2  * Copyright (C) 2001 - 2004 ScalAgent Distributed Technologies
3  * Copyright (C) 1996 - 2000 BULL
4  * Copyright (C) 1996 - 2000 INRIA
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
19  * USA.
20  *
21  * Initial developer(s): Dyade
22  * Contributor(s): ScalAgent Distributed Technologies
23  */
24 package fr.dyade.aaa.agent;
25
26 import java.io.*;
27
28 import org.objectweb.util.monolog.api.BasicLevel;
29 import org.objectweb.util.monolog.api.Logger;
30
31 import fr.dyade.aaa.util.EmptyQueueException;
32
33 /**
34  * Interface <code>MessageQueue</code> represents a First-In-First-Out (FIFO)
35  * persistent list of Message (source and target agent identifier,
36  * notification).
37  */
38 interface MessageQueue {
39   /**
40    * Insert a message in the queue, it should only be used during
41    * initialization for restoring the queue state.
42    *
43    * @param item the message to be pushed onto this queue.
44    */
45   public void insert(Message item);
46
47   /**
48    * Pushes a message onto the bottom of this queue. It should only
49    * be used during a transaction. The item will be really available
50    * after the transaction commit and the queue validate.
51    *
52    * @param item the message to be pushed onto this queue.
53    */
54   public void push(Message item);
55
56   /**
57    * Removes the message at the top of this queue.
58    * It must only be used during a transaction.
59    *
60    * @return The message at the top of this queue.
61    * @exception EmptyQueueException if this queue is empty.
62    */
63   public Message pop() throws EmptyQueueException;
64
65   /**
66    * Atomicaly validates all messages pushed in queue during a reaction.
67    * It must only be used during a transaction.
68    */
69   public void validate();
70
71   /**
72    * Looks at the message at the top of this queue without removing
73    * it from the queue.
74    * It should never be used during a transaction to avoid dead-lock
75    * problems.
76    *
77    * @return the message at the top of this queue.
78    * @exception InterruptedException if another thread has interrupted the
79    * current thread.
80    */
81   public Message get() throws InterruptedException JavaDoc ;
82
83   /**
84    * Looks at the message at the top of this queue without removing
85    * it from the queue. It waits until a message is available or the
86    * specified amount of time has elapsed.
87    * It should never be used during a transaction to avoid dead-lock
88    * problems.
89    *
90    * @param timeout the maximum time to wait in milliseconds.
91    * @return the message at the top of this queue.
92    * @exception InterruptedException if another thread has interrupted the
93    * current thread.
94    * @exception IllegalArgumentException if the value of timeout is negative.
95    */
96   public Message get(long timeout) throws InterruptedException JavaDoc;
97
98   /**
99    * Returns the number of messages in this <code>MessageQueue</code>
100    * object. Be careful, the result includes messages to be validated.
101    *
102    * @return the size of the MessageQueue
103    */
104   public int size();
105 }
106
Popular Tags