Class jabberwerx.PubSubNode

Extends jabberwerx.Entity.

Represents a pubsub node - a virtual location to which information can be published and from which event notifications and/or payloads can be received.

This class provides the following events:

jabberwerx.PubSubNode

Class Summary
Constructor Attributes	Constructor Name and Description
	jabberwerx.PubSubNode(jid, node, ctrl) Creates a new PubSubNode object for the given pubsub service JID, pubsub node identifier, and PubSubController (or delegate).

Field Summary
Field Attributes	Field Name and Description
	autoRetrieve Flag to determine if items are automatically retrieved from the pubsub node upon subscription.

Fields borrowed from class jabberwerx.Entity:: features, identities, jid, node, properties

Method Summary
Method Attributes	Method Name and Description
	createNode(cb) Creates the pubsub node on the pubsub service.
	deleteNode(cb) Deletes the pubsub node on the pubsub service.
	destroy() Destroys this PubSubNode.
	getDelegatedFor(jid) Retrieves the delegated PubSubNode for the given JID.
	getItems() Retrieves the current PubSubItems for this PubSubNode.
	publish(id, payload, cb) Publishes an item to this PubSubNode with the (optional) item id.
	retract(id, cb) Retracts an item from this PubSubNode.
	retrieve(cb) Retrieves the items for this PubSubNode.
	subscribe(cb) Subscribes to this PubSubNode.
	unsubscribe(cb) Unsubscribes from this PubSubNode.

Methods borrowed from class jabberwerx.Entity:: apply, getAllPresence, getDisplayName, getGroups, getPrimaryPresence, getResourcePresence, hasFeature, hasIdentity, isActive, matches, remove, setDisplayName, setGroups, toString, update, updatePresence
Methods borrowed from class jabberwerx.JWModel:: applyEvent, event, shouldBeSavedWithGraph
Methods borrowed from class jabberwerx.JWBase:: getClassName, graphUnserialized, init, invocation, shouldBeSerializedInline, wasUnserialized, willBeSerialized

Class Detail

jabberwerx.PubSubNode(jid, node, ctrl)

Creates a new PubSubNode object for the given pubsub service JID, pubsub node identifier, and PubSubController (or delegate).

If this PubSubNode is created with a delegate, the owning controller is the delegate's controller. A delegated PubSubNode (one that has a delegate) is mostly just a container of published items, relying on the delegate to perform most operations.

NOTE: This type should not be constructed directly. Instead, use jabberwerx.PubSubController#node to obtain an instance.

Parameters:
{jabberwerx.JID} jid: The JID of the pubsub service which hosts this pubsub node
{String} node: The unique identifier for the node within the context of the pubsub service
{jabberwerx.PubSubController|jabberwerx.PubSubNode} ctrl: The owning controller or delegate

Throws:
{TypeError}: If {ctrl} is not valid; or if {node} is not valid

Field Detail

{Boolean} autoRetrieve

Flag to determine if items are automatically retrieved from the pubsub node upon subscription.

Method Detail

createNode(cb)

Creates the pubsub node on the pubsub service.

The callback function, if defined, will be executed after the pubsub service response is received. If an error occurred the function will be passed the <error> Element of the response stanza.

The signature of the callback function is expected to match the following:

 function callback(err) {
     this;   // the PubSubNode object representing the pubsub node
             to which the createNode attempt was made
     err;    // the stanza error Element if create failed,
             else undefined
 }

Parameters:
{Function} cb Optional: The callback function

Throws:
{TypeError}: If {cb} is defined and not a function
{jabberwerx.Client.NotConnectedError}: If the client is not connected
{jabberwerx.PubSubNode.DelegatedNodeError}: If this is a delegated node

deleteNode(cb)

Deletes the pubsub node on the pubsub service.

The callback function, if defined, will be executed after the pubsub service response is received. If an error occurred the function will be passed the <error> Element of the response stanza.

The signature of the callback function is expected to match the following:

 function callback(err) {
     this;   // the PubSubNode object representing the pubsub node
             to which the deleteNode attempt was made
     err;    // the stanza error Element if delete failed,
             else undefined
 }

Parameters:
{Function} cb Optional: The callback function

Throws:
{TypeError}: If {cb} is defined and not a function
{jabberwerx.Client.NotConnectedError}: If the client is not connected
{jabberwerx.PubSubNode.DelegatedNodeError}: If this is a delegated node

destroy()

Destroys this PubSubNode. This method unbinds registered callbacks, destroys any delegated PubSubNodes, and then calls the superclass' implementation.

