i_queue.java

java开源的企业总线.xmlBlaster

   /**
    * Returns the first element in the queue
    * but does not remove it from that queue (leaves it untouched).
    * This method does not block.
    * @return I_QueueEntry the least element with respect to the given ordering or null if the queue is empty.
    * @throws XmlBlasterException if the underlying implementation gets an exception.
    */
   I_QueueEntry peek() throws XmlBlasterException;

   /**
    * Returns maximum the first num element in the queue
    * but does not remove it from that queue (leaves it untouched).
    * This method does not block.
    * @param numOfEntries Access num entries, if -1 access all entries currently found
    * @param numOfBytes is the maximum size in bytes of the array to return, -1 is unlimited .
    * @return list with I_QueueEntry, the least elements with respect to the given ordering, or size()==0
    * @throws XmlBlasterException if the underlying implementation gets an exception.
    */
   ArrayList peek(int numOfEntries, long numOfBytes) throws XmlBlasterException;

   /**
    * Returns maximum the first num element in the queue of highest priority
    * but does not remove it from that queue (leaves it untouched).
    * This method does not block.
    * @param numOfEntries Access num entries, if -1 access all entries currently found
    * @param numOfBytes so many entries are returned as not to exceed the amount specified. If the first
    *        entry is bigger than this amount, it is returned anyway. -1 is unlimited.
    * @return list with I_QueueEntry, the least elements with respect to the given ordering, or size()==0
    * @throws XmlBlasterException if the underlying implementation gets an exception.
    */
   ArrayList peekSamePriority(int numOfEntries, long numOfBytes) throws XmlBlasterException;

   /**
    * Returns maximum given number of entries from the queue (none blocking).
    * @param numOfEntries Access num entries, if -1 take all entries currently found
    * @param numOfBytes so many entries are returned as not to exceed the amount specified. If the first
    *        entry is bigger than this amount, it is returned anyway.
    * @param minPriority The lower priority (inclusive), usually 0 lowest, 9 highest, <0 is not allowed
    * @param maxPriority The higher priority (inclusive), usually 0 lowest, 9 highest, <0 is not allowed
    * @return list with I_QueueEntry, the least elements with respect to the given ordering, or size()==0
    * @throws XmlBlasterException in case the underlying implementation gets an exception while retrieving the element.
    */
   ArrayList peekWithPriority(int numOfEntries, long numOfBytes, int minPriority, int maxPriority) throws XmlBlasterException;

   /**
    * It returns the entries which are higher than the entry specified in the argument list.
    * @param limitEntry the entry which limits the peek. Only entries of higher order, i.e.
    *        entries having a higher priority, or same priority and lower uniqueId are
    *        returned. If entryLimit is null or no entries are higher than entryLimit,
    *        an empty list is returned.
    * Note: The limitEntry does not need to be in the queue.
    * @deprecated you should use directly removeWithLimitEntry
    */
   ArrayList peekWithLimitEntry(I_QueueEntry limitEntry) throws XmlBlasterException;

   /**
    * It removes the entries which are higher than the entry specified in the argument list.
    * @param limitEntry the entry which limits the remove. Only entries of higher order, i.e.
    *        entries having a higher priority, or same priority and lower uniqueId are
    *        deleted. If entryLimit is null or no entries are higher than entryLimit,
    *        an empty list is returned.
    * @param inclusive if 'true', then also the entry specified will be removed (if it exists). If false
    *        the remove is exclusive, i.e. the specified entry is left in the queue.
    * Note: The limitEntry does not need to be in the queue.
    */
   long removeWithLimitEntry(I_QueueEntry limitEntry, boolean inclusive) throws XmlBlasterException;

   /**
    * Removes the first element in the queue. 
    * This method does not block.
    * @return the size in bytes of the removed elements
    * @throws XmlBlasterException if the underlying implementation gets an exception.
    */
   int remove() throws XmlBlasterException;

   /**
    * Removes max num messages.
    * This method does not block.
    * @param numOfEntries Erase num entries or less if less entries are available, -1 erases everything
    * @param numOfBytes so many entries are returned as not to exceed the amount specified. If the first
    *        entry is bigger than this amount, it is removed anyway.
    * @return Number of entries erased
    * @throws XmlBlasterException if the underlying implementation gets an exception.
    */
   long remove(long numOfEntries, long numOfBytes) throws XmlBlasterException;

   /**
    * Removes max numOfEntries messages (or less depending on the numOfBytes).
    * This method does not block.
    * @param numOfEntries Erase num entries or less if less entries are available, -1 erases everything
    * @param numOfBytes so many entries are returned as not to exceed the amout specified. If the first
    *        entry is bigger than this amount, it is returned anyway.
    * @param minPriority The lower priority (inclusive), usually 0 lowest, 9 highest
    * @param maxPriority The higher priority (inclusive), usually 0 lowest, 9 highest
    * @return Number of entries erased
    * @throws XmlBlasterException in case the underlying implementation gets an exception while retrieving the element.
    */
   long removeWithPriority(long numOfEntries, long numOfBytes, int minPriority, int maxPriority) throws XmlBlasterException;

   /**
    * Returns the number of elements having the persistent flag set in this queue.
    * If the implementation of this interface is not able to return the correct
    * number of entries (for example if the implementation must make a remote
    * call to a DB which is temporarly not available) it will return -1.
    * @return int the number of elements currently in the queue
    */
   long getNumOfPersistentEntries();

   /**
    * Returns the amount of bytes used by the persistent entries in the queue
    * If the implementation of this interface is not able to return the correct
    * number of entries (for example if the implementation must make a remote
    * call to a DB which is temporarly not available) it will return -1.
    * @return The amount of bytes currently in the queue
    */
   long getNumOfPersistentBytes();

   /**
    * Access the configured capacity (maximum bytes) for this queue
    * @return The maximum capacity for the queue in bytes
    */
   long getMaxNumOfBytes();

   /*
    * Updates the given queue entry with a new value. Note that this
    * can be used if an entry with the unique id already exists.
    * ?? Does this really make sense here since we need to store history ??
    * ?? Should we define a switch which can deactivate storage of history ??
    */
