com.safmq
Class MessageQueue

java.lang.Object
  com.safmq.MessageQueue

public class MessageQueue
extends java.lang.Object

This class represents a SAFMQ message queue by providing a facade in front of the MQConnection. This facade provides an interface to queue operations such as enqueueing messages, retrieving messages, and scanning the queue for messages with particular attributes.
Note: When a queue is no longer in use, a call to Close() should be made so that resources on the server are released. Additionally, when cursors are no longer needed, a call to CloseCursor() should be made.

See Also:

Close(), CloseCursor(CursorHandle), MQConnection

Constructor Summary

MessageQueue(MQConnection con, QueueHandle que)
Constructs the MessageQueue object, from an open handle to a message queue.

MessageQueue(java.lang.String queuename, MQConnection con)
Constructs the MessageQueue object, from the queue's name and a connection to the queue server.

Method Summary

int	AdvanceCursor(CursorHandle cursorID) Advances the cursor to the next message in the queue.
int	Close() Closes the connection to the queue.
int	CloseCursor(CursorHandle cursorID) Closes a cursor when it is no longer needed to access the queue.
int	Enqueue(QueueMessage msg) Places a message on the queue.
MQConnection	getConnection()
int	GetQueueStatistics(boolean includeStorageBytes, boolean includeMessageBytes, QueueStatistics stats) Gets statistics about an open queue.
int	OpenCursor(CursorHandle cursorID) Opens a cursor for sequential reading of the queue.
int	PeekCursor(boolean retrievebody, CursorHandle cursorID, QueueMessage msg) Retrieves the message pointed to by cursorID.
int	PeekFront(boolean retrievebody, int timeout, QueueMessage msg) Gathers the highest priority FIFO message present on the queue.
int	PeekID(boolean retrievebody, UUID id, int timeout, QueueMessage msg) Gathers the message identified by id in the message's receipt id, set prior to the message having been enqueued (See: Enqueue(QueueMessage).
int	Retrieve(boolean retrievebody, int timeout, QueueMessage msg) Retrieves the highest priority FIFO message present on the queue.
int	RetrieveCursor(boolean retrievebody, CursorHandle cursorID, QueueMessage msg) Retrieves the message pointed to by cursorID.
int	RetrieveID(boolean retrievebody, UUID id, int timeout, QueueMessage msg) Retrieves the message identified by id in the message's receipt id, set prior to the message having been enqueued (See: Enqueue(QueueMessage).
int	SeekID(UUID id, int timeout, CursorHandle cursorID) Attempts to locate the messaged indicated by id.
int	TestCursor(CursorHandle cursorID) Determines whether the cursor indicated by cursorID is still a valid cursor, and has not been invalidated by other queue readers.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MessageQueue

public MessageQueue(java.lang.String queuename,
                    MQConnection con)
             throws MQException

Constructs the MessageQueue object, from the queue's name and a connection to the queue server. This method opens a reference to the queue. In case of an error, an MQException is thrown reporting the status of the connection.

Parameters:

queuename - The name of the queue to be opened

con - A valid connection to a SAFMQ server

Throws:

MQException - In the case that OpenQueue reports an error

MessageQueue

public MessageQueue(MQConnection con,
                    QueueHandle que)

Constructs the MessageQueue object, from an open handle to a message queue. This interface is useful when working with a Temporary Queue, or already open queue.

Parameters:

con - A valid connection to a SAFMQ server

Throws:

MQException - In the case that OpenQueue reports an error

Method Detail

Close

public int Close()

Closes the connection to the queue. After a call to close the MessageQueue is no longer valid and should not be used.

Returns:

The result code from a call to MQConnection.CloseQueue()

See Also:

MQConnection.CloseQueue(QueueHandle) for details on errors

GetQueueStatistics

public int GetQueueStatistics(boolean includeStorageBytes,
                              boolean includeMessageBytes,
                              QueueStatistics stats)

Gets statistics about an open queue. Places statistic information into the parameter stats.

Parameters:

includeStorageBytes - Causes server to calculate the number of bytes on disk

includeMessageBytes - Causes the server to calculate the number of bytes in queue, may be less than bytes on disk

