com.pcbsys.nirvana.client.nQueue Class Reference

This class provides a Queue mechanism. More...

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

Public Member Functions

void addConnectionListener (nChannelConnectionListener listener) throws nSessionPausedException, nUnexpectedResponseException, nIllegalArgumentException, nRequestTimedOutException, nSessionNotConnectedException
 Adds a nChannelConnectionListener to this queue so that when new connections are made to this queue the listener is notified. More...
 
nQueueAsyncReader createAsyncReader (final nQueueReaderContext context) throws nIllegalArgumentException, nSecurityException
 Creates an Asynchronous queue reader. More...
 
nQueueAsyncReader createAsyncReaderPrevious (final nQueueReaderContext context) throws nIllegalArgumentException, nSecurityException
 Creates an Asynchronous queue reader. More...
 
nQueueAsyncTransactionReader createAsyncTransactionalReader (final nQueueReaderContext context) throws nIllegalArgumentException, nSecurityException
 Creates an Asynchronous Transactional queue reader. More...
 
nQueueAsyncTransactionReader createAsyncTransactionalReaderPrevious (final nQueueReaderContext context) throws nIllegalArgumentException, nSecurityException
 Creates an Asynchronous Transactional queue reader. More...
 
nQueueSyncFragmentReader createFragmentReader (final nQueueReaderContext context) throws nIllegalArgumentException
 Creates a Synchronous queue reader that supports fragmented events. More...
 
nQueueSyncReader createReader (final nQueueReaderContext context) throws nIllegalArgumentException
 Creates a Synchronous queue reader. More...
 
nQueueSyncTransactionFragmentReader createTransactionalFragmentReader (final nQueueReaderContext context) throws nIllegalArgumentException
 Creates a Synchronous Transaction queue reader that supports fragmented events. More...
 
nQueueSyncTransactionReader createTransactionalReader (final nQueueReaderContext context) throws nIllegalArgumentException
 Creates a Synchronous Transaction queue reader. More...
 
nQueueDetails getDetails () throws nSecurityException, nChannelNotFoundException, nSessionNotConnectedException, nSessionPausedException,nRequestTimedOutException, nUnexpectedResponseException
 This method returns the current queue details. More...
 
String getName ()
 Gets the name of this queue. More...
 
com.pcbsys.nirvana.client.nChannelAttributes getQueueAttributes ()
 This method will return the nChannelAttributes associated with the nQueue object. More...
 
void purge () throws nSecurityException, nChannelNotFoundException, nSessionNotConnectedException, nSessionPausedException,nRequestTimedOutException, nUnexpectedResponseException
 Deletes all undelivered events from the queue. More...
 
void purge (String selector) throws nSecurityException, nChannelNotFoundException, nSessionNotConnectedException, nSessionPausedException,nRequestTimedOutException, nUnexpectedResponseException
 Deletes all undelivered events from the queue. More...
 
void purgeEventsAsync () throws nSecurityException, nChannelNotFoundException, nSessionNotConnectedException, nSessionPausedException,nRequestTimedOutException, nUnexpectedResponseException
 Deletes all undelivered events from the queue and does not wait for the response from the server. More...
 
void purgeEventsAsync (String selector) throws nSecurityException, nChannelNotFoundException, nSessionNotConnectedException, nSessionPausedException,nRequestTimedOutException, nUnexpectedResponseException
 Deletes all undelivered events matching the selector from the queue and does not wait for the response from the server. More...
 
long push (final nConsumeEvent e) throws nIllegalArgumentException, nSessionPausedException,nSecurityException, nRequestTimedOutException, nSessionNotConnectedException
 Pushes an event on to the queue. More...
 
void push (String tag, Document adom) throws nSessionNotConnectedException, nSessionPausedException,nIllegalArgumentException, nSecurityException
 Publishes the specified XML DOM document to this queue with the specified tag. More...
 
void push (String tag, Document adom, nMessageSigner signer) throws nSessionNotConnectedException, nSessionPausedException,nIllegalArgumentException, nSecurityException
 Publishes the specified XML DOM document to this queue with the specified tag. More...
 
