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
	applyConfig(form, cb) Set the nodes's configuration.
	createNode(cb) Creates the pubsub node on the pubsub service.
	deleteNode(cb) Deletes the pubsub node on the pubsub service.
	destroy() Destroys this PubSubNode.
	fetchAffiliations(cb) Get the affiliations for the pubsub node on the pubsub service.
	fetchConfig(cb) Fetch the nodes's configuration jabberwerx.XDataForm The callback function will be executed after the pubsub service response is received.
	getDelegatedFor(jid) Retrieves the delegated PubSubNode for the given JID.
	getItems() Retrieves the current PubSubItems for this PubSubNode.
	isCachingItems() Is the node caching PubSubNode items? See jabberwerx.PubSubNode#setCachingItems for a detailed discussion of item caching.
	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.
	setCachingItems(enable) Enable or disable a node's jabberwerx.PubSubItem caching.
	subscribe(cb) Subscribes to this PubSubNode.
	unsubscribe(cb) Unsubscribes from this PubSubNode.
	updateAffiliation(jid, affiliation, cb) Updates or remove the affiliation for a jid on the pubsub node.

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

applyConfig(form, cb)

Set the nodes's configuration. Use the given jabberwerx.XDataForm (or a generated cancel form if null) to update the node's configuration. Fires the optional callback on result.

The optional function {cb} is expected to match the following signature:

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

Errors may be any error node found in the result.

Parameters:
{jabberwerx.XDataForm} form: The xdata configuration to set, may be null.
{Function} cb Optional: Callback fired on attempt completion.

Throws:
{TypeError}: If {cb} is defined but not a function or form is non null but not an XDataForm.
{jabberwerx.Client.NotConnectedError}: If the client is not connected

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.

fetchAffiliations(cb)

Get the affiliations for 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(affiliations, err) {
     this;           // the PubSubNode object representing the pubsub node
                         to which the deleteNode attempt was made.
     affiliations;   //map of jid key to affiliation string (null if failed)
     err;            // the stanza error Element if get 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

fetchConfig(cb)

Fetch the nodes's configuration jabberwerx.XDataForm

The callback function 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. On success the function is passed the resultant jabberwerx.XDataForm in the {form} parameter.

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

 function callback(form, err) {
     this;   // the PubSubNode object representing the pubsub node
             to which the configuration fetch attempt was made
     form;   // the fetched jabberwerx.XDataForm
             null if fetch failed
     err;    // the stanza error Element if fetch failed, else
             undefined
 }

Parameters:
{Function} cb: The callback function

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

{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

{Boolean} isCachingItems()

Is the node caching PubSubNode items? See jabberwerx.PubSubNode#setCachingItems for a detailed discussion of item caching.

Returns:: {Boolean} True if the node is currently caching items, otherwise False

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, node) {
     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
     node;   node to which the retrieve attempt was made, 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

setCachingItems(enable)

Enable or disable a node's jabberwerx.PubSubItem caching.

PubSubNode will automatically cache items received by this node. In some use cases (for example where items are events), every item has a unique identitfier and the item cache becomes a resource drain over time. This method disables item caching for the node.

When the item cache has been disabled PubSubNode modifies its behavior in the following ways:

All items received are considered new. When any item(s) is received a pubsubItemsChanged:added event will be triggered. The pubsubItemsChanged:updated event is never tiggered.
When an item is retracted a pubsubItemsChanged:removed event is triggered with a new PubSubItem. Essentially, the user cannot assume reference equality when working with items.
When a node is deleted or purged no pubsubItemsChanged:removed event is triggered for previously received items.
When a node is unsubscribed no pubsubItemsChanged:removed event is triggered for previously received items.
The jabberwerx.PubSubNode#getItems method will always return an empty array.

NOTE: Items in the cache are NOT retracted when the item cache is disabled.

Parameters:
{Boolean} enable: If True, enable item caching from this moment onward. If not True the cache is cleared and no new items are added.

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 property "node.properties.subscription" can be checked to determine if the subscribe succeeded but the retrieve failed.

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

 function callback(err, node) {
     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
     node;    // node to which the subscribe attempt was made, 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

updateAffiliation(jid, affiliation, cb)

Updates or remove the affiliation for a jid on the pubsub node.

The optional function {cb} is expected to match the following signature:

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

Errors may be any error node found in the result.

Parameters:
{String|jabberwerx.JID} jid: The JID of the delegated node.
{String} affiliation: the desired affiliation to be set.
{Function} cb Optional: Callback fired on attempt completion.

Throws:
{TypeError}: If the affiliation is not a valid affiliation string. Possible values are "owner", "member", "publisher", "publish-only", "outcast" or "none". Setting the affiliation to "none" actually deletes the affiliation.
{TypeError}: If {cb} is defined but not a function or form is non null but not an XDataForm.
{jabberwerx.Client.NotConnectedError}: If the client is not connected

Classes

Class jabberwerx.PubSubNode