stats - Receives the statistics information.

Returns:

Safmq.EC_NOERROR on success
Safmq.EC_NETWORKERROR
Safmq.EC_NOTOPEN

Enqueue

public int Enqueue(QueueMessage msg)

Places a message on the queue. The object msg must have been previously prepared before calling this method. Upon successful sending of the message, the message id and message time stamp will be set by the server and may be retrieved by a call to QueueMessage.getMessageID() and QueueMessage.getTimeStamp() respectively.

Note: Message responders will typically place the message id of the original message in the receipt id of the message being returned. This round-trip message identification is provided by SAFMQ as a method for coordinated two-way communications.

Parameters:

msg - The message to be placed on the queue

Returns:

The results of a call to MQConnection.Enqueue()

See Also:

MQConnection.Enqueue(QueueHandle,QueueMessage) for details on errors

Retrieve

public int Retrieve(boolean retrievebody,
                    int timeout,
                    QueueMessage msg)

Retrieves the highest priority FIFO message present on the queue. The results are placed in the object msg.

Note: Retrieved messages are removed from the queue

Parameters:

retrievebody - A flag indicating whether the body of the message should be retrieved

timeout - The number of seconds to wait before returning, a value of zero (0) will cause the method to return immediately if no messages are present on the queue, a value of (-1) will cause the method to wait until a message is placed on the queue.

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise see MQConnection.Retrieve() for result codes.

See Also:

MQConnection.Retrieve(QueueHandle,boolean,int,QueueMessage)

RetrieveID

public int RetrieveID(boolean retrievebody,
                      UUID id,
                      int timeout,
                      QueueMessage msg)

Retrieves the message identified by id in the message's receipt id, set prior to the message having been enqueued (See: Enqueue(QueueMessage). The results are placed in the object msg.

Note: Message responders will typically place the message id of the original message in the receipt id of the message being returned. This round-trip message identification is provided by SAFMQ as a method for coordinated two-way communications.

Note: Retrieved messages are removed from the queue.

Parameters:

retrievebody - A flag indicating whether the body of the message should be retrieved

id - The UUID of the message to be retrieved.

timeout - The number of seconds to wait before returning, a value of zero (0) will cause the method to return immediately if no messages are present on the queue, a value of (-1) will cause the method to wait until a message is placed on the queue.

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise see MQConnection.RetrieveID() for result codes.

See Also:

MQConnection.Retrieve(QueueHandle,boolean,int,QueueMessage), Enqueue(QueueMessage)

RetrieveCursor

public int RetrieveCursor(boolean retrievebody,
                          CursorHandle cursorID,
                          QueueMessage msg)

Retrieves the message pointed to by cursorID. The results are placed in the object msg.

Note: Retrieved messages are removed from the queue.

Parameters:

retrievebody - A flag indicating whether the body of the message should be retrieved

cursorID - The cursor indicating the current position in the queue to be read from

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise see MQConnection.Retrieve() for result codes.

See Also:

MQConnection.Retrieve(QueueHandle,boolean,int,QueueMessage)

PeekFront

public int PeekFront(boolean retrievebody,
                     int timeout,
                     QueueMessage msg)

Gathers the highest priority FIFO message present on the queue. The results are placed in the object msg. Any errors from the operation are returned on the stack. The message retrieved is not removed from the queue and is available for reading by other queue readers.

Parameters:

retrievebody - A flag indicating whether the body of the message should be retrieved

timeout - The number of seconds to wait before returning, a value of zero (0) will cause the method to return immediately if no messages are present on the queue, a value of (-1) will cause the method to wait until a message is placed on the queue.

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise see MQConnection.Retrieve() for result codes.

See Also:

MQConnection.Retrieve(QueueHandle,boolean,int,QueueMessage)

PeekID

public int PeekID(boolean retrievebody,
                  UUID id,
                  int timeout,
                  QueueMessage msg)

Gathers the message identified by id in the message's receipt id, set prior to the message having been enqueued (See: Enqueue(QueueMessage). The results are placed in the object msg. The message retrieved is not removed from the queue and is available for reading by other queue readers.