long push (final nConsumeEvent e, final nMessageSigner signer) throws nIllegalArgumentException, nSessionPausedException,nSecurityException, nRequestTimedOutException, nSessionNotConnectedException
 Pushes an event on to the queue. More...
 
void removeConnectionListener (nChannelConnectionListener listener) throws nSessionPausedException, nUnexpectedResponseException, nRequestTimedOutException, nSessionNotConnectedException
 Removes the connection listener to this queue. More...
 
int size ()
 Returns the number of events waiting in the queue. More...
 
- Public Member Functions inherited from com.pcbsys.nirvana.client.nAbstractChannel
int getQueueSize ()
 Returns the size of the underlying event queue waiting for delivery via the go method. More...
 
nSession getSession ()
 Returns the nSession used to create/find this channel. More...
 
void updateProtobufDefinitions (byte[][] descriptors) throws nIllegalArgumentException, nSessionNotConnectedException, nRequestTimedOutException, nSessionPausedException
 Update the Protocol Buffer definition for the store. More...
 

Static Public Member Functions

static void destroyReader (final nQueueReader reader) throws nUnexpectedResponseException, nSessionPausedException,nSessionNotConnectedException, nRequestTimedOutException
 This call will release any outstanding resources on the server and close the reader. More...
 
static void destroyReaderLocally (final nQueueReader reader) throws nUnexpectedResponseException, nSessionNotConnectedException, nRequestTimedOutException
 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. More...
 

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

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

Parameters
listenerto add
Exceptions
nRequestTimedOutExceptionif the request exceeded the timeout value
nSessionNotConnectedExceptionThe session is not currently connected to the server
nUnexpectedResponseExceptionReceived a response from the server for which we can not deal with, see the message for further information
nIllegalArgumentExceptionPassed am illegal argument. This means the value passed is outside expected limits, or has already been set.
nSessionPausedExceptionThe session is currently paused, please resume
nQueueAsyncReader com.pcbsys.nirvana.client.nQueue.createAsyncReader ( final nQueueReaderContext  context) throws nIllegalArgumentException, nSecurityException

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
contextcontains the readers context to be used during construction of the reader
Returns
nQueueAsyncReader
Exceptions
nIllegalArgumentExceptionif context is null or has no event listener, already subscribed, or some non specified error is found
nSecurityExceptionif the subject does not have the correct permissions
nQueueAsyncReader com.pcbsys.nirvana.client.nQueue.createAsyncReaderPrevious ( final nQueueReaderContext  context) throws nIllegalArgumentException, nSecurityException

Creates an Asynchronous queue reader.

This is identical to createAsyncReader() except that it will remove and add the reader anew, if they were already subscribed.

Returns
nQueueAsyncReader
Exceptions
nIllegalArgumentExceptionifthe context is null or has no event listener, or some non specified error is found
nSecurityExceptionif the subject does not have the correct permissions
nQueueAsyncTransactionReader com.pcbsys.nirvana.client.nQueue.createAsyncTransactionalReader ( final nQueueReaderContext  context) throws nIllegalArgumentException, nSecurityException

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
contextcontains the readers context to be used during construction of the reader
Returns
nQueueAsyncTransactionReader
Exceptions
nIllegalArgumentExceptionif context is null or has no event listener, already subscribed, or some non specified error is found
nSecurityExceptionif the subject does not have the correct permissions
nQueueAsyncTransactionReader com.pcbsys.nirvana.client.nQueue.createAsyncTransactionalReaderPrevious ( final nQueueReaderContext  context) throws nIllegalArgumentException, nSecurityException

Creates an Asynchronous Transactional queue reader.

This is identical to createAsyncTransactional Reader() except that it will remove and add the reader anew, if they were already subscribed.

Returns
nQueueAsyncReader
Exceptions
nIllegalArgumentExceptionif context is null or has no event listener, or some non specified error is found
nSecurityExceptionif the subject does not have the correct permissions
nQueueSyncFragmentReader com.pcbsys.nirvana.client.nQueue.createFragmentReader ( final nQueueReaderContext  context) throws nIllegalArgumentException

