com.pcbsys.nirvana.client.nQueue Class Reference

This class provides a Queue mechanism. More...

#include <nQueue.h>

Inheritance diagram for com.pcbsys.nirvana.client.nQueue:

com.pcbsys.nirvana.client.nAbstractChannel

Public Member Functions

void addConnectionListener (nChannelConnectionListener *pListener)
 Adds a nChannelConnectionListener to this queue so that when new connections are made to this queue the listener is notified.
nQueueAsyncReader * createAsyncReader (nQueueReaderContext *pContext)
 Creates an Asynchronous queue reader.
nQueueAsyncTransactionReader * createAsyncTransactionalReader (nQueueReaderContext *pContext)
 Creates an Asynchronous Transactional queue reader.
nQueueSyncReader * createReader (nQueueReaderContext *pContext)
 Creates a Synchronous queue reader.
nQueueSyncTransactionReader * createTransactionalReader (nQueueReaderContext *pContext)
 Creates a Synchronous Transaction queue reader.
nQueueDetails * getDetails ()
 This method returns the current queue details.
std::string getName ()
 Gets the name of this queue.
nChannelAttributes * getQueueAttributes ()
 This method will return the nChannelAttributes associated with the nQueue object.
void purge ()
 Deletes all undelivered events from the queue.
void purge (std::string &selector)
 Deletes all undelivered events from the queue.
long push (nConsumeEvent *pEvent)
 Pushes an event on to the queue.
void removeConnectionListener (nChannelConnectionListener *pListener)
 Removes the connection listener to this queue.
int size ()
 Returns the number of events waiting in the queue.

Static Public Member Functions

static void destroyReader (nQueueReader *pReader)
 This call will release any outstanding resources on the server and close the reader.
static void destroyReaderLocally (nQueueReader *pReader)
 This call will close local reader resources but remain subscribed at the server Any future calls to this object will work unless destroyReader() is called.

Detailed Description

This class provides a Queue mechanism.

It allows for multiple users to pop events from the queue and multiple users to push events on to the queue.

However, a queue differs from a channel in that an event can only be popped by one user. This means that an event is only delivered to one client. While a channel it is delivered to all users who are subscribed.

The queue also offers a peek method. This method uses a window over the queue so that the entire queue does not need to be sent in one hit.

Four different Queue reading models are supported, these are

Synchronous Here the client will call pop() whenever the client wants to retrieve an event from the server. The server will automatically acknowledge that the client has received this event.
Synchronous Transactional This is similar in operation to the Synchronous model, except the server does not auto acknowledge the events, this enables the client to perform commit() or rollback() operations.
Asynchronous In this model the server will record that the client is interested in events from this queue and will maintain an outstanding pop() and as events are received on the queue they are automatically delivered to the client via a callback. The events are auto acknowledged on the server once they have been delivered to the client.
Asynchronous Transactional This is similar in operation to the Asynchronous model, except the server does not auto acknowledge the events, this enables the client to perform commit() or rollback() operations. The server will stop delivering events to this client once the WindowSize has been reached, the client will need to call either commit() or rollback() before events are delivered again.

In both transactional models, when a rollback() is called any events sent since the last commit() or rollback() will be redelivered to all registered clients. This means the client may not receive these events again, but rather, they are redistributed amongst the current clients.

Member Function Documentation

void com.pcbsys.nirvana.client.nQueue.addConnectionListener ( nChannelConnectionListener *  pListener  ) 

Adds a nChannelConnectionListener to this queue so that when new connections are made to this queue the listener is notified.

Parameters:
*pListener to add
Exceptions:
nRequestTimedOutException if the request exceeded the timeout value
nSessionNotConnectedException The session is not currently connected to the server
nUnexpectedResponseException Received a response from the server for which we can not deal with, see the message for further information
nIllegalArgumentException Passed am illegal argument. This means the value passed is outside expected limits, or has already been set.
nSessionPausedException The session is currently paused, please resume

nQueueAsyncReader* com.pcbsys.nirvana.client.nQueue.createAsyncReader ( nQueueReaderContext *  pContext  ) 

Creates an Asynchronous queue reader.

In this model the server will record that the client is interested in events from this queue and will maintain an outstanding pop() and as events are received on the queue they are automatically delivered to the client via a callback. The events are auto acknowledged on the server once they have been delivered to the client.

Parameters:
*pContext contains the readers context to be used during construction of the reader
Returns:
nQueueAsyncReader
Exceptions:
nIllegalArgumentException if the context is null
nSecurityException if the subject does not have the correct permissions

nQueueAsyncTransactionReader* com.pcbsys.nirvana.client.nQueue.createAsyncTransactionalReader ( nQueueReaderContext *  pContext  ) 

Creates an Asynchronous Transactional queue reader.

This is similar in operation to the Asynchronous model, except the server does not auto acknowledge the events, this enables the client to perform commit() or rollback() operations. The server will stop delivering events to this client once the WindowSize has been reached, the client will need to call either commit() or rollback() before events are delivered again.