Note: Message responders will typically place the message id of the original message in the receipt id of the message being returned. This round-trip message identification is provided by SAFMQ as a method for coordinated two-way communications.

Parameters:

retrievebody - A flag indicating whether the body of the message should be retrieved

id - The UUID of the message to be retrieved.

timeout - The number of seconds to wait before returning, a value of zero (0) will cause the method to return immediately if no messages are present on the queue, a value of (-1) will cause the method to wait until a message is placed on the queue.

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise see MQConnection.PeekID() for result codes.

See Also:

MQConnection.Retrieve(QueueHandle,boolean,int,QueueMessage), Enqueue(QueueMessage)

PeekCursor

public int PeekCursor(boolean retrievebody,
                      CursorHandle cursorID,
                      QueueMessage msg)

Retrieves the message pointed to by cursorID. The results are placed in the object msg. The message retrieved is not removed from the queue and is available for reading by other queue readers.

Note: Retrieved messages are removed from the queue.

Parameters:

retrievebody - A flag indicating whether the body of the message should be retrieved

cursorID - The cursor indicating the current position in the queue to be read from

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise see MQConnection.PeekCursor() for result codes.

See Also:

MQConnection.Retrieve(QueueHandle,boolean,int,QueueMessage)

OpenCursor

public int OpenCursor(CursorHandle cursorID)

Opens a cursor for sequential reading of the queue. The newly opened cursor points to the oldest, highest priority message in the queue.

Cursors may be used to violate the priority FIFO nature of the queue by scanning the queue and only retrieving messages which meet the criteria of the reader. Cursor access is sequential when used in conjunction with AdvanceCursor(CursorHandle), however specific messages may be sought out by a call to SeekID(UUID,int,CursorHandle).

Parameters:

cursorID - A previously allocated reference to a CursorHandle which will receive the reference to the cursor.

Returns:

Safmq.EC_NOERROR upon success, otherwise see MQConnection.OpenCursor(QueueHandle,CursorHandle) for error codes.

See Also:

MQConnection.OpenCursor(QueueHandle,CursorHandle)

CloseCursor

public int CloseCursor(CursorHandle cursorID)

Closes a cursor when it is no longer needed to access the queue. The cursor is invalidated after a call to CloseCursor() and should not be used again.

Parameters:

cursorID - The cursor to be closed.

Returns:

Safmq.EC_NOERROR upon success, otherwise see MQConnection.CloseCursor(QueueHandle,CursorHandle) for error codes.

See Also:

MQConnection.CloseCursor(QueueHandle,CursorHandle)

AdvanceCursor

public int AdvanceCursor(CursorHandle cursorID)

Advances the cursor to the next message in the queue.

Parameters:

cursorID - The cursor to be advanced.

Returns:

Safmq.EC_NOERROR upon success, otherwise see MQConnection.AdvanceCursor(QueueHandle,CursorHandle) for error codes.

See Also:

MQConnection.AdvanceCursor(QueueHandle,CursorHandle)

SeekID

public int SeekID(UUID id,
                  int timeout,
                  CursorHandle cursorID)

Attempts to locate the messaged indicated by id. If the message is successfully located, the cursor will point to the message identified and the message may be retrieved there after.

Parameters:

id - The receipt UUID of the message to be located

timeout - The maximum number of seconds the call should be allowed before resulting in a "timeout".

cursorID - The cursor which should be be assigned the position of the message indicated by id

Returns:

Safmq.EC_NOERROR upon success, otherwise see MQConnection.SeekID(QueueHandle,UUID,int,CursorHandle) for error codes.

See Also:

MQConnection.SeekID(QueueHandle,UUID,int,CursorHandle)

TestCursor

public int TestCursor(CursorHandle cursorID)

Determines whether the cursor indicated by cursorID is still a valid cursor, and has not been invalidated by other queue readers.

Parameters:

cursorID - The cursor which should be be evaluated

Returns:

Safmq.EC_NOERROR upon success, otherwise see MQConnection.TestCursor(QueueHandle,CursorHandle) for error codes.

See Also:

MQConnection.TestCursor(QueueHandle,CursorHandle)

getConnection

public MQConnection getConnection()