org.jivesoftware.openfire.entitycaps

Class EntityCapabilitiesManager

java.lang.Object

org.jivesoftware.openfire.container.BasicModule

org.jivesoftware.openfire.entitycaps.EntityCapabilitiesManager

All Implemented Interfaces:

Module, UserEventListener, org.xmpp.component.IQResultListener

public class EntityCapabilitiesManager
extends BasicModule
implements org.xmpp.component.IQResultListener, UserEventListener

Implements server side mechanics for XEP-0115: "Entity Capabilities" Version 1.4 In particular, EntityCapabilitiesManager is useful for processing "filtered-notifications" for use with Pubsub (XEP-0060) for contacts that may not want to receive notifications for all payload types. The server's role in managing Entity Capabilities is to cache previously encountered entity capabilities for XMPP clients supporting the same identities and features. If the server has not seen a particular combination of identities and features, a Discover Information query is sent to that client and its reply is cached for future use by clients sharing those same entity capabilities.

Author:

Armando Jagucki

See Also:

Field Summary

Fields

Modifier and Type	Field and Description
static String	OPENFIRE_IDENTIFIER_NODE A XEP-0115 described identifier for the Openfire server software, intended to be used as a value of 'node' attributes.

Constructor Summary

Constructors

Constructor and Description
EntityCapabilitiesManager()

Method Summary

Modifier and Type	Method and Description
void	addListener(EntityCapabilitiesListener listener) Registers an event listener that will be invoked when the detected entity capabilities for any entity have changed.
void	addListener(org.xmpp.packet.JID entity, EntityCapabilitiesListener listener) Registers an event listener that will be invoked when the detected entity capabilities for a particular entity have changed.
void	answerTimeout(String packetId)
protected void	checkObsolete(String verHash) Verifies if the provided 'ver' hash is used for any user.
void	destroy() Destroys the module.
protected void	dispatch(org.xmpp.packet.JID entity, EntityCapabilities updatedEntityCapabilities, EntityCapabilities previousEntityCapabilities) Invokes the entityCapabilitiesChanged method of all currently registered event listeners.
static String	generateVerHash(org.xmpp.packet.IQ packet, String algorithm) Generates a 'ver' hash attribute used in validation to help prevent poisoning of entity capabilities information.
EntityCapabilities	getEntityCapabilities(org.xmpp.packet.JID jid) Returns the entity capabilities for a specific JID.
static EntityCapabilitiesManager	getInstance() Deprecated. Replaced by XMPPServer.getEntityCapabilitiesManager()
static String	getLocalDomainVerHash() Returns the 'ver' hash for this server.
void	initialize(XMPPServer server) Initializes the basic module.
void	process(org.xmpp.packet.Presence packet)
void	receivedAnswer(org.xmpp.packet.IQ packet)
protected void	registerCapabilities(org.xmpp.packet.JID entity, EntityCapabilities newCapabilities) Registers that a particular entity has a particular set of capabilities, invoking event listeners when appropriate.
void	removeListener(EntityCapabilitiesListener listener) Removes a previously registered event listener, if such a listener is currently registered.
void	removeListener(org.xmpp.packet.JID entity, EntityCapabilitiesListener listener) Removes a previously registered event listener for a particular entity, if such a combination is currently registered.
void	removeListeners(org.xmpp.packet.JID entity) Removes all previously registered event listener for a particular entity, if any were registered.
void	userCreated(User user, Map<String,Object> params) A user was created.
void	userDeleting(User user, Map<String,Object> params) A user is being deleted.
void	userModified(User user, Map<String,Object> params) A user's name, email, or an extended property was changed.

Methods inherited from class org.jivesoftware.openfire.container.BasicModule

getName, start, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OPENFIRE_IDENTIFIER_NODE

public static final String OPENFIRE_IDENTIFIER_NODE

A XEP-0115 described identifier for the Openfire server software, intended to be used as a value of 'node' attributes.

See Also:

Constant Field Values

Constructor Detail

EntityCapabilitiesManager

public EntityCapabilitiesManager()

Method Detail

initialize

public void initialize(XMPPServer server)

Description copied from class: BasicModule

Initializes the basic module.

Inheriting classes that choose to override this method MUST call this initialize() method before accessing BasicModule resources.

Specified by:

initialize in interface Module

Overrides:

initialize in class BasicModule

Parameters:

server - the server hosting this module.

destroy

public void destroy()

Description copied from class: BasicModule

Destroys the module.

Does nothing in the basic module.

Specified by:

destroy in interface Module

Overrides:

destroy in class BasicModule

getInstance

@Deprecated
public static EntityCapabilitiesManager getInstance()

Deprecated. Replaced by XMPPServer.getEntityCapabilitiesManager()

Returns the unique instance of this class.

Returns:

the unique instance of this class.

process

public void process(org.xmpp.packet.Presence packet)

generateVerHash

public static String generateVerHash(org.xmpp.packet.IQ packet,
                                     String algorithm)

Generates a 'ver' hash attribute used in validation to help prevent poisoning of entity capabilities information.

Parameters:

packet - IQ reply to the entity cap request.

algorithm - The hashing algorithm to use (e.g. SHA-1)

Returns:

the generated 'ver' hash

See Also:

The value of the 'ver' attribute is generated according to the method outlined in XEP-0115.

answerTimeout

public void answerTimeout(String packetId)

Specified by:

answerTimeout in interface org.xmpp.component.IQResultListener

receivedAnswer

public void receivedAnswer(org.xmpp.packet.IQ packet)

Specified by:

receivedAnswer in interface org.xmpp.component.IQResultListener

getEntityCapabilities

public EntityCapabilities getEntityCapabilities(org.xmpp.packet.JID jid)

Returns the entity capabilities for a specific JID. The specified JID should be a full JID that identified the entity's connection.

Parameters:

jid - the full JID of entity

Returns:

the entity capabilities of jid, or null if these are unavailable.

registerCapabilities

protected void registerCapabilities(@Nonnull
                                    org.xmpp.packet.JID entity,
                                    @Nonnull
                                    EntityCapabilities newCapabilities)

Registers that a particular entity has a particular set of capabilities, invoking event listeners when appropriate.

Parameters:

entity - The entity for which a set of capabilities is detected.

newCapabilities - The capabilities that are detected.

addListener

public void addListener(@Nonnull
                        org.xmpp.packet.JID entity,
                        @Nonnull
                        EntityCapabilitiesListener listener)

Registers an event listener that will be invoked when the detected entity capabilities for a particular entity have changed. This method supports multiple event listeners per JID. Registration of the same combination of entity and listener will be ignored.

Parameters:

entity - The entity for which to listen for events.

listener - The event listener to be invoked when entity capabilities have changed.

removeListener

public void removeListener(@Nonnull
                           org.xmpp.packet.JID entity,
                           @Nonnull
                           EntityCapabilitiesListener listener)

Removes a previously registered event listener for a particular entity, if such a combination is currently registered.

Parameters:

entity - The entity for which the listener was registered.

listener - The event listener to be removed.

removeListeners

public void removeListeners(@Nonnull
                            org.xmpp.packet.JID entity)

Removes all previously registered event listener for a particular entity, if any were registered.

Parameters:

entity - The entity for which listeners are to removed.

addListener

public void addListener(@Nonnull
                        EntityCapabilitiesListener listener)

Registers an event listener that will be invoked when the detected entity capabilities for any entity have changed. If the listener already is registered, the invocation of this method will be a no-op.

Parameters:

listener - The event listener to be invoked when entity capabilities have changed.

removeListener

public void removeListener(@Nonnull
                           EntityCapabilitiesListener listener)

Removes a previously registered event listener, if such a listener is currently registered.

Parameters:

listener - The event listener to be removed.

dispatch

protected void dispatch(@Nonnull
                        org.xmpp.packet.JID entity,
                        @Nonnull
                        EntityCapabilities updatedEntityCapabilities,
                        @Nullable
                        EntityCapabilities previousEntityCapabilities)

Invokes the entityCapabilitiesChanged method of all currently registered event listeners. It is assumed that this method is used to notify listeners of a change in capabilities for a particular entity.

Parameters:

entity - The entity for which an event is to be dispatched

updatedEntityCapabilities - The most up-to-date capabilities.

previousEntityCapabilities - The capabilities, if any, prior to the update.

userDeleting

public void userDeleting(User user,
                         Map<String,Object> params)

Description copied from interface: UserEventListener

A user is being deleted.

Specified by:

userDeleting in interface UserEventListener

Parameters:

user - the user.

params - event parameters.

checkObsolete

protected void checkObsolete(String verHash)

Verifies if the provided 'ver' hash is used for any user. If not, the cache entry containing the entity capabilities are removed from the cache.

Parameters:

verHash - an 'ver' hash (cannot be null).

userCreated

public void userCreated(User user,
                        Map<String,Object> params)

Description copied from interface: UserEventListener

A user was created.

Specified by:

userCreated in interface UserEventListener

Parameters:

user - the user.

params - event parameters.

userModified

public void userModified(User user,
                         Map<String,Object> params)

Description copied from interface: UserEventListener

A user's name, email, or an extended property was changed.

Specified by:

userModified in interface UserEventListener

Parameters:

user - the user.

params - event parameters.

getLocalDomainVerHash

public static String getLocalDomainVerHash()

Returns the 'ver' hash for this server.

Returns:

A 'ver' hash, or null if none could be generated.