Creates a Synchronous queue reader that supports fragmented events.

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. The only difference with the nQueueSyncReader is that the pop() method here will only return an event after all fragments have been received.

Parameters
contextcontains the readers context to be used during construction of the reader
Returns
nQueueSyncFragmentedReader
Exceptions
nIllegalArgumentExceptionif the context is null
nQueueSyncReader com.pcbsys.nirvana.client.nQueue.createReader ( final nQueueReaderContext  context) throws nIllegalArgumentException

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
contextcontains the readers context to be used during construction of the reader
Returns
nQueueSyncReader
Exceptions
nIllegalArgumentExceptionif the context is null
nQueueSyncTransactionFragmentReader com.pcbsys.nirvana.client.nQueue.createTransactionalFragmentReader ( final nQueueReaderContext  context) throws nIllegalArgumentException

Creates a Synchronous Transaction queue reader that supports fragmented events.

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. The only difference with the nQueueSyncTransactionReader is that the pop() method here will only return an event after all fragments have been received.

Parameters
contextcontains the readers context to be used during construction of the reader
Returns
nQueueSyncTransactionReader
Exceptions
nIllegalArgumentExceptionif the context is null
nQueueSyncTransactionReader com.pcbsys.nirvana.client.nQueue.createTransactionalReader ( final nQueueReaderContext  context) throws nIllegalArgumentException

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
contextcontains the readers context to be used during construction of the reader
Returns
nQueueSyncTransactionReader
Exceptions
nIllegalArgumentExceptionif the context is null
static void com.pcbsys.nirvana.client.nQueue.destroyReader ( final nQueueReader  reader) throws nUnexpectedResponseException, nSessionPausedException,nSessionNotConnectedException, nRequestTimedOutException
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
readerThe reader to close
Exceptions
nUnexpectedResponseExceptionif the server returns a response that was not expected
nSessionNotConnectedExceptionif the session is currently not connected to the server
nRequestTimedOutExceptionif the request did not receive a response within the timeout period
nSessionPausedExceptionThe session is currently paused
static void com.pcbsys.nirvana.client.nQueue.destroyReaderLocally ( final nQueueReader  reader) throws nUnexpectedResponseException, nSessionNotConnectedException, nRequestTimedOutException
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
readerThe reader to close
Exceptions
nUnexpectedResponseExceptionif the server returns a response that was not expected
nSessionNotConnectedExceptionif the session is currently not connected to the server
nRequestTimedOutExceptionif the request did not receive a response within the timeout period

This method returns the current queue details.

Returns
nQueueDetails to be examined
Exceptions
nSecurityExceptionClient is not authorized to perform the request
nChannelNotFoundExceptionThe Queue does not exist
nSessionNotConnectedExceptionClient is not currently connected to the server
nRequestTimedOutExceptionThe server did not respond within the client timeout
nUnexpectedResponseExceptionThe server responded with an unknown response
nSessionPausedExceptionThe session is currently paused
String com.pcbsys.nirvana.client.nQueue.getName ( )

Gets the name of this queue.

Returns
a string specifying the name of this channel
com.pcbsys.nirvana.client.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

Deletes all undelivered events from the queue.

Exceptions
nSecurityExceptionThe client is not authorized to perform this task
nChannelNotFoundExceptionThe Queue could not be found
nSessionNotConnectedExceptionClient is not currently connected to the server
nRequestTimedOutExceptionThe server did not respond within the timeout
nUnexpectedResponseExceptionThe server responded with an unknown response
nSessionPausedExceptionThe session is currently paused

Deletes all undelivered events from the queue.

Parameters
selectorPurges all events which match this filter
Exceptions
nSecurityExceptionThe client is not authorized to perform this task
nChannelNotFoundExceptionThe Queue could not be found
nSessionNotConnectedExceptionClient is not currently connected to the server
nRequestTimedOutExceptionThe server did not respond within the timeout
nUnexpectedResponseExceptionThe server responded with an unknown response
nSessionPausedExceptionThe session is currently paused

