org.jivesoftware.smackx.disco

Class ServiceDiscoveryManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.disco.ServiceDiscoveryManager

public final class ServiceDiscoveryManager
extends Manager

Manages discovery of services in XMPP entities. This class provides:

1. A registry of supported features in this XMPP entity.
2. Automatic response when this XMPP entity is queried for information.
3. Ability to discover items and information of remote XMPP entities.
4. Ability to publish publicly available items.

Method Summary

Modifier and Type	Method and Description
boolean	accountSupportsFeatures(CharSequence... features) Check if the given features are supported by the connection account.
boolean	accountSupportsFeatures(Collection<? extends CharSequence> features) Check if the given collection of features are supported by the connection account.
static void	addDiscoInfoLookupShortcutMechanism(DiscoInfoLookupShortcutMechanism discoInfoLookupShortcutMechanism)
void	addDiscoverInfoTo(DiscoverInfo response) Add discover info response data.
boolean	addEntityCapabilitiesChangedListener(EntityCapabilitiesChangedListener entityCapabilitiesChangedListener)
void	addFeature(String feature) Registers that a new feature is supported by this XMPP entity.
void	addIdentity(DiscoverInfo.Identity identity) Add an further identity to the client.
static boolean	canPublishItems(DiscoverInfo info) Deprecated. The disco-publish feature was removed from XEP-0030 in 2008 in favor of XEP-0060: Publish-Subscribe.
boolean	canPublishItems(Jid entityID) Deprecated. The disco-publish feature was removed from XEP-0030 in 2008 in favor of XEP-0060: Publish-Subscribe.
DiscoverInfo	discoverInfo(Jid entityID) Returns the discovered information of a given XMPP entity addressed by its JID.
DiscoverInfo	discoverInfo(Jid entityID, String node) Returns the discovered information of a given XMPP entity addressed by its JID and note attribute.
DiscoverItems	discoverItems(Jid entityID) Returns the discovered items of a given XMPP entity addressed by its JID.
DiscoverItems	discoverItems(Jid entityID, String node) Returns the discovered items of a given XMPP entity addressed by its JID and note attribute.
DomainBareJid	findService(String feature, boolean useCache)
DomainBareJid	findService(String feature, boolean useCache, String category, String type)
List<DomainBareJid>	findServices(String feature, boolean stopOnFirst, boolean useCache) Find all services under the users service that provide a given feature.
List<DiscoverInfo>	findServicesDiscoverInfo(DomainBareJid serviceName, String feature, boolean stopOnFirst, boolean useCache, Map<? super Jid,Exception> encounteredExceptions) Find all services under a given service that provide a given feature.
List<DiscoverInfo>	findServicesDiscoverInfo(String feature, boolean stopOnFirst, boolean useCache) Find all services under the users service that provide a given feature.
List<DiscoverInfo>	findServicesDiscoverInfo(String feature, boolean stopOnFirst, boolean useCache, Map<? super Jid,Exception> encounteredExceptions) Find all services under the users service that provide a given feature.
DataForm	getExtendedInfo() Returns the data form that is set as extended information for this Service Discovery instance (XEP-0128).
List<ExtensionElement>	getExtendedInfoAsList() Returns the data form as List of PacketExtensions, or null if no data form is set.
List<String>	getFeatures() Returns the supported features by this XMPP entity.
Set<DiscoverInfo.Identity>	getIdentities() Returns all identities of this client as unmodifiable Collection.
DiscoverInfo.Identity	getIdentity() Return the default identity of the client.
String	getIdentityName() Returns the name of the client that will be returned when asked for the client identity in a disco request.
String	getIdentityType() Returns the type of client that will be returned when asked for the client identity in a disco request.
static ServiceDiscoveryManager	getInstanceFor(XMPPConnection connection) Returns the ServiceDiscoveryManager instance associated with a given XMPPConnection.
boolean	includesFeature(String feature) Returns true if the specified feature is registered in the ServiceDiscoveryManager.
void	publishItems(Jid entityID, DiscoverItems discoverItems) Deprecated. The disco-publish feature was removed from XEP-0030 in 2008 in favor of XEP-0060: Publish-Subscribe.
void	publishItems(Jid entityID, String node, DiscoverItems discoverItems) Deprecated. The disco-publish feature was removed from XEP-0030 in 2008 in favor of XEP-0060: Publish-Subscribe.
static void	removeDiscoInfoLookupShortcutMechanism(DiscoInfoLookupShortcutMechanism discoInfoLookupShortcutMechanism)
void	removeExtendedInfo() Removes the data form containing extended service discovery information from the information returned by this XMPP entity.
void	removeFeature(String feature) Removes the specified feature from the supported features by this XMPP entity.
boolean	removeIdentity(DiscoverInfo.Identity identity) Remove an identity from the client.
void	removeNodeInformationProvider(String node) Removes the NodeInformationProvider responsible for providing information (ie items) related to a given node.
boolean	serverSupportsFeature(CharSequence feature) Returns true if the server supports the given feature.
boolean	serverSupportsFeatures(CharSequence... features)
boolean	serverSupportsFeatures(Collection<? extends CharSequence> features)
static void	setDefaultIdentity(DiscoverInfo.Identity identity) Set the default identity all new connections will have.
void	setExtendedInfo(DataForm info) Registers extended discovery information of this XMPP entity.
void	setIdentity(DiscoverInfo.Identity identity) Sets the default identity the client will report.
void	setNodeInformationProvider(String node, NodeInformationProvider listener) Sets the NodeInformationProvider responsible for providing information (ie items) related to a given node.
boolean	supportsFeature(Jid jid, CharSequence feature) Queries the remote entity for it's features and returns true if the given feature is found.
boolean	supportsFeatures(Jid jid, CharSequence... features)
boolean	supportsFeatures(Jid jid, Collection<? extends CharSequence> features)

