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