{jabberwerx.PubSubNode} getDelegatedFor(jid)

Retrieves the delegated PubSubNode for the given JID. If such a delegated node does not exist, one is created.

Parameters:
{String|jabberwerx.JID} jid: The JID of the delegated node

Throws:
{TypeError}: if {jid} is not a valid JID
{jabberwerx.PubSubNode.DelegatedNodeError}: If this PubSubNode is already delegated.

Returns:: {jabberwerx.PubSubNode} The delegated node

{jabberwerx.PubSubItem[]} getItems()

Retrieves the current PubSubItems for this PubSubNode. The returned array's items are indexed by both the natural array index (e.g. items[0], items[1]) and by the "item:{item.id}" (e.g. items["item:current"], items["item:some-random-id"]).

Returns:: {jabberwerx.PubSubItem[]} The current items

publish(id, payload, cb)

Publishes an item to this PubSubNode with the (optional) item id.

The callback function, if defined, will be executed after the pubsub service response is received. If an error occurred the function will be passed the <error> Element of the response stanza.

The signature of the callback function is expected to match the following:

 function callback(err, id) {
     this;   // the PubSubNode object representing the pubsub node
             to which the publish attempt was made
     err;    // the stanza error Element if publish failed,
             else undefined
     id;     // the item id of the published item, either supplied
             with publish request or generated by the pubsub service
 }

Parameters:
{String} id Optional: The item id
{Element} payload Optional: The item payload
{Function} cb Optional: The callback function

Throws:
{TypeError}: If {cb} is defined and not a function; If {paylaod} is defined and not an Element
{jabberwerx.Client.NotConnectedError}: If the client is not connected

retract(id, cb)

Retracts an item from this PubSubNode.

The callback function, if defined, will be executed after the pubsub service response is received. If an error occurred the function will be passed the <error> Element of the response stanza.

The signature of the callback function is expected to match the following:

 function callback(err) {
     this;   // the PubSubNode object representing the pubsub node
             to which the retract attempt was made
     err;    // the stanza error Element if retract failed,
             else undefined
 }

Parameters:
{String} id: The item id
{Function} cb Optional: The callback function

Throws:
{TypeError}: If {cb} is defined and not a function; if {id} is empty or not a string
{jabberwerx.Client.NotConnectedError}: If the client is not connected

retrieve(cb)

Retrieves the items for this PubSubNode. This method updates the list of items returned by #getItems with the current remote state of the pubsub node.

The callback function, if defined, will be executed after the pubsub service response is received. If an error occurred the function will be passed the <error> Element of the response stanza.

The signature of the callback function is expected to match the following:

 function callback(err) {
     this;   // the PubSubNode object representing the pubsub node
             to which the retrieve attempt was made
     err;    // the stanza error Element if retrieve failed,
             else undefined
 }

Parameters:
{Function} cb Optional: The callback function

Throws:
{TypeError}: If {cb} is defined and not a function
{jabberwerx.Client.NotConnectedError}: If the client is not connected

See:: #getItems

subscribe(cb)

Subscribes to this PubSubNode. This method sends the explicit subscription request to the pubsub node, using the connected user's bare JID.

The callback function, if defined, will be executed after the pubsub service response is received. If an error occurred the function will be passed the <error> Element of the response stanza.

The signature of the callback function is expected to match the following:

 function callback(err) {
     this;   // the PubSubNode object representing the pubsub node
             to which the subscribe attempt was made
     err;    // the stanza error Element if subscribe failed, else
             undefined
 }

Parameters:
{Function} cb Optional: The callback function

Throws:
{TypeError}: If {cb} is defined and not a function
{jabberwerx.Client.NotConnectedError}: If the client is not connected

See:: #unsubscribe

unsubscribe(cb)

Unsubscribes from this PubSubNode. This method sends the explicit unsubscription request to the pubsub node.

The callback function, if defined, will be executed after the pubsub service response is received. If an error occurred the function will be passed the <error> Element of the response stanza.

The signature of the callback function is expected to match the following:

 function callback(err) {
     this;   // the PubSubNode object representing the pubsub node
             to which the unsubscribe attempt was made
     err;    // the stanza error Element if unsubscribe failed,
             else undefined
 }

Parameters:
{Function} cb Optional: The callback function

Throws:
{TypeError}: If {cb} is defined and not a function
{jabberwerx.Client.NotConnectedError}: If the client is not connected

See:: #subscribe

Classes

Class jabberwerx.PubSubNode