Methods inherited from class org.jivesoftware.smack.Manager

connection, getAuthenticatedConnectionOrThrow, schedule

Methods inherited from class java.lang.Object

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

Method Detail

setDefaultIdentity

public static void setDefaultIdentity(DiscoverInfo.Identity identity)

Set the default identity all new connections will have. If unchanged the default identity is an identity where category is set to 'client', type is set to 'pc' and name is set to 'Smack'.

Parameters:

identity -

getIdentityName

public String getIdentityName()

Returns the name of the client that will be returned when asked for the client identity in a disco request. The name could be any value you need to identity this client.

Returns:

the name of the client that will be returned when asked for the client identity in a disco request.

setIdentity

public void setIdentity(DiscoverInfo.Identity identity)

Sets the default identity the client will report.

Parameters:

identity -

getIdentity

public DiscoverInfo.Identity getIdentity()

Return the default identity of the client.

Returns:

the default identity.

getIdentityType

public String getIdentityType()

Returns the type of client that will be returned when asked for the client identity in a disco request. The valid types are defined by the category client. Follow this link to learn the possible types: Jabber::Registrar.

Returns:

the type of client that will be returned when asked for the client identity in a disco request.

addIdentity

public void addIdentity(DiscoverInfo.Identity identity)

Add an further identity to the client.

Parameters:

identity -

removeIdentity

public boolean removeIdentity(DiscoverInfo.Identity identity)

Remove an identity from the client. Note that the client needs at least one identity, the default identity, which can not be removed.

Parameters:

identity -

Returns:

true, if successful. Otherwise the default identity was given.

getIdentities

public Set<DiscoverInfo.Identity> getIdentities()

Returns all identities of this client as unmodifiable Collection.

Returns:

all identies as set

getInstanceFor

public static ServiceDiscoveryManager getInstanceFor(XMPPConnection connection)

Returns the ServiceDiscoveryManager instance associated with a given XMPPConnection.

Parameters:

