1 /*------------------------------------------------------------------------------
2 Name: I_Queue.h
3 Project: xmlBlaster.org
4 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
5 ------------------------------------------------------------------------------*/
6 #ifndef _UTIL_QUEUE_I_QUEUE_H
7 #define _UTIL_QUEUE_I_QUEUE_H
8
9 #include <util/xmlBlasterDef.h>
10 #include <util/ReferenceHolder.h>
11 #include <util/queue/MsgQueueEntry.h>
12 #include <util/plugin/I_Plugin.h>
13
14 namespace org { namespace xmlBlaster { namespace util { namespace queue {
15
16 /**
17 * Smart pointer support.
18 */
19 typedef ReferenceHolder<MsgQueueEntry> EntryType;
20
21 /**
22 * Interface for queue implementations (RAM, JDBC or CACHE).
23 *
24 * @author <a href='mailto:laghi@swissinfo.org'>Michele Laghi</a>
25 * @author <a href='mailto:xmlblast@marcelruff.info'>Marcel Ruff</a>
26 */
27 class Dll_Export I_Queue : public virtual org::xmlBlaster::util::plugin::I_Plugin
28 {
29 public:
30 virtual ~I_Queue() {};
31
32 /**
33 * Puts a new entry into the queue.
34 * The put() method takes a clone of the passed entry, you can safely destroy
35 * your passed entry after this invocation.
36 * @param entry A message which is stored in the queue
37 * @throws XmlBlasterException on problems
38 */
39 virtual void put(const MsgQueueEntry &entry) = 0;
40
41 /**
42 * Returns the entries with the highest priority in the queue. If 'maxNumOfEntries' is positive,
43 * this is the maximum number of entries to return. If maxNumOfBytes is positive, only the entries
44 * which fit into the range specified are returned. If there are no such entries, an empty std::vector is
45 * returned.
46 * @return A vector with EntryType, this smart pointer wraps the real message, you don't need to take
47 * care on freeing memory.
48 * @throws XmlBlasterException on problems
49 */
50 virtual const std::vector<EntryType> peekWithSamePriority(long maxNumOfEntries=-1, long maxNumOfBytes=-1) const = 0;
51
52 /**
53 * Deletes the entries specified in the std::vector in the argument list. If this std::vector is empty or if
54 * the queue is empty, zero (0) is returned, otherwise it returns the number of entries really deleted.
55 * @param start The inclusive beginning of the messages to remove
56 * @param end The exclusive ending
57 * @return Number of entries removed
58 * @throws XmlBlasterException on problems
59 */
60 virtual long randomRemove(const std::vector<EntryType>::const_iterator &start, const std::vector<EntryType>::const_iterator &end) = 0;
61
62 /**
63 * Access the current number of entries.
64 * @return The number of entries in the queue
65 */
66 virtual long getNumOfEntries() const = 0;
67
68 /**
69 * Access the configured maximum number of elements for this queue.
70 * @return The maximum number of elements in the queue
71 */
72 virtual long getMaxNumOfEntries() const = 0;
73
74 /**
75 * Returns the amount of bytes currently in the queue.
76 * If the implementation of this interface is not able to return the correct
77 * number of entries (for example if the implementation must make a remote
78 * call to a DB which is temporarly not available) it will return -1.
79 * @return The amount of bytes currently in the queue, returns -1 on error
80 */
81 virtual int64_t getNumOfBytes() const = 0;
82
83 /**
84 * Access the configured capacity (maximum bytes) for this queue.
85 * @return The maximum capacity for the queue in bytes
86 */
87 virtual int64_t getMaxNumOfBytes() const = 0;
88
89 /**
90 * Clears (removes all entries) this queue
91 * @throws XmlBlasterException on problems
92 */
93 virtual void clear() = 0;
94
95 /**
96 * @return true if the queue is empty, false otherwise
97 * @throws XmlBlasterException on problems
98 */
99 virtual bool empty() const = 0;
100
101 /**
102 * Removes all entries and cleans up the storage,
103 * for example with a database it would remove all tables and relating database files.
104 * This is an administrative task.
105 * The class instance calling <code>destroy()</code> is invalid after this call
106 * @throws XmlBlasterException if failed
107 */
108 virtual void destroy() = 0;
109 };
110
111 }}}} // namespace
112
113 #endif
syntax highlighted by Code2HTML, v. 0.9.1