Universal Messaging JavaScript API

function createSession( config )

Creates and initializes (but does not start) a session object for communication with a Universal Messaging Realm Server.

Optional Parameter

Configuration Object Keys (Optional)

Returns

An object representing a Universal Messaging session.

Example Usage

var session = Nirvana.createSession();
session.start();
session.stop();

A session can be customized by passing in a configuration object containing keys which override default values, as follows:

var session = Nirvana.createSession({
  realms : [ "https://showcase.um.softwareag.com:443" ],
  debugLevel : 4
});

See Also

Session.start()

function createEvent()

Factory method to create a new, empty Universal Messaging Event (typically for subsequent publishing to a resource such as a Channel or Queue).

Returns

A new, empty Event.

Example Usage

var myEvent = Nirvana.createEvent();
var myDict = myEvent.getDictionary();
myDict.putString("message", "Hello World");
myChannel.publish(myEvent);

See Also

Event, Event.getDictionary()

function createDictionary()

Factory method to create a new, empty EventDictionary (typically for subsequent addition to an existing EventDictionary using EventDictionary.putDictionary()).

Returns

A new, empty EventDictionary.

Example Usage

var myEvent = Nirvana.createEvent();
var myDict = myEvent.getDictionary();
var newDict = Nirvana.createDictionary();
newDict.putString("message", "Hello World");
myDict.putDictionary("aNestedDictionary", newDict);
myChannel.publish(myEvent);

See Also

EventDictionary.putDictionary()

function on( observable, listener )

Registers a single event listener on the Nirvana object for observable events of the specified type (see Nirvana.Observe for a list of applicable observables).

To register more than one observable listener for the same type, invoke on() with a different listener function as many times as needed.

Parameters

Returns

The Nirvana object (making this a chainable method).

Example Usage

function myErrorHandler(session, exception) {
  // This will receive errors such as total transport driver failures
}
Nirvana.on(Nirvana.Observe.ERROR, myErrorHandler);

// we can now also un-assign this listener any time we want to:
Nirvana.removeListener(Nirvana.Observe.ERROR, myErrorHandler);

See Also

Nirvana.removeListener(), Nirvana.Observe

function removeListener( observable, listener )

Removes a specific listener for observable events of the specified type (see Nirvana.Observe for a list of applicable observables).

Parameters

Returns

The Nirvana object (making this a chainable method).

Example Usage

Nirvana.removeListener(Nirvana.Observe.ERROR, myErrorHandler);

Notice that a reference to the listener is required if you wish to remove it.  See the note about named and anonymous functions in the Nirvana.Observe Example Usage section.

See Also

Nirvana.on(), Nirvana.Observe

this.start = function ()

Starts the Session.  This will launch the first preferred transport driver and attempt to contact the first preferred realm to initialize a session.  If the Session initializes successfully as a result of this call to Session.start(), then any listeners of the Nirvana.Observe.START observable event will be invoked with the new session as a parameter.

Note that there is no requirement that the developer wait for the Nirvana.Observe.START observable event to fire before attempting to interact with the Session; any such interactions will be transparently queued until the session has successfully initialized.

Returns

The Session object on which Session.start() was invoked (making this a chainable method).

Example Usage

Starting a Session can be very simple:

var mySession = Nirvana.createSession();
mySession.start();

Sessions support arbitrary orders of interaction (transparently queueing commands until realm server communication is possible).  It is possible to start a session and subscribe to a channel as follows:

var mySession = Nirvana.createSession();
mySession.start();
mySession.subscribe(mySession.getChannel("/some/channel"));

The placement of the Session.start() call is flexible.  The following would work just as well, for instance:

var mySession = Nirvana.createSession();
mySession.subscribe(mySession.getChannel("/some/channel"));
mySession.start();

Client code can be asynchronously notified of the actual session initialization.  To do this, simply assign a listener to the Session’s Nirvana.Observe.START observable event:

function sessionStarted(s) {
  console.log("Session started with ID " + s.getSessionID());
}
mySession.on(Nirvana.Observe.START, sessionStarted);
mySession.start();

See Also

Nirvana.Observe, Nirvana.createSession()

this.stop = function ( forceClose )

Stops the Session.  This will close the connection with the realm server, and set the Session’s status to STOPPED.

Returns

The Session object on which Session.stop() was invoked (making this a chainable method).

Example Usage

mySession.stop();

If a developer wishes to be asynchronously notified when the session has stopped, they can assign a listener to the Session’s Nirvana.Observe.STOP observable event.

function sessionStopped(session) {
  console.log("Session " + session.getSessionID() + " explicitly stopped");
}
mySession.on(Nirvana.Observe.STOP, sessionStopped);
mySession.stop();

See Also

Nirvana.Observe

this.subscribe = function ( resourceArray )

Batch-subscribes to multiple Channel, Queue and/or TransactionalQueue resources with a single call to the server.

