OSMQ
v2.0.1

osmq.mque
Class MQue

java.lang.Object
  extended byosmq.mque.MQue
All Implemented Interfaces:
EventCounter, java.io.Serializable, Writable
Direct Known Subclasses:
PersistableMQue

public class MQue
extends java.lang.Object
implements Writable, EventCounter, java.io.Serializable

A thread-safe, byte-oriented FIFO (first-in first-out) queue that holds byte array and/or String elements. An instance can have one or more writing threads, but limited to only one reader.

This class is an alternative to an OS pipe, since a Queue can hold any number of objects, limted only by its implementation.

The implementation includes the following aggreagate classes:

1) a MemoryFifo (memory-resident) and

2) a DiskFifo (file-resident)

The MQue uses the MemoryFifo exclusively until a user-definable threshold capacity is reached. It then utilizes the DiskFifo to hold the excess entries.

A MemoryFifo is instantiated in an opened state. with a DiskFifo being created only if/when necessary.

Basic Algorithms Read priority is

1) putback element

2) disk

3) memory

Always write to the MemoryFifo, with a test before the write to determine whether memory is full. If it is full, the memory elements are appended to the DiskFifo.

See Also:
Serialized Form

Constructor Summary
MQue()
           
MQue(java.lang.String name)
           
MQue(java.lang.String name, long startcount)
           
 
Method Summary
 void clear()
          Clears the queue of all elements.
 void clearHighestSize()
          Clears the highest count.
 void close()
          Halts all writes, resulting in a QueueException being thrown on any subsequent calls to the Queue object's write methods.
 boolean flushToPullCount(long count)
          Empty records from the queue until the pulled count equals a specific value
 long getBytesWritten()
          Returns the cumulative length (in bytes) of all elements that have been written to the queue.
 long getEventCount()
          Returns the number of element read events.
 java.lang.String getInstanceName()
          Returns a name associated with this MQue instance.
 int getMaxThreshold()
          Returns the maximum capacity threshold (element count).
 int getPagingThreshold()
          Returns the paging threshold (in elements).
 long getPullCount()
          Returns the number of elements that have been read from the queue since it was instantiated.
 long getPushCount()
          Returns the number of elements that have been written to the queue since it was instantiated.
 long highestSize()
          Returns the highest queue count (elements on the queue) since the queue was instantiated or since the max count was cleared.
 boolean isClosed()
          Returns true if the queue has been closed.
 boolean isEmpty()
          Returns true if the queue size (element count) is zero.
 boolean isHaltReads()
          Returns true if the queue is in a read halt state.
 boolean isHaltWrites()
          Returns true if the queue is in a write halt state.
 boolean isOpen()
          Returns true if the queue is in an opened state.
 byte[] nextElement()
          Returns the next element from the queue.
 void open()
          Reopens a queue that has been closed.
 void putBack(byte[] o)
          Returns an element that was pulled from the queue.
 byte[] readBytes()
          Returns the next element in the queue as a byte array.
 byte[] readBytesNoWait()
          Returns the next element in the queue as a byte array.
 java.lang.String readString()
          Returns the next element on the queue as a String.
 java.lang.String readStringNoWait()
          Returns the next element on the queue as a String.
 void setHaltWrites(boolean halt)
          Sets the write halt mode.
 void setInstanceName(java.lang.String instancename)
          Sets a name associated with this MQue instance.
 void setMaxThreshold(int threshold)
          Sets the maximum capacity threshold.
 void setPagingThreshold(int v)
          Sets the element count threshold, where overflow elements are paged to disk.
 long size()
          Returns the number of elements currently on the queue.
 java.lang.String toString()
           
 void writeAllFromQue(MQue f)
          Pulls elements from another queue, writing them to this queue.
 void writeBytes(byte[] s)
          Creates a duplicate copy of the byte array and writes it to the queue.
 void writeBytesNoDuplicate(byte[] s)
          Writes the byte array to the queue without duplicating it.
 void writeString(java.lang.String s)
          Writes a String to the queue.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

MQue

public MQue()

MQue

public MQue(java.lang.String name)

MQue

public MQue(java.lang.String name,
            long startcount)
Method Detail

getInstanceName

public java.lang.String getInstanceName()
Returns a name associated with this MQue instance.


setInstanceName

public void setInstanceName(java.lang.String instancename)
Sets a name associated with this MQue instance.


toString

public java.lang.String toString()

getBytesWritten

public final long getBytesWritten()
Returns the cumulative length (in bytes) of all elements that have been written to the queue.


writeString

public void writeString(java.lang.String s)
                 throws java.io.IOException
Writes a String to the queue.

Throws:
java.io.IOException - if queue is in a closed state, if the queue is in a write-halt state, or if the total number of elements in the queue would exceed the max allowable count.

writeBytes

public void writeBytes(byte[] s)
                throws java.io.IOException
Creates a duplicate copy of the byte array and writes it to the queue.