//   int update(I_QueueEntry queueEntry) throws XmlBlasterException;

   /*
    * Removes the given entry.
    * @param dataId the unique id. It must be unique within the storage area
    *        of the implementing queue. In other words, if the underlying
    *        implementation is on RAM, then the storage area is the JVM, that
    *        is the queue must be unique in the same JVM. If the queue is a
    *        jdbc, the dataId is unique in the DB used.
    * @returns the number of elements erased (0 or 1)
    */
//   int removeRandom(long dataId) throws XmlBlasterException;

   /*
    * Removes the given entries.
    * @param dataIdArray the entries to erase.
    * @return the number of elements erased.
    */
//   long removeRandom(long[] dataIdArray) throws XmlBlasterException;

   /**
    * Removes the given entries.
    * @param queueEntries the entries to erase.
    * @return a boolean array of the same size as the queueEntries array. If an entry is true it means
    *         it could be removed, if false it means it could not be removed (probably already removed)
    */
   boolean[] removeRandom(I_Entry[] queueEntries) throws XmlBlasterException;

   /**
    * Removes the given entry.
    * @param entry The entry to erase.
    * @return the number of elements erased.
    */
   int removeRandom(I_Entry entry) throws XmlBlasterException;

   /**
    * Removes all the transient entries (the ones which have the flag 'persistent'
    * set to false.
    */
   int removeTransient() throws XmlBlasterException;

   /**
    * Remove all queue entries. 
    * @return The number of entries erased
    */
   public long clear();

   /**
    * Shutdown the implementation, sync with data store, free resources.
    * Persistent entries will NOT be deleted.
    */
   public void shutdown();

   /**
    * removes the head of the queue until (but not included) the entry specified
    * as the argument.
    * @param toEntry the entry until to remove.
    * @return long the number of entries deleted.
    */
   public long removeHead(I_QueueEntry toEntry) throws XmlBlasterException;


   /**
    * destroys all the resources associated to this queue. This means that all
    * temporary and persistent resources are removed.
    */
//   public void destroy() throws XmlBlasterException;

   /**
    * @return a human readable usage help string
    */
   public String usage();

   /**
    * Dump state to XML string. 
    * @param extraOffset Indent the dump with given ASCII blanks
    * @return An xml encoded dump
    */
   public String toXml(String extraOffset);

   /**
    * Dump all entries of this queue to the given output stream. 
    * The messages are XML formatted.
    * @param out The output stream to dump the entries
    * @param props Configuration properties, not yet specified, just pass null
    * @return Number of entries dumped
    */
   public long embeddedObjectsToXml(OutputStream out, Properties props) throws Exception;
   
}