connection - the connection used to look for the proper ServiceDiscoveryManager.

Returns:

the ServiceDiscoveryManager associated with a given XMPPConnection.

addDiscoverInfoTo

public void addDiscoverInfoTo(DiscoverInfo response)

Add discover info response data.

Parameters:

response - the discover info response packet

See Also:

XEP-30 Basic Protocol; Example 2

setNodeInformationProvider

public void setNodeInformationProvider(String node,
                                       NodeInformationProvider listener)

Sets the NodeInformationProvider responsible for providing information (ie items) related to a given node. Every time this client receives a disco request regarding the items of a given node, the provider associated to that node will be the responsible for providing the requested information.

In MUC, a node could be 'http://jabber.org/protocol/muc#rooms' which means that the NodeInformationProvider will provide information about the rooms where the user has joined.

Parameters:

node - the node whose items will be provided by the NodeInformationProvider.

listener - the NodeInformationProvider responsible for providing items related to the node.

removeNodeInformationProvider

public void removeNodeInformationProvider(String node)

Removes the NodeInformationProvider responsible for providing information (ie items) related to a given node. This means that no more information will be available for the specified node. In MUC, a node could be 'http://jabber.org/protocol/muc#rooms' which means that the NodeInformationProvider will provide information about the rooms where the user has joined.

Parameters:

node - the node to remove the associated NodeInformationProvider.

getFeatures

public List<String> getFeatures()

Returns the supported features by this XMPP entity.

The result is a copied modifiable list of the original features.

Returns:

a List of the supported features by this XMPP entity.

addFeature

public void addFeature(String feature)

Registers that a new feature is supported by this XMPP entity. When this client is queried for its information the registered features will be answered.

Since no stanza is actually sent to the server it is safe to perform this operation before logging to the server. In fact, you may want to configure the supported features before logging to the server so that the information is already available if it is required upon login.

Parameters:

feature - the feature to register as supported.

removeFeature

public void removeFeature(String feature)

Removes the specified feature from the supported features by this XMPP entity.

Since no stanza is actually sent to the server it is safe to perform this operation before logging to the server.

Parameters:

feature - the feature to remove from the supported features.

includesFeature

public boolean includesFeature(String feature)

Returns true if the specified feature is registered in the ServiceDiscoveryManager.

Parameters:

feature - the feature to look for.

Returns:

a boolean indicating if the specified featured is registered or not.

setExtendedInfo

public void setExtendedInfo(DataForm info)

Registers extended discovery information of this XMPP entity. When this client is queried for its information this data form will be returned as specified by XEP-0128.

Since no stanza is actually sent to the server it is safe to perform this operation before logging to the server. In fact, you may want to configure the extended info before logging to the server so that the information is already available if it is required upon login.

Parameters:

info - the data form that contains the extend service discovery information.

getExtendedInfo

public DataForm getExtendedInfo()

Returns the data form that is set as extended information for this Service Discovery instance (XEP-0128).

Returns:

the data form

See Also:

XEP-128: Service Discovery Extensions

getExtendedInfoAsList

public List<ExtensionElement> getExtendedInfoAsList()

Returns the data form as List of PacketExtensions, or null if no data form is set. This representation is needed by some classes (e.g. EntityCapsManager, NodeInformationProvider)

Returns:

the data form as List of PacketExtensions

removeExtendedInfo

public void removeExtendedInfo()

Removes the data form containing extended service discovery information from the information returned by this XMPP entity.

Since no stanza is actually sent to the server it is safe to perform this operation before logging to the server.

discoverInfo

public DiscoverInfo discoverInfo(Jid entityID)
                          throws SmackException.NoResponseException,
                                 XMPPException.XMPPErrorException,
                                 SmackException.NotConnectedException,
                                 InterruptedException

Returns the discovered information of a given XMPP entity addressed by its JID. Use null as entityID to query the server

Parameters:

entityID - the address of the XMPP entity or null.