If attempting to subscribe to more than one resource at a time, this is considerably more efficient than using the resource-level subscription methods such as Channel.subscribe().

This method may be used in place of resource-level subscription methods such as Channel.subscribe() even if intending to subscribe only to a single resource; either approach is a matter of developer preference.

Each successful subscription or failure will fire an observable event both on the respective Channel, Queue, and/or TransactionalQueue resource object, and on the Session.

Parameters

Returns

The Session object on which Session.subscribe() was invoked (making this a chainable method).

Example Usage

var myChannel = mySession.getChannel("/some/channel");
var myChannel2 = mySession.getChannel("/some/other/channel");
var myQueue = mySession.getQueue("/some/queue");
mySession.subscribe([myChannel, myChannel2, myQueue]);

If a developer wishes to be asynchronously notified when a resource subscription is successful (or if a subscription error occurs), they can assign appropriate listeners to the respective resource, as shown below:

function subscriptionCompleteHandler(resource) {
  // subscription to this resource was successful
}

function errorHandler(resource, ex) {
   if (ex instanceof MissingResourceException) {
       console.log("Resource " + resource.getName() + " not found: " + ex.message);
   }
   else if (ex instanceof AlreadySubscribedException) {
       console.log("Already subscribed to " + resource.getName());
   }
   else if (ex instanceof SecurityException) {
       console.log("ACL error for " + resource.getName() + ": " + ex.message);
   }
}

function eventHandler(evt) {
   console.log("Received event from: " + evt.getResourceName());
}

myChannel.on(Nirvana.Observe.SUBSCRIBE, subscriptionCompleteHandler);
myChannel.on(Nirvana.Observe.ERROR, errorHandler);
myChannel.on(Nirvana.Observe.DATA, eventHandler);
mySession.subscribe([myChannel, myChannel2, myQueue]);

See Also

Nirvana.Observe, Channel.subscribe(), Queue.subscribe(), TransactionalQueue.subscribe()

this.getChannel = function ( channelName )

Returns the Channel object for the supplied channel name.  Note that a valid object will be returned irrespective of whether this resource actually exists on the realm server.

Parameters

Returns

A Channel object for the supplied channel name.

Example Usage

var myChannel = mySession.getChannel("/some/channel");

this.getQueue = function ( queueName, isTransactionalReader )

Returns the Queue or TransactionalQueue object for the supplied queue name.  If the optional second parameter is not supplied (or has a false value), then a Queue is returned.  If the value of the second parameter is true, then a TransactionalQueue is returned.  Note that a valid object will be returned irrespective of whether this resource actually exists on the realm server.

Parameters

Returns

A Queue or TransactionalQueue object for the supplied queue name.

Example Usage

var myQueue = mySession.getQueue("/some/queue");

this.on = function ( observable, listener )

Registers a single event listener on the Session for observable events of the specified type (see Nirvana.Observe for a list of applicable observables).

To register more than one observable listener for the same type, invoke on() with a different listener function as many times as needed.

Parameters

Returns

The Session object on which Session.on() was invoked (making this a chainable method).

Example Usage

function myHandler(evt) {
  // do something with the evt passed to us as a parameter
}
session.on(Nirvana.Observe.DATA, myHandler);

// we can now also un-assign this listener any time we want to:
session.removeListener(Nirvana.Observe.DATA, myHandler);

See Also

Session.removeListener(), Nirvana.Observe

this.removeListener = function ( observable, listener )

Removes a specific listener for observable events of the specified type (see Nirvana.Observe for a list of applicable observables).

Parameters

Returns

The Session object on which Session.removeListener() was invoked (making this a chainable method).

Example Usage

session.removeListener(Nirvana.Observe.DATA, myHandler);

Notice that a reference to the listener is required if you wish to remove it.  See the note about named and anonymous functions in the Nirvana.Observe Example Usage section.

See Also

Session.on(), Nirvana.Observe

this.getUsername = function ()

Returns the username used in this Session.  A username can be optionally set when invoking Nirvana.createSession() with a suitable configuration object parameter.

Returns

The Session’s username.

Example Usage

var username = mySession.getUsername();

See Also

Nirvana.createSession()

this.getCurrentDriver = function ()

Returns the name of the Session’s current transport driver.  This will be one of the names defined in Nirvana.Driver, and, if the call to Nirvana.createSession() included a configuration object parameter with a “drivers” key, will be restricted to one of the user-specified drivers.

Returns

The name of the Session’s current transport driver.

Example Usage

var driverName = mySession.getCurrentDriver();

See Also

Nirvana.Driver, Nirvana.createSession()

this.getCurrentRealm = function ()