Parameters:
*pContext contains the readers context to be used during construction of the reader
Returns:
nQueueAsyncTransactionReader
Exceptions:
nIllegalArgumentException if the context is null
nSecurityException if the subject does not have the correct permissions

nQueueSyncReader* com.pcbsys.nirvana.client.nQueue.createReader ( nQueueReaderContext *  pContext  ) 

Creates a Synchronous queue reader.

Here the client will call pop() whenever the client wants to retrieve an event from the server. The server will automatically acknowledge that the client has received this event.

Parameters:
*pContext contains the readers context to be used during construction of the reader
Returns:
nQueueSyncReader
Exceptions:
nIllegalArgumentException if the context is null

nQueueSyncTransactionReader* com.pcbsys.nirvana.client.nQueue.createTransactionalReader ( nQueueReaderContext *  pContext  ) 

Creates a Synchronous Transaction queue reader.

This is similar in operation to the Synchronous model, except the server does not auto acknowledge the events, this enables the client to perform commit() or rollback() operations.

Parameters:
*pContext contains the readers context to be used during construction of the reader
Returns:
nQueueSyncTransactionReader
Exceptions:
nIllegalArgumentException if the context is null

static void com.pcbsys.nirvana.client.nQueue.destroyReader ( nQueueReader *  pReader  )  [static]

This call will release any outstanding resources on the server and close the reader.

Any future calls to this object will result in an nIllegalStateException being raised.

Parameters:
*pReader The reader to close
Exceptions:
nUnexpectedResponseException if the server returns a response that was not expected
nSessionNotConnectedException if the session is currently not connected to the server
nRequestTimedOutException if the request did not receive a response within the timeout period
nSessionPausedException The session is currently paused

static void com.pcbsys.nirvana.client.nQueue.destroyReaderLocally ( nQueueReader *  pReader  )  [static]

This call will close local reader resources but remain subscribed at the server Any future calls to this object will work unless destroyReader() is called.

Parameters:
*pReader The reader to close
Exceptions:
nUnexpectedResponseException if the server returns a response that was not expected
nSessionNotConnectedException if the session is currently not connected to the server
nRequestTimedOutException if the request did not receive a response within the timeout period

nQueueDetails* com.pcbsys.nirvana.client.nQueue.getDetails (  ) 

This method returns the current queue details.

Returns:
nQueueDetails to be examined
Exceptions:
nSecurityException Client is not authorized to perform the request
nChannelNotFoundException The Queue does not exist
nSessionNotConnectedException Client is not currently connected to the server
nRequestTimedOutException The server did not respond within the client timeout
nUnexpectedResponseException The server responded with an unknown response
nSessionPausedException The session is currently paused

std::string com.pcbsys.nirvana.client.nQueue.getName (  ) 

Gets the name of this queue.

Returns:
a string specifying the name of this channel

nChannelAttributes* com.pcbsys.nirvana.client.nQueue.getQueueAttributes (  ) 

This method will return the nChannelAttributes associated with the nQueue object.

Returns:
the nChannelAttributes for the nQueue object

void com.pcbsys.nirvana.client.nQueue.purge (  ) 

Deletes all undelivered events from the queue.

Exceptions:
nSecurityException The client is not authorized to perform this task
nChannelNotFoundException The Queue could not be found
nSessionNotConnectedException Client is not currently connected to the server
nRequestTimedOutException The server did not respond within the timeout
nUnexpectedResponseException The server responded with an unknown response
nSessionPausedException The session is currently paused

void com.pcbsys.nirvana.client.nQueue.purge ( std::string &  selector  ) 

Deletes all undelivered events from the queue.

Parameters:
selector Purges all events which match this filter
Exceptions:
nSecurityException The client is not authorized to perform this task
nChannelNotFoundException The Queue could not be found
nSessionNotConnectedException Client is not currently connected to the server
nRequestTimedOutException The server did not respond within the timeout
nUnexpectedResponseException The server responded with an unknown response
nSessionPausedException The session is currently paused

long com.pcbsys.nirvana.client.nQueue.push ( nConsumeEvent *  pEvent  ) 

Pushes an event on to the queue.

Parameters:
*pEvent nConsumeEvent to push
Returns:
an unique ID for the event on the queue
Exceptions:
nIllegalArgumentException If the event is null
nSecurityException If your not authorized to publish to the queue
nRequestTimedOutException If the server failed to respond
nSessionNotConnectedException Client is not currently connected to the server
nSessionPausedException The session is currently paused

void com.pcbsys.nirvana.client.nQueue.removeConnectionListener ( nChannelConnectionListener *  pListener  ) 

Removes the connection listener to this queue.

Parameters:
*pListener remove the listener
Exceptions:
nRequestTimedOutException if the request exceeded the timeout value
nSessionNotConnectedException The session is not currently connected to the server
nUnexpectedResponseException Received a response from the server for which we can not deal with, see the message for further information
nSessionPausedException The session is currently paused, please resume

int com.pcbsys.nirvana.client.nQueue.size (  ) 

Returns the number of events waiting in the queue.

Returns:
int size of the queue