Returns:

the discovered information.

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

discoverInfo

public DiscoverInfo discoverInfo(Jid entityID,
                                 String node)
                          throws SmackException.NoResponseException,
                                 XMPPException.XMPPErrorException,
                                 SmackException.NotConnectedException,
                                 InterruptedException

Returns the discovered information of a given XMPP entity addressed by its JID and note attribute. Use this message only when trying to query information which is not directly addressable.

Parameters:

entityID - the address of the XMPP entity.

node - the optional attribute that supplements the 'jid' attribute.

Returns:

the discovered information.

Throws:

XMPPException.XMPPErrorException - if the operation failed for some reason.

SmackException.NoResponseException - if there was no response from the server.

SmackException.NotConnectedException

InterruptedException

See Also:

XEP-30 Basic Protocol, XEP-30 Info Nodes

discoverItems

public DiscoverItems discoverItems(Jid entityID)
                            throws SmackException.NoResponseException,
                                   XMPPException.XMPPErrorException,
                                   SmackException.NotConnectedException,
                                   InterruptedException

Returns the discovered items of a given XMPP entity addressed by its JID.

Parameters:

entityID - the address of the XMPP entity.

Returns:

the discovered information.

Throws:

XMPPException.XMPPErrorException - if the operation failed for some reason.

SmackException.NoResponseException - if there was no response from the server.

SmackException.NotConnectedException

InterruptedException

discoverItems

public DiscoverItems discoverItems(Jid entityID,
                                   String node)
                            throws SmackException.NoResponseException,
                                   XMPPException.XMPPErrorException,
                                   SmackException.NotConnectedException,
                                   InterruptedException

Returns the discovered items of a given XMPP entity addressed by its JID and note attribute. Use this message only when trying to query information which is not directly addressable.

Parameters:

entityID - the address of the XMPP entity.

node - the optional attribute that supplements the 'jid' attribute.

Returns:

the discovered items.

Throws:

XMPPException.XMPPErrorException - if the operation failed for some reason.

SmackException.NoResponseException - if there was no response from the server.

SmackException.NotConnectedException

InterruptedException

canPublishItems

@Deprecated
public boolean canPublishItems(Jid entityID)
                                    throws SmackException.NoResponseException,
                                           XMPPException.XMPPErrorException,
                                           SmackException.NotConnectedException,
                                           InterruptedException

Deprecated. The disco-publish feature was removed from XEP-0030 in 2008 in favor of XEP-0060: Publish-Subscribe.

Returns true if the server supports publishing of items. A client may wish to publish items to the server so that the server can provide items associated to the client. These items will be returned by the server whenever the server receives a disco request targeted to the bare address of the client (i.e. user@host.com).

Parameters:

entityID - the address of the XMPP entity.

Returns:

true if the server supports publishing of items.

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

canPublishItems

@Deprecated
public static boolean canPublishItems(DiscoverInfo info)

Deprecated. The disco-publish feature was removed from XEP-0030 in 2008 in favor of XEP-0060: Publish-Subscribe.

Returns true if the server supports publishing of items. A client may wish to publish items to the server so that the server can provide items associated to the client. These items will be returned by the server whenever the server receives a disco request targeted to the bare address of the client (i.e. user@host.com).

Parameters:

info - the discover info stanza to check.

Returns:

true if the server supports publishing of items.

publishItems

@Deprecated
public void publishItems(Jid entityID,
                                     DiscoverItems discoverItems)
                              throws SmackException.NoResponseException,
                                     XMPPException.XMPPErrorException,
                                     SmackException.NotConnectedException,
                                     InterruptedException

Deprecated. The disco-publish feature was removed from XEP-0030 in 2008 in favor of XEP-0060: Publish-Subscribe.

Publishes new items to a parent entity. The item elements to publish MUST have at least a 'jid' attribute specifying the Entity ID of the item, and an action attribute which specifies the action being taken for that item. Possible action values are: "update" and "remove".