Deletes all undelivered events from the queue and does not wait for the response from the server.

Exceptions
nSecurityExceptionThe client is not authorized to perform this task
nChannelNotFoundExceptionThe Queue could not be found
nSessionNotConnectedExceptionClient is not currently connected to the server
nRequestTimedOutExceptionThe server did not respond within the timeout
nUnexpectedResponseExceptionThe server responded with an unknown response
nSessionPausedExceptionThe session is currently paused

Deletes all undelivered events matching the selector from the queue and does not wait for the response from the server.

Parameters
selectorPurges all events which match this filter
Exceptions
nSecurityExceptionThe client is not authorized to perform this task
nChannelNotFoundExceptionThe Queue could not be found
nSessionNotConnectedExceptionClient is not currently connected to the server
nRequestTimedOutExceptionThe server did not respond within the timeout
nUnexpectedResponseExceptionThe server responded with an unknown response
nSessionPausedExceptionThe session is currently paused

Pushes an event on to the queue.

Parameters
enConsumeEvent to push
Returns
an unique ID for the event on the queue
Exceptions
nIllegalArgumentExceptionIf the event is null
nSecurityExceptionIf your not authorized to publish to the queue
nRequestTimedOutExceptionIf the server failed to responsed
nSessionNotConnectedExceptionClient is not currently connected to the server
nSessionPausedExceptionThe session is currently paused
void com.pcbsys.nirvana.client.nQueue.push ( String  tag,
Document  adom 
) throws nSessionNotConnectedException, nSessionPausedException,nIllegalArgumentException, nSecurityException

Publishes the specified XML DOM document to this queue with the specified tag.

Parameters
taga string specifying the event tag to be used
adoman XML DOM document object specifying the XML document to be published to this queue
Exceptions
nSecurityExceptionis thrown if the caller has insufficient permissions
nSessionNotConnectedExceptionThe session is not currently connected to the server
nIllegalArgumentExceptionPassed am illegal argument. This means the value passed is outside expected limits
nSessionPausedExceptionThe session is currently paused
void com.pcbsys.nirvana.client.nQueue.push ( String  tag,
Document  adom,
nMessageSigner  signer 
) throws nSessionNotConnectedException, nSessionPausedException,nIllegalArgumentException, nSecurityException

Publishes the specified XML DOM document to this queue with the specified tag.

Parameters
taga string specifying the event tag to be used
adoman XML DOM document object specifying the XML document to be published to this queue
signerEvent Signer class to use to sign the event
Exceptions
nSecurityExceptionis thrown if the caller has insufficient permissions
nSessionNotConnectedExceptionThe session is not currently connected to the server
nIllegalArgumentExceptionPassed am illegal argument. This means the value passed is outside expected limits
nSessionPausedExceptionThe session is currently paused

Pushes an event on to the queue.

Parameters
enConsumeEvent to push
signerThis object will be used to sign the event prior to it being placed on to the queue
Returns
an unique ID for the event on the queue
Exceptions
nIllegalArgumentExceptionIf the event is null
nSecurityExceptionIf your not authorized to publish to the queue
nRequestTimedOutExceptionIf the server failed to respond
nSessionNotConnectedExceptionClient is not currently connected to the server
nSessionPausedExceptionThe session is currently paused
void com.pcbsys.nirvana.client.nQueue.removeConnectionListener ( nChannelConnectionListener  listener) throws nSessionPausedException, nUnexpectedResponseException, nRequestTimedOutException, nSessionNotConnectedException

Removes the connection listener to this queue.

Parameters
listenerremove the listener
Exceptions
nRequestTimedOutExceptionif the request exceeded the timeout value
nSessionNotConnectedExceptionThe session is not currently connected to the server
nUnexpectedResponseExceptionReceived a response from the server for which we can not deal with, see the message for further information
nSessionPausedExceptionThe 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