Specified by:
writeBytes in interface Writable
Throws:
java.io.IOException - if queue is in a closed state, if the queue is in a write-halt state, or if the total number of elements in the queue would exceed the max allowable count.

writeBytesNoDuplicate

public void writeBytesNoDuplicate(byte[] s)
                           throws java.io.IOException
Writes the byte array to the queue without duplicating it. Although this is a more rapid method than writeBytes(byte[]), it may cause unpredicable results if the array is later changed.

Throws:
java.io.IOException - if queue is in a closed state, if the queue is in a write-halt state, or if the total number of elements in the queue would exceed the max allowable count.

readBytesNoWait

public byte[] readBytesNoWait()
                       throws java.io.IOException
Returns the next element in the queue as a byte array. This is a non-blocking read of the queue: if the queue is empty, this method returns a value of null.

Throws:
java.io.IOException - if queue is in a closed state and the queue is empty.

readBytes

public byte[] readBytes()
                 throws java.io.IOException
Returns the next element in the queue as a byte array. If the queue is empty, the method blocks until one is available or the queue is closed.

Throws:
java.io.IOException - if queue is in a closed state and the queue is empty.

flushToPullCount

public boolean flushToPullCount(long count)
                         throws java.io.IOException
Empty records from the queue until the pulled count equals a specific value

Throws:
java.io.IOException

clear

public void clear()
           throws java.io.IOException
Clears the queue of all elements.

Throws:
java.io.IOException

isOpen

public boolean isOpen()
Returns true if the queue is in an opened state. Otherwise, returns false.


isClosed

public boolean isClosed()
Returns true if the queue has been closed. Otherwise, returns false.


open

public void open()
Reopens a queue that has been closed.


close

public void close()
Halts all writes, resulting in a QueueException being thrown on any subsequent calls to the Queue object's write methods. When MQue's size drops to zero, read method calls will throw a QueueException.


writeAllFromQue

public void writeAllFromQue(MQue f)
                     throws java.io.IOException
Pulls elements from another queue, writing them to this queue.

Throws:
java.io.IOException

readStringNoWait

public java.lang.String readStringNoWait()
                                  throws java.io.IOException
Returns the next element on the queue as a String. This is a non-blocking read of the queue: if the queue is empty, this method returns a value of null.

Throws:
java.io.IOException - if queue is in a closed state and the queue is empty.

readString

public java.lang.String readString()
                            throws java.io.IOException
Returns the next element on the queue as a String. If the queue is empty, the method blocks until an element is available or the queue is closed.

Throws:
java.io.IOException - if queue is in a closed state and the queue is empty.

putBack

public void putBack(byte[] o)
             throws java.io.IOException
Returns an element that was pulled from the queue. This element will be the next to be read from the queue.

Throws:
java.io.IOException - if no read has been performed since the last occurance of a putBack(), or if the queue is closed.

isEmpty

public boolean isEmpty()
Returns true if the queue size (element count) is zero.


nextElement

public byte[] nextElement()
Returns the next element from the queue. This is an alias method for readBytes().

See Also:
readBytes()

size

public long size()
Returns the number of elements currently on the queue.


highestSize

public long highestSize()
Returns the highest queue count (elements on the queue) since the queue was instantiated or since the max count was cleared.

See Also:
clearHighestSize()

clearHighestSize

public void clearHighestSize()
Clears the highest count. A call to highSize() immediately after calling this method returns a value of zero.

See Also:
highestSize()

getPushCount

public long getPushCount()
Returns the number of elements that have been written to the queue since it was instantiated.


getPullCount

public long getPullCount()
Returns the number of elements that have been read from the queue since it was instantiated.


isHaltWrites

public boolean isHaltWrites()
Returns true if the queue is in a write halt state. Otherwise, returns false.


setHaltWrites

public void setHaltWrites(boolean halt)
Sets the write halt mode. When set to true, any attempt to write an element to the queue will return an exception.


isHaltReads

public boolean isHaltReads()
Returns true if the queue is in a read halt state. A read halt state is when the queue is closed and the queue is empty. Attempting to read an element in a read halt state throws an exception.


setPagingThreshold

public void setPagingThreshold(int v)
Sets the element count threshold, where overflow elements are paged to disk.

See Also:
getPagingThreshold()

getPagingThreshold

public int getPagingThreshold()
Returns the paging threshold (in elements).

See Also:
setPagingThreshold(int)

setMaxThreshold

public void setMaxThreshold(int threshold)
Sets the maximum capacity threshold. When the queue reaches this capacity (element count), subsequent writes throw an exception. A value of 0 indicates no threshold.


getMaxThreshold

public int getMaxThreshold()
Returns the maximum capacity threshold (element count). When the queue reaches this capacity, subsequent writes throw an exception. A value of 0 indicates no threshold.


getEventCount

public long getEventCount()
Returns the number of element read events. This is an alias for getPullCount(). This method supports EventCounter interface.

Specified by:
getEventCount in interface EventCounter

(c) 2000 - 2003 MQue Systems
All Rights Reserved