1 /*------------------------------------------------------------------------------
2 Name: I_Queue.cs
3 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
4 ------------------------------------------------------------------------------*/
5
6 using System.Text;
7 using System.Collections;
8
9 namespace org.xmlBlaster.util
10 {
11 public interface I_Queue
12 {
13
14 /**
15 * Is called after the instance is created.
16 * @param uniqueQueueId A unique name, allowing to create a unique name for a persistent store (e.g. file name)
17 * "update:/node/heron/client/joe/2", "history:<oid>", "client:joe/2"
18 * @param userData For example a Properties object or a string[] args object passing the configuration data
19 */
20 void Initialize(object /*StorageId*/ storageId, Hashtable properties);
21
22 /**
23 * Puts one queue entry on top of the queue.
24 * See the other put() for a detailed description.
25 * @param msgQueueEntry the queue entry to put into the queue.
26 * @param ignorePutInterceptor if set to 'IGNORE_PUT_INTERCEPTOR=true' the put will not inform the
27 * QueuePutListener that a put occurred.
28 * @throws XmlBlasterException in case an error occurs. Possible causes of
29 * error can be a communication exception of the underlying implementation (jdbc, file system etc).
30 * @see I_QueuePutListener#putPre(I_QueueEntry)
31 * @see I_QueuePutListener#putPost(I_QueueEntry)
32 * @see #put(I_QueueEntry[], bool)
33 */
34 void Put(I_QueueEntry queueEntry);
35
36 /**
37 * Returns the first element in the queue
38 * but does not remove it from that queue (leaves it untouched).
39 * This method does not block.
40 * @return I_QueueEntry the least element with respect to the given ordering or null if the queue is empty.
41 * @throws XmlBlasterException if the underlying implementation gets an exception.
42 */
43 I_QueueEntry Peek();
44
45 /**
46 * Returns maximum the first num element in the queue
47 * but does not remove it from that queue (leaves it untouched).
48 * This method does not block.
49 * @param numOfEntries Access num entries, if -1 access all entries currently found
50 * @param numOfBytes is the maximum size in bytes of the array to return, -1 is unlimited .
51 * @return list with I_QueueEntry, the least elements with respect to the given ordering, or size()==0
52 * @throws XmlBlasterException if the underlying implementation gets an exception.
53 */
54 //ArrayList peek(int numOfEntries, long numOfBytes);
55
56 /**
57 * Removes the first element in the queue.
58 * This method does not block.
59 * @return the size in bytes of the removed elements
60 * @throws XmlBlasterException if the underlying implementation gets an exception.
61 */
62 int Remove();
63
64 /**
65 * Returns the number of elements having the persistent flag set in this queue.
66 * If the implementation of this interface is not able to return the correct
67 * number of entries (for example if the implementation must make a remote
68 * call to a DB which is temporarly not available) it will return -1.
69 * @return int the number of elements currently in the queue
70 */
71 long GetNumOfPersistentEntries();
72
73 /**
74 * Returns the amount of bytes used by the persistent entries in the queue
75 * If the implementation of this interface is not able to return the correct
76 * number of entries (for example if the implementation must make a remote
77 * call to a DB which is temporarly not available) it will return -1.
78 * @return The amount of bytes currently in the queue
79 */
80 long GetNumOfPersistentBytes();
81
82 /**
83 * Access the configured capacity (maximum bytes) for this queue
84 * @return The maximum capacity for the queue in bytes
85 */
86 long GetMaxNumOfBytes();
87
88 /**
89 * Removes all the transient entries (the ones which have the flag 'persistent'
90 * set to false.
91 int removeTransient() throws XmlBlasterException;
92 */
93
94 /**
95 * Remove all queue entries.
96 * @return The number of entries erased
97 */
98 long Clear();
99
100 /**
101 * Shutdown the implementation, sync with data store, free resources.
102 * Persistent entries will NOT be deleted.
103 */
104 void Shutdown();
105 }
106 } // namespace
syntax highlighted by Code2HTML, v. 0.9.1