Returns the RNAME (in protocol://host:port format) of the realm server to which the Session is currently connected.  This will be one of the RNAMEs defined in the realms value in the configuration object passed into Nirvana.createSession(), or, if not configured, willbe derived from the protocol, host and port of the server which served the application itself.

Returns

The name of the realm to which the Session is connected.

Example Usage

var rname = mySession.getCurrentRealm();

See Also

Nirvana.createSession()

this.getSessionID = function ()

Returns the Session’s current session ID.  This will be a string, generated and assigned by the realm server after a successful session start or reconnection.

Returns

A string representing the Session’s current session ID.

Example Usage

var sessionID = mySession.getSessionID();

See Also

Session.start()

this.getDataStreamID = function ()

Returns the Session’s current DataStream ID.  This will be a string, generated and assigned by the realm server after a successful session start or reconnection IF the session was DataStream-enabled (see enableDataStreams property of session configuration object).

Returns

A string representing the Session’s current DataStream ID.

Example Usage

var dataStreamID = mySession.getDataStreamID();

See Also

Session.start()

this.getConfig = function ()

Returns the configuration object for the Session.  Its key/value pairs will be affected by any user-specified values in the optional configuration object if passed as a parameter to Nirvana.createSession().  Some such values (such as the drivers value) may have changed over time, depending on client capabilities.

Returns

The configuration object for the Session.

Example Usage

var config = mySession.getConfig();
var myRealmArray = config.realms;

See Also

Nirvana.createSession()

this.getStatus = function ()

Returns the Session’s current status, which describes whether it is, for example, not yet started, connected, disconnected, or stopped.  The actual status value is represented by of the following string constants:

Returns

A string representing the Session’s current status.

Example Usage

var status = mySession.getStatus();

this.isDataStreamEnabled = function ()

Returns true or false, depending on whether the Session was configured to be DataStream-enabled (via setting of the dataStreamEnabled key in the configuration object passed as an optional parameter to Nirvana.createSession().

Returns

A boolean value of true or false.

Example Usage

if ( mySession.isDataStreamEnabled() ) {
   console.log("This DataStream session receives events from any DataGroup of which it is a member.");
}

See Also

Nirvana.createSession()

this.subscribe = function ()

Subscribes to the Channel, and begins receiving events.

Each successful subscription or failure will fire an observable event both on the respective Channel resource object, and on the Session (see Nirvana.Observe for applicable observables).

Returns

The Channel object on which Channel.subscribe() was invoked (making this a chainable method).

Example Usage

var myChannel = mySession.getChannel("/some/channel");

function eventHandler(evt) {
   console.log("Received event from: " + evt.getResourceName());
}

myChannel.on(Nirvana.Observe.DATA, eventHandler);
myChannel.subscribe();

Additional Information

For more information on assignment of listeners for subscription success or failure and for receipt of individual events, please see Session.subscribe(), as the techniques and caveats discussed there also apply.

See Also

Nirvana.Observe

this.unsubscribe = function ()

Unsubscribes from the Channel, and stops receiving events.

A successful or failed unsubscription attempt will fire an observable event on the Channel (see Nirvana.Observe for applicable observables).

Returns

The Channel object on which Channel.unsubscribe() was invoked (making this a chainable method).

Example Usage

function unsubscribeHandler(resource) {
   console.log("Unsubscribed from: " + resource.getName());
}

myChannel.on(Nirvana.Observe.UNSUBSCRIBE, unsubscribeHandler);
myChannel.unsubscribe();

See Also

Channel.subscribe(), Session.subscribe(), Nirvana.Observe

this.isSubscribed = function ()

Returns true or false, depending on whether a subscription exists for the Channel.

Returns

A boolean value of true or false.

Example Usage

if ( !myChannel.isSubscribed() ) {
   myChannel.subscribe();
}

See Also

Channel.subscribe(), Session.subscribe()

this.publish = function ( event )

Publishes a Universal Messaging Event to the Channel.

Parameters

Returns

The Channel object on which Channel.publish() was invoked (making this a chainable method).

Example Usage

var myEvent = Nirvana.createEvent();
var myDict = myEvent.getDictionary();
myDict.putString("message", "Hello World");
myChannel.publish(myEvent);

this.createTransaction = function ()

Factory method to create a new Transaction for use on the Channel.

Returns

A new Transaction object.

Example Usage

var myTransaction = myChannel.createTransaction();

this.getStartEID = function ()

Returns the Event ID (the “EID”) from which an existing subscription to the Channel started, or from which a subsequent subscription to the Channel will start.  This defaults to 0 unless it is set with setStartEID().

Returns

An integer representing the EID from which any subscription on the Channel will start.

Example Usage

var startEID = myChannel.getStartEID();

See Also

Channel.setStartEID(), Channel.subscribe(), Channel.getFilter(), Channel.setFilter()

this.setStartEID = function ( eid )

Sets the Event ID (the “EID”) from which a subsequent subscription to the Channel shall start.  This defaults to 0 if not set explicitly.

Parameters

Returns

The Channel object on which Channel.setStartEID() was invoked (making this a chainable method).

Example Usage

var myChannel = mySession.getChannel("/some/channel");
myChannel.setStartEID(5106); // receive only events with EID 5016 or higher
myChannel.subscribe();

See Also

Channel.getStartEID(), Channel.subscribe(), Channel.getFilter(), Channel.setFilter()

this.getCurrentEID = function ()

Returns the Event ID (the “EID”) which an existing subscription to the Channel is at.  This defaults to -1 before any events are received.

Returns

An integer representing the EID which the subscription on the Channel is up to.

Example Usage

var currentEID = myChannel.getCurrentEID();

See Also

<Channel.setCurrentEID()>, Channel.subscribe(), Channel.getFilter(), Channel.setFilter()

this.getFilter = function ()

Returns the SQL-style filter applied to an existing or subsequent subscription to the Channel.  By default, no filter is used unless one is set with setFilter().

Returns

A string representing the filter applied to an existing or subsequent subscription to the Channel.

Example Usage

var filter = myChannel.getFilter();

See Also

Channel.setFilter(), Channel.subscribe(), Channel.getStartEID(), Channel.setStartEID()

this.setFilter = function ( newFilter )

Sets the SQL-style filter to be applied to a subsequent subscription to the Channel.  No filter is applied to a subscription if one is not set explicitly using this method.

Parameters

Returns

The Channel object on which Channel.setFilter() was invoked (making this a chainable method).

Example Usage

var myChannel = mySession.getChannel("/some/channel");
// receive only events matching the following filter:
myChannel.setFilter("currencypair = 'USDGBP' AND price < 0.6385");
myChannel.subscribe();

See Also

Channel.getFilter(), Channel.subscribe(), Channel.getStartEID(), Channel.setStartEID()

this.getName = function ()

Returns the Channel’s fully qualified name (e.g.  “/some/channel”).

Returns

A string representing the Channel’s fully qualified name.

Example Usage

var channelName = myChannel.getName();

See Also

Session.getChannel()

this.getResourceType = function ()

Returns the constant Nirvana.CHANNEL_RESOURCE, which identifies this resource as a Channel.

Returns

A integer constant equal to Nirvana.CHANNEL_RESOURCE.

Example Usage

if (myChannel.getResourceType() === Nirvana.CHANNEL_RESOURCE) {
   console.log("myChannel is a channel");
}

this.on = function ( observable, listener )

Registers a single event listener on the Channel for observable events of the specified type (see Nirvana.Observe for applicable observables).

Parameters

Returns

The Channel object on which Channel.on() was invoked (making this a chainable method).

Example Usage

function myHandler(evt) {
   console.log("Received event from: " + evt.getResourceName());
}
myChannel.on(Nirvana.Observe.DATA, myHandler);

Additional Information

For more information on assigning listeners for Nirvana.Observe.DATA or any other observable event, please see the Nirvana.Observe Example Usage section.

See Also

Channel.removeListener(), Nirvana.Observe

this.removeListener = function ( observable, listener )

Removes a specific listener for observable events of the specified type (see Nirvana.Observe for applicable observables).

Parameters

Returns

The Channel object on which Channel.removeListener() was invoked (making this a chainable method).

Example Usage

function myHandler(evt) {
  // do something with the evt passed to us as a parameter
}
myChannel.on(Nirvana.Observe.DATA, myHandler);

// when we want to, we can un-assign the listener:
myChannel.removeListener(Nirvana.Observe.DATA, myHandler);

Additional Information

For more information on removing listeners for Nirvana.Observe.DATA or any other observable event, please see the Nirvana.Observe Example Usage section.

See Also

Channel.on(), Nirvana.Observe

this.subscribe = function ()

Subscribes to the Queue, and begins receiving events.

Each successful subscription or failure will fire an observable event both on the respective Queue resource object, and on the Session (see Nirvana.Observe for applicable observables).

Returns

The Queue object on which Queue.subscribe() was invoked (making this a chainable method).

Example Usage

var myQueue = mySession.getChannel("/some/queue");

function eventHandler(evt) {
   console.log("Received event from: " + evt.getResourceName());
}

myQueue.on(Nirvana.Observe.DATA, eventHandler);
myQueue.subscribe();

Additional Information

For more information on assignment of listeners for subscription success or failure and for receipt of individual events, please see Session.subscribe(), as the techniques and caveats discussed there also apply.

See Also

Nirvana.Observe

this.unsubscribe = function ()

Unsubscribes from the Queue, and stops receiving events.

A successful or failed unsubscription attempt will fire an observable event on the Queue (see Nirvana.Observe for applicable observables).

Returns

The Queue object on which Queue.unsubscribe() was invoked (making this a chainable method).

Example Usage

function unsubscribeHandler(resource) {
   console.log("Unsubscribed from: " + resource.getName());
}

myQueue.on(Nirvana.Observe.UNSUBSCRIBE, unsubscribeHandler);
myQueue.unsubscribe();

See Also

Queue.subscribe(), Session.subscribe(), Nirvana.Observe

this.isSubscribed = function ()

Returns true or false, depending on whether a subscription exists for the Queue.

Returns

A boolean value of true or false.

Example Usage

if ( !myQueue.isSubscribed() ) {
   myQueue.subscribe();
}

See Also

Queue.subscribe(), Session.subscribe()

this.publish = function ( event )

Publishes a Universal Messaging Event to the Queue.

Parameters

Returns

The Queue object on which Queue.publish() was invoked (making this a chainable method).

Example Usage

var myEvent = Nirvana.createEvent();
var myDict = myEvent.getDictionary();
myDict.putString("message", "Hello World");
myQueue.publish(myEvent);

this.createTransaction = function ()

Factory method to create a new Transaction for use on the Queue.

Returns

A new Transaction object.

Example Usage

var myTransaction = myQueue.createTransaction();

this.getFilter = function ()

Returns the SQL-style filter applied to an existing or subsequent subscription to the Queue.  By default, no filter is used unless one is set with setFilter().

Returns

A string representing the filter applied to an existing or subsequent subscription to the Queue.

Example Usage

var filter = myQueue.getFilter();

See Also

Queue.setFilter(), Queue.subscribe()

this.setFilter = function ( newFilter )

Sets the SQL-style filter to be applied to a subsequent subscription to the Queue.  No filter is applied to a subscription if one is not set explicitly using this method.

Parameters

Returns

The Queue object on which Queue.setFilter() was invoked (making this a chainable method).

Example Usage

var myQueue = mySession.getQueue("/some/queue");
// receive only events matching the following filter:
myQueue.setFilter("currencypair = 'USDGBP' AND price < 0.6385");
myQueue.subscribe();

See Also

Queue.getFilter(), Queue.subscribe()

this.getName = function ()

Returns the Queue’s fully qualified name (e.g.  “/some/queue”).

Returns

A string representing the Queue’s fully qualified name.

Example Usage

var queueName = myQueue.getName();

See Also

Session.getQueue()

this.getResourceType = function ()

Returns the constant Nirvana.QUEUE_RESOURCE, which identifies this resource as a Queue.

Returns

A integer constant equal to Nirvana.QUEUE_RESOURCE.

Example Usage

if (myQueue.getResourceType() === Nirvana.QUEUE_RESOURCE) {
   console.log("myQueue is a queue");
}

this.on = function ( observable, listener )

Registers a single event listener on the Queue for observable events of the specified type (see Nirvana.Observe for applicable observables).

Parameters

Returns

The Queue object on which Queue.on() was invoked (making this a chainable method).

Example Usage

function myHandler(evt) {
   console.log("Received event from: " + evt.getResourceName());
}
myQueue.on(Nirvana.Observe.DATA, myHandler);

Additional Information

For more information on assigning listeners for Nirvana.Observe.DATA or any other observable event, please see the Nirvana.Observe Example Usage section.

See Also

Queue.removeListener(), Nirvana.Observe

this.removeListener = function ( observable, listener )

Removes a specific listener for observable events of the specified type (see Nirvana.Observe for applicable observables).

Parameters

Returns

The Queue object on which Queue.removeListener() was invoked (making this a chainable method).

Example Usage

function myHandler(evt) {
  // do something with the evt passed to us as a parameter
}
myQueue.on(Nirvana.Observe.DATA, myHandler);

// when we want to, we can un-assign the listener:
myQueue.removeListener(Nirvana.Observe.DATA, myHandler);

Additional Information

For more information on removing listeners for Nirvana.Observe.DATA or any other observable event, please see the Nirvana.Observe Example Usage section.

See Also

Queue.on(), Nirvana.Observe

this.subscribe = function ()

Subscribes to the TransactionalQueue, and begins receiving events.

Each successful subscription or failure will fire an observable event both on the respective TransactionalQueue resource object, and on the Session (see Nirvana.Observe for applicable observables).

Returns

The TransactionalQueue object on which TransactionalQueue.subscribe() was invoked (making this a chainable method).

Example Usage

var myTransactionalQueue = mySession.getChannel("/some/queue");

function eventHandler(evt) {
   console.log("Received event from: " + evt.getResourceName());
}

myTransactionalQueue.on(Nirvana.Observe.DATA, eventHandler);
myTransactionalQueue.subscribe();

Additional Information

For more information on assignment of listeners for subscription success or failure and for receipt of individual events, please see Session.subscribe(), as the techniques and caveats discussed there also apply.

See Also

Nirvana.Observe

this.unsubscribe = function ()

Unsubscribes from the TransactionalQueue, and stops receiving events.

A successful or failed unsubscription attempt will fire an observable event on the Queue (see Nirvana.Observe for applicable observables).

Returns

The TransactionalQueue object on which TransactionalQueue.unsubscribe() was invoked (making this a chainable method).

Example Usage

function unsubscribeHandler(resource) {
   console.log("Unsubscribed from: " + resource.getName());
}

myTransactionalQueue.on(Nirvana.Observe.UNSUBSCRIBE, unsubscribeHandler);
myTransactionalQueue.unsubscribe();

See Also

TransactionalQueue.subscribe(), Session.subscribe(), Nirvana.Observe

this.isSubscribed = function ()

Returns true or false, depending on whether a subscription exists for the TransactionalQueue.

Returns

A boolean value of true or false.

Example Usage

if ( !myTransactionalQueue.isSubscribed() ) {
   myTransactionalQueue.subscribe();
}

See Also

TransactionalQueue.subscribe(), Session.subscribe()

this.publish = function ( event )

Publishes a Universal Messaging Event to the TransactionalQueue.

Parameters

Returns

The TransactionalQueue object on which TransactionalQueue.publish() was invoked (making this a chainable method).

Example Usage

var myEvent = Nirvana.createEvent();
var myDict = myEvent.getDictionary();
myDict.putString("message", "Hello World");
myTransactionalQueue.publish(myEvent);

this.createTransaction = function ()

Factory method to create a new Transaction for use on the TransactionalQueue.

Returns

A new Transaction object.

Example Usage

var myTransaction = myTransactionalQueue.createTransaction();

this.commit = function ( event )

Commits the read of the supplied Event on the TransactionalQueue.  If there are any Event objects which the client has previously received but not called commit on, they will be implicitly committed.

Parameters

Returns

The TransactionalQueue object on which TransactionalQueue.commit() was invoked (making this a chainable method).

Example Usage

var dataCallback = function(event) {
  myQueue.commit(event); // commit every event we receive
}

myQueue.on(Nirvana.Observe.DATA, dataCallback);

this.commitAll = function ()

Commits the read of all received Events on the TransactionalQueue.  This behaves the same as committing the most recent event received by the client.

Returns

The TransactionalQueue object on which TransactionalQueue.commitAll() was invoked (making this a chainable method).

Example Usage

var dataCallback = function(event) {
  myQueue.commitAll(); // Same as doing myQueue.commit(event)
}

myQueue.on(Nirvana.Observe.DATA, dataCallback);

this.rollback = function ( event )

Performs a Roll back of the TransactionalQueue to the supplied Event.  Any uncommitted events received after the given parameter will be added to the queue and redelivered to clients.

Note that different clients may receive the redelivered events.

Parameters

Returns

The TransactionalQueue object on which TransactionalQueue.rollback() was invoked (making this a chainable method).

Example Usage

var myEvents = [];

var dataCallback = function(event) {
  myEvents.push(event);

  if(myEvents.length === 5) {
      myQueue.rollback(myEvents[0]); // Rolls back myEvents[1] to myEvents[4]
  }

}

myQueue.on(Nirvana.Observe.DATA, dataCallback);

this.getFilter = function ()

Returns the SQL-style filter applied to an existing or subsequent subscription to the TransactionalQueue.  By default, no filter is used unless one is set with setFilter().

Returns

A string representing the filter applied to an existing or subsequent subscription to the TransactionalQueue.

Example Usage

var filter = myTransactionalQueue.getFilter();

See Also

TransactionalQueue.setFilter(), TransactionalQueue.subscribe()

this.setFilter = function ( newFilter )

Sets the SQL-style filter to be applied to a subsequent subscription to the TransactionalQueue.  No filter is applied to a subscription if one is not set explicitly using this method.

Parameters

Returns

The TransactionalQueue object on which TransactionalQueue.setFilter() was invoked (making this a chainable method).

Example Usage

var myTransactionalQueue = mySession.getQueue("/some/queue");
// receive only events matching the following filter:
myTransactionalQueue.setFilter("currencypair = 'USDGBP' AND price < 0.6385");
myTransactionalQueue.subscribe();

See Also

TransactionalQueue.getFilter(), TransactionalQueue.subscribe()

this.getWindowSize = function ()

Returns the window size for transactional reading on the TransactionalQueue.  By default, its value is 5 unless changed with TransactionalQueue.setWindowSize().

The window size for a TransactionalQueue indicates how many events will be delivered by the server to the client before the client must call TransactionalQueue.commit() or TransactionalQueue.rollback().

Returns

An integer representing the window size of the current or future subscription to this TransactionalQueue.

Example Usage

var windowSize = myTransactionalQueue.getWindowSize();

See Also

TransactionalQueue.setWindowSize()

this.setWindowSize = function ( newWindowSize )

Sets the window size for transactional reading on the TransactionalQueue.

This defines the number of Events that can be read before the reads are committed with a call to <TransactionalQueue.commit(Event)> or TransactionalQueue.rollback().

If the window size is not explicitly set with a call to TransactionalQueue.setWindowSize(), then the default value is 5.

Parameters

A positive integer, greater than 0.  Representing the new window size of this TransactionalQueue.

Returns

The TransactionalQueue object on which TransactionalQueue.setWindowSize() was invoked (making this a chainable method).

Example Usage

myTransactionalQueue.setWindowSize(10);

See Also

TransactionalQueue.getWindowSize()

this.getName = function ()

Returns the TransactionalQueue’s fully qualified name (e.g.  “/some/queue”).

Returns

A string representing the TransactionalQueue’s fully qualified name.

Example Usage

var transactionalQueueName = myTransactionalQueue.getName();

See Also

Session.getQueue()

this.getResourceType = function ()

Returns the constant Nirvana.TRANSACTIONAL_QUEUE_RESOURCE, which identifies this resource as a TransactionalQueue.

Returns

A integer constant equal to Nirvana.TRANSACTIONAL_QUEUE_RESOURCE.

Example Usage

if (myQueue.getResourceType() === Nirvana.TRANSACTIONAL_QUEUE_RESOURCE) {
   console.log("myQueue is a queue with a transactional reader");
}

this.on = function ( observable, listener )

Registers a single event listener on the TransactionalQueue for observable events of the specified type (see Nirvana.Observe for applicable observables).

Parameters

Returns

The TransactionalQueue object on which TransactionalQueue.on() was invoked (making this a chainable method).

Example Usage

function myHandler(evt) {
   console.log("Received event from: " + evt.getResourceName());
}
myTransactionalQueue.on(Nirvana.Observe.DATA, myHandler);

Additional Information

For more information on assigning listeners for Nirvana.Observe.DATA or any other observable event, please see the Nirvana.Observe Example Usage section.

See Also

TransactionalQueue.removeListener(), Nirvana.Observe

this.removeListener = function ( observable, listener )

Removes a specific listener for observable events of the specified type (see Nirvana.Observe for applicable observables).

Parameters

Returns

The TransactionalQueue object on which TransactionalQueue.removeListener() was invoked (making this a chainable method).

Example Usage

function myHandler(evt) {
  // do something with the evt passed to us as a parameter
}
myTransactionalQueue.on(Nirvana.Observe.DATA, myHandler);

// when we want to, we can un-assign the listener:
myTransactionalQueue.removeListener(Nirvana.Observe.DATA, myHandler);

Additional Information

For more information on removing listeners for Nirvana.Observe.DATA or any other observable event, please see the Nirvana.Observe Example Usage section.

See Also

TransactionalQueue.on(), Nirvana.Observe

Event.prototype.getSession = function getSession()

Returns the Session with which this Event is associated, or null if this is a new client-created Event.

If an Event is received via a subscription to a resource such as a Channel, Queue or TransactionalQueue then this method will return the Session object with which the resource, and thus the Event, is associated.

If an Event has been created locally with a call to Nirvana.createEvent(), then this method will return null.

Returns

A Session object or null.

Example Usage

var s = evt.getSession();
if (s != null) {
   s.getChannel("/some/channel").publish(evt);
}

Event.prototype.getResource = function getResource()

Returns the resource object from which the Event was received, or null if this is a new client-created Event.

If this Event was received via a client-initiated subscription, then this method will return the corresponding Channel, Queue or TransactionalQueue object.

If this Event was received as a result of DataGroup membership via a DataStream-enabled Session, this method will return a reference to the Session object.

If an Event has been created locally with a call to Nirvana.createEvent(), then this method will return null.

Returns

The resource from which the Event was received, or null if it is a new, locally-created Event.

Example Usage

var sourceChannel = evt.getResource(); // assuming evt came from a Channel subscription

Event.prototype.getResourceName = function getResourceName()

Returns the name of the resource with which the Event is associated, or null if this is a new client-created Event.

If an Event is received via a client-initiated subscription to a resource such as a Channel, Queue or TransactionalQueue then this method will return the name of the resource with which the Event is associated (e.g.  “/some/channel”).

If this Event was received as a result of DataGroup membership via a DataStream-enabled Session, this method will return the name of the source DataGroup.

If an Event has been created locally with a call to Nirvana.createEvent(), then this method will return null.

Returns

A string representing the resource’s fully qualified name, or null if it is a new, locally-created Event.

Example Usage

var channelName = evt.getResourceName(); // assuming evt came from a Channel subscription

Event.prototype.getTTL = function getTTL()

Returns the Event’s TTL (Time-to-live) in milliseconds.

Returns

An integer representing the Event’s TTL in milliseconds.

Example Usage

var ttl = evt.getTTL();

See Also

Event.setTTL()

Event.prototype.setTTL = function setTTL( newTTL )

Sets the Event’s TTL (Time-to-live) in milliseconds.  This is useful if you wish to publish an Event that will expire after a certain time.

Parameters

Returns

The Event object on which Event.setTTL() was invoked (making this a chainable method).

Example Usage

evt.setTTL(60000); // expire one minute after publishing
myChannel.publish(evt);

See Also

Event.getTTL()

Event.prototype.getEID = function getEID( longFormat )

Returns the Event’s ID (the EID).

Parameters

Returns

By default a Number representing the Event’s ID (EID).  If longFormat is provided as a parameter will return the selected type if the Event’s origin is from the server

Example Usage

var eid = evt.getEID();                         //returns the EID as the default, a Number
evt.getEID(Nirvana.LongType.LONG_AS_ARRAY);    // returns an array of the EID split into two 32 bit parts
evt.getEID(Nirvana.LongType.LONG_AS_DECIMAL_STRING);    // returns the EID as decimal formated string
evt.getEID(Nirvana.LongType.LONG_AS_HEXADECIMAL_STRING);    // returns the EID as a hexadecimal string

Event.prototype.getData = function getData( dataFormat )

Returns the Event’s raw data, or undefined if it has no data.

Parameters

Returns

The Event’s raw data, or undefined if it has no data.

Example Usage

evt.setData("Hello World");
evt.getData();        // returns "Hello World"
evt.getData(true);    // returns "SGVsbG8gV29ybGQ="

See Also

Event.setData(), Event.hasData()

Event.prototype.setData = function setData( data, dataFormat )

Sets the Event’s raw data.

Parameters

Returns

The Event object on which Event.setData() was invoked (making this a chainable method).

Example Usage

evt.setData("Hello World");
evt.getData();                // returns "Hello World"

evt.setData(Utils.base64Encode("Another Example"), true);
evt.getData();                // returns "Another Example"

See Also

Event.getData(), Event.hasData()

Event.prototype.getTag = function getTag()

Returns the Event’s tag, or undefined if it has no data.

Returns

The Event’s tag, or undefined if it has no data.

Example Usage

console.log(evt.getTag());

See Also

Event.setTag(), Event.hasTag()

Event.prototype.setTag = function setTag( newTag )

Sets the Event’s tag.

Parameters

Returns

The Event object on which Event.setTTL() was invoked (making this a chainable method).

Example Usage

evt.setTag("sometag");

See Also

Event.getTag(), Event.hasTag()

Event.prototype.getDictionary = function getDictionary()

Returns the Event’s EventDictionary.  If the Event did not explicitly have an EventDictionary, then a new, empty EventDictionary is initialized for the Event.

Note that the object returned is a reference to the Event’s actual EventDictionary, not a copy.  There is therefore no corresponding setDictionary() method.

Returns

An EventDictionary object.

Example Usage

var dict = evt.getDictionary();
dict.putString("message", "Hello World");
myChannel.publish(evt);

See Also

Nirvana.createDictionary(), EventDictionary

Event.prototype.getEventAttributes = function getEventAttributes()

Returns the Event’s EventAttributes.  If the Event did not explicitly have any EventAttributes, then a new, empty EventAttributes object is initialized for the Event.

Note that the object returned is a reference to the Event’s actual EventAttributes, not a copy.  There is therefore no corresponding setEventAttributes() method.

Returns

An EventAttributes object.

Example Usage

var attribs = evt.getEventAttributes();
attribs.setPublisherName("John Doe");
myChannel.publish(evt);

See Also

Event.setTag(), Event.hasTag()

Event.prototype.hasData = function hasData()

Returns true if the Event has data, or false otherwise.

Returns

A boolean value of true or false

Example Usage

if (evt.hasData()) {
  console.log(evt.getData());
}

See Also

Event.getData(), Event.setData(), <Event.getEncodedData()>, <Event.setEncodedData()>

Event.prototype.hasTag = function hasTag()

Returns true if the Event has a tag, or false otherwise.

Returns

A boolean value of true or false

Example Usage

if (evt.hasTag()) {
  console.log(evt.getTag());
}

See Also

Event.getTag(), Event.setTag()

Event.prototype.hasDictionary = function hasDictionary()

Returns true if the Event has an EventDictionary, or false otherwise.

Returns

A boolean value of true or false

Example Usage

if (evt.hasDictionary()) {
   console.log(evt.getDictionary().getKeys());
}

See Also

Event.getDictionary()

EventDictionary.prototype.getKeys = function ()

Returns an array of the keys contained in the EventDictionary.

Returns

An array of key names.

Example Usage

var evt = Nirvana.createEvent();

evt.getDictionary().getKeys(); // returns []

evt.getDictionary().putString("message", "Hello World");
evt.getDictionary().getKeys(); // returns ["message"]

See Also

EventDictionary.get()

EventDictionary.prototype.get = function ( key, longType )

Returns the value to which the EventDictionary maps the specified key.

Parameters

Returns

The value to which this EventDictionary maps the specified key.

Example Usage

var evt = Nirvana.createEvent();
evt.getDictionary().putString("message", "Hello World");
evt.getDictionary().get("message"); // returns "Hello World"