Parameters:

entityID - the address of the XMPP entity.

discoverItems - the DiscoveryItems to publish.

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

publishItems

@Deprecated
public void publishItems(Jid entityID,
                                     String node,
                                     DiscoverItems discoverItems)
                              throws SmackException.NoResponseException,
                                     XMPPException.XMPPErrorException,
                                     SmackException.NotConnectedException,
                                     InterruptedException

Deprecated. The disco-publish feature was removed from XEP-0030 in 2008 in favor of XEP-0060: Publish-Subscribe.

Publishes new items to a parent entity and node. The item elements to publish MUST have at least a 'jid' attribute specifying the Entity ID of the item, and an action attribute which specifies the action being taken for that item. Possible action values are: "update" and "remove".

Parameters:

entityID - the address of the XMPP entity.

node - the attribute that supplements the 'jid' attribute.

discoverItems - the DiscoveryItems to publish.

Throws:

XMPPException.XMPPErrorException - if the operation failed for some reason.

SmackException.NoResponseException - if there was no response from the server.

SmackException.NotConnectedException

InterruptedException

serverSupportsFeature

public boolean serverSupportsFeature(CharSequence feature)
                              throws SmackException.NoResponseException,
                                     XMPPException.XMPPErrorException,
                                     SmackException.NotConnectedException,
                                     InterruptedException

Returns true if the server supports the given feature.

Parameters:

feature -

Returns:

true if the server supports the given feature.

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

Since:

4.1

serverSupportsFeatures

public boolean serverSupportsFeatures(CharSequence... features)
                               throws SmackException.NoResponseException,
                                      XMPPException.XMPPErrorException,
                                      SmackException.NotConnectedException,
                                      InterruptedException

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

serverSupportsFeatures

public boolean serverSupportsFeatures(Collection<? extends CharSequence> features)
                               throws SmackException.NoResponseException,
                                      XMPPException.XMPPErrorException,
                                      SmackException.NotConnectedException,
                                      InterruptedException

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

accountSupportsFeatures

public boolean accountSupportsFeatures(CharSequence... features)
                                throws SmackException.NoResponseException,
                                       XMPPException.XMPPErrorException,
                                       SmackException.NotConnectedException,
                                       InterruptedException

Check if the given features are supported by the connection account. This means that the discovery information lookup will be performed on the bare JID of the connection managed by this ServiceDiscoveryManager.

Parameters:

features - the features to check

Returns:

true if all features are supported by the connection account, false otherwise

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

Since:

4.2.2

accountSupportsFeatures

public boolean accountSupportsFeatures(Collection<? extends CharSequence> features)
                                throws SmackException.NoResponseException,
                                       XMPPException.XMPPErrorException,
                                       SmackException.NotConnectedException,
                                       InterruptedException

Check if the given collection of features are supported by the connection account. This means that the discovery information lookup will be performed on the bare JID of the connection managed by this ServiceDiscoveryManager.

Parameters:

features - a collection of features

Returns:

true if all features are supported by the connection account, false otherwise

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

Since:

4.2.2

supportsFeature

public boolean supportsFeature(Jid jid,
                               CharSequence feature)
                        throws SmackException.NoResponseException,
                               XMPPException.XMPPErrorException,
                               SmackException.NotConnectedException,
                               InterruptedException

Queries the remote entity for it's features and returns true if the given feature is found.

Parameters:

jid - the JID of the remote entity

feature -

Returns:

true if the entity supports the feature, false otherwise

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

supportsFeatures

public boolean supportsFeatures(Jid jid,
                                CharSequence... features)
                         throws SmackException.NoResponseException,
                                XMPPException.XMPPErrorException,
                                SmackException.NotConnectedException,
                                InterruptedException

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

supportsFeatures

public boolean supportsFeatures(Jid jid,
                                Collection<? extends CharSequence> features)
                         throws SmackException.NoResponseException,
                                XMPPException.XMPPErrorException,
                                SmackException.NotConnectedException,
                                InterruptedException

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

