Class jabberwerx.Entity (MINIMAL)

Extends jabberwerx.JWModel.

Something addressable by JID and/or node: user, server, room, etc. For this release, clients are not considered entities; there's a single global client.

This class provides the following events:

jabberwerx.Entity

To subscribe for a single entities primary presence updates use:

entity.event('primaryPresenceUpdated').bind......
To subscribe for all entities primary presence updates use:
jabberwerx.globalEvents.bind('primaryPresenceChanged',......

Class Summary
Constructor Attributes	Constructor Name and Description
	jabberwerx.Entity(key, ctrl) Creates a new Entity with the given key and controller/cache.

Field Summary
Field Attributes	Field Name and Description
	features The set of features for this Entity.
	identities The set of identities for this Entity.
	jid The JID for this Entity.
	node The node ID for this Entity.
	properties The properties for this Entity.

Method Summary
Method Attributes	Method Name and Description
	apply(entity, noupdate) Applies the values from the given entity to this one.
	destroy() Destroys this entity.
	getAllPresence() Returns a sorted array of all presence objects for this entity
	getDisplayName() Retrieves the display name for this Entity.
	getGroups() Retrieves the groups for this Entity.
	getPrimaryPresence() Gets the primary presence object of this entity.
	getResourcePresence(resource) Gets the presence object for a particular resource under this entity.
	hasFeature(feat) Determines if this Entity supports the given feature.
	hasIdentity(id) Determines if this Entity supports the given identity (as a single "category/type" string).
	isActive() Determines if this entity is active.
	matches(entity) Determines if the given entity matches this Entity.
	remove() Removes this entity.
	setDisplayName(name) Changes or removes the expclit display name for this Entity.
	setGroups(groups) Changes or removes the groups for this Entity.
	toString() Retrieves the string value of this Entity.
	update() Triggers an update of this entity.
	updatePresence(presence, quiet) Update presence for this Entity.

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.Entity(key, ctrl)

Creates a new Entity with the given key and controller/cache.

The value of key is expected to be an object with at least one of the following properties:

jid: The JID for this Entity (must either be undefined or represent a valid JID)
node: The sub node for this Entity (must either be undefined or a non-empty string)

The value of {ctrl} may be undefined, a jabberwerx.Controller or a jabberwerx.ClientEntityCache. If it is a Controller, its jabberwerx.Controller#updateEntity and jabberwerx.Controller#removeEntity method will be called as appropriate. If it is a ClientEntityCache, the event notifiers for "entityCreated", "entityUpdated", and "entityDestroyed" are retained and used as appropriate.

Parameters:
{Object} key: The JID and/or node identifying this entity
{jabberwerx.Controller|jabberwerx.EntitySet} ctrl Optional: The controller or cache for this entity

Field Detail

features

The set of features for this Entity. This is a unique array of Service Discovery feature strings.

identities

The set of identities for this Entity. This is a unique array of Service Discovery category/type strings.

{jabberwerx.JID} jid

The JID for this Entity. This property may be null if the entity is not JID-addressable.

{String} node

The node ID for this Entity. This property may be "" if the entity is not node-addressable.

properties

The properties for this Entity. This is an open-ended hashtable, with the specifics defined by subclasses.

Method Detail

{jabberwerx.Entity} apply(entity, noupdate)

Applies the values from the given entity to this one. This method copies the groups, displayName, properties, features, and identities from {entity} into this one. It then calls #update, which may trigger an "entityUpdated" event.

Parameters:
{jabberwerx.Entity} entity: The entity to apply
{Boolean} noupdate Optional: true to indicate that an update should NOT be triggered

Throws:
{TypeError}: if {entity} is not an instance of Entity.

Returns:: {jabberwerx.Entity} This entity

destroy()

Destroys this entity. In most cases, this method should not be called directly. Instead, call #remove.

{jabberwerx.Presence[]} getAllPresence()

Returns a sorted array of all presence objects for this entity

Returns:: {jabberwerx.Presence[]} an array of presence objects

{String} getDisplayName()

Retrieves the display name for this Entity. This method returns the explicitly set value (if one is present), or a string using the following format:

{<node>}<jid>

Where <jid> is #jid (or "" if not defined), and <node> is #node (or "" if not defined).

Subclasses overriding this method SHOULD also override #setDisplayName.

Returns:: {String} The display name

{String[]} getGroups()

Retrieves the groups for this Entity. The returned array is never {null} or {undefined}.

Returns:: {String[]} The array of groups (as strings)

{jabberwerx.Presence} getPrimaryPresence()

Gets the primary presence object of this entity. If the primary presence for this object does not exist then null is returned.

Returns:: {jabberwerx.Presence} primary presence

{jabberwerx.Presence} getResourcePresence(resource)

Gets the presence object for a particular resource under this entity.

Parameters:
{String} resource: The resource to get the presence object for

Returns:: {jabberwerx.Presence} The presence object for the resource. If the resource does not exist or does not have a presence object associated with it then null is returned.

{Boolean} hasFeature(feat)

Determines if this Entity supports the given feature.

Parameters:
{String} feat: The feature to check for

Returns:: {Boolean} true if {feat} is supported

{Boolean} hasIdentity(id)

Determines if this Entity supports the given identity (as a single "category/type" string).

Parameters:
{String} id: The identity to check for as a "category/type" string

Returns:: {Boolean} true if {id} is supported

{Boolean} isActive()

Determines if this entity is active. This method returns true if the entity has at least one available presence in its list.

Subclasses may override this method to provide an alternative means of determining its active state.

Returns:: {Boolean} true if the entity is active

{Boolean} matches(entity)

Determines if the given entity matches this Entity. This method returns true if the jids and nodes of this Entity are equal to {entity}'s.

Parameters:
{jabberwerx.Entity} entity: The entity to match against

Returns:: {Boolean} true if {entity}'s identity matches this Entity.

remove()

Removes this entity. If the entity has a controller, then jabberwerx.Controller#removeEntity is called. Otherwise #destroy is called.

setDisplayName(name)

Changes or removes the expclit display name for this Entity. If the value of {name} is non-empty String, it is set as the explicit display name. Otherwise any previous value is cleared.

If this entity has a controller associated with it, its jabberwerx.Controller#updateEntity is called, passing in this Entity. Otherwise this method attempts to trigger a "entityUpdated" event on the associated event cache.

Subclasses overriding this method SHOULD also override #getDisplayName.

Parameters:
{String} name: The new display name

setGroups(groups)

Changes or removes the groups for this Entity. This method uses the following algorithm:

If {groups} is an array, it is cloned (with duplicate values removed) and replaces any previous groups.
If {groups} is a single string, all previous groups are replaced with an array containing this value.
Otherwise, the previous groups are replaced with an empty array.

Parameters:
{String[]|String} groups Optional: The name of groups

{String} toString()

Retrieves the string value of this Entity.

Returns:: {String} The string value

update()

Triggers an update of this entity. If the entity has a controller, then jabberwerx.Controller#updateEntity is called. Otherwise if this entity has an owning cache, an "entityUpdated" event is fired on that cache for this entity.

{Boolean} updatePresence(presence, quiet)

Update presence for this Entity.

If {presence} results in a change of the primary resource for this entity, a "primaryPresenceChanged" event is triggered. A "resourcePresenceChanged" event is always triggered by this method, before "primaryPresenceChanged" (if applicable).

NOTE: The {quiet} flag is used to suppress the normal eventing for certain cases, such as during entity creation. It should not be needed in most cases.

Parameters:
{jabberwerx.Presence} presence Optional: The presence used to update. If this parameter is null or undefined the presence list for this entity is cleared.
{Boolean} quiet Optional: true to suppress firing "primaryPresenceChagned" and "resourcePresenceChanged" events

Throws:
{TypeError}: If {presence} exists but is not a valid availability or unavailability presence for this entity

Returns:: {Boolean} true if primary presence changed.

Classes

Class jabberwerx.Entity (MINIMAL)