findServicesDiscoverInfo

public List<DiscoverInfo> findServicesDiscoverInfo(String feature,
                                                   boolean stopOnFirst,
                                                   boolean useCache)
                                            throws SmackException.NoResponseException,
                                                   XMPPException.XMPPErrorException,
                                                   SmackException.NotConnectedException,
                                                   InterruptedException

Find all services under the users service that provide a given feature.

Parameters:

feature - the feature to search for

stopOnFirst - if true, stop searching after the first service was found

useCache - if true, query a cache first to avoid network I/O

Returns:

a possible empty list of services providing the given feature

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

findServicesDiscoverInfo

public List<DiscoverInfo> findServicesDiscoverInfo(String feature,
                                                   boolean stopOnFirst,
                                                   boolean useCache,
                                                   Map<? super Jid,Exception> encounteredExceptions)
                                            throws SmackException.NoResponseException,
                                                   XMPPException.XMPPErrorException,
                                                   SmackException.NotConnectedException,
                                                   InterruptedException

Find all services under the users service that provide a given feature.

Parameters:

feature - the feature to search for

stopOnFirst - if true, stop searching after the first service was found

useCache - if true, query a cache first to avoid network I/O

encounteredExceptions - an optional map which will be filled with the exceptions encountered

Returns:

a possible empty list of services providing the given feature

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

Since:

4.2.2

findServicesDiscoverInfo

public List<DiscoverInfo> findServicesDiscoverInfo(DomainBareJid serviceName,
                                                   String feature,
                                                   boolean stopOnFirst,
                                                   boolean useCache,
                                                   Map<? super Jid,Exception> encounteredExceptions)
                                            throws SmackException.NoResponseException,
                                                   XMPPException.XMPPErrorException,
                                                   SmackException.NotConnectedException,
                                                   InterruptedException

Find all services under a given service that provide a given feature.

Parameters:

serviceName - the service to query

feature - the feature to search for

stopOnFirst - if true, stop searching after the first service was found

useCache - if true, query a cache first to avoid network I/O

encounteredExceptions - an optional map which will be filled with the exceptions encountered

Returns:

a possible empty list of services providing the given feature

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

Since:

4.3.0

findServices

public List<DomainBareJid> findServices(String feature,
                                        boolean stopOnFirst,
                                        boolean useCache)
                                 throws SmackException.NoResponseException,
                                        XMPPException.XMPPErrorException,
                                        SmackException.NotConnectedException,
                                        InterruptedException

Find all services under the users service that provide a given feature.

Parameters:

feature - the feature to search for

stopOnFirst - if true, stop searching after the first service was found

useCache - if true, query a cache first to avoid network I/O

Returns:

a possible empty list of services providing the given feature

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

findService

public DomainBareJid findService(String feature,
                                 boolean useCache,
                                 String category,
                                 String type)
                          throws SmackException.NoResponseException,
                                 XMPPException.XMPPErrorException,
                                 SmackException.NotConnectedException,
                                 InterruptedException

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

findService

public DomainBareJid findService(String feature,
                                 boolean useCache)
                          throws SmackException.NoResponseException,
                                 XMPPException.XMPPErrorException,
                                 SmackException.NotConnectedException,
                                 InterruptedException

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

addEntityCapabilitiesChangedListener

public boolean addEntityCapabilitiesChangedListener(EntityCapabilitiesChangedListener entityCapabilitiesChangedListener)

addDiscoInfoLookupShortcutMechanism

public static void addDiscoInfoLookupShortcutMechanism(DiscoInfoLookupShortcutMechanism discoInfoLookupShortcutMechanism)

removeDiscoInfoLookupShortcutMechanism

public static void removeDiscoInfoLookupShortcutMechanism(DiscoInfoLookupShortcutMechanism discoInfoLookupShortcutMechanism)