Smack

org.jivesoftware.smackx
Class ServiceDiscoveryManager

java.lang.Object
  extended by org.jivesoftware.smackx.ServiceDiscoveryManager

public class ServiceDiscoveryManager
extends java.lang.Object

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.

Author:
Gaston Dombiak

Constructor Summary
ServiceDiscoveryManager(Connection connection)
          Creates a new ServiceDiscoveryManager for a given Connection.
 
Method Summary
 void addDiscoverInfoTo(DiscoverInfo response)
          Add discover info response data.
 void addFeature(java.lang.String feature)
          Registers that a new feature is supported by this XMPP entity.
static boolean canPublishItems(DiscoverInfo info)
          Returns true if the server supports publishing of items.
 boolean canPublishItems(java.lang.String entityID)
          Returns true if the server supports publishing of items.
 DiscoverInfo discoverInfo(java.lang.String entityID)
          Returns the discovered information of a given XMPP entity addressed by its JID.
 DiscoverInfo discoverInfo(java.lang.String entityID, java.lang.String node)
          Returns the discovered information of a given XMPP entity addressed by its JID and note attribute.
 DiscoverItems discoverItems(java.lang.String entityID)
          Returns the discovered items of a given XMPP entity addressed by its JID.
 DiscoverItems discoverItems(java.lang.String entityID, java.lang.String node)
          Returns the discovered items of a given XMPP entity addressed by its JID and note attribute.
 DataForm getExtendedInfo()
          Returns the data form that is set as extended information for this Service Discovery instance (XEP-0128)
 java.util.List<PacketExtension> getExtendedInfoAsList()
          Returns the data form as List of PacketExtensions, or null if no data form is set.
 java.util.Iterator<java.lang.String> getFeatures()
          Returns the supported features by this XMPP entity.
 java.util.List<java.lang.String> getFeaturesList()
          Returns the supported features by this XMPP entity.
static java.util.List<DiscoverInfo.Identity> getIdentities()
          Returns all identities of this client as unmodifiable Collection
static java.lang.String getIdentityName()
          Returns the name of the client that will be returned when asked for the client identity in a disco request.
static java.lang.String getIdentityType()
          Returns the type of client that will be returned when asked for the client identity in a disco request.
static ServiceDiscoveryManager getInstanceFor(Connection connection)
          Returns the ServiceDiscoveryManager instance associated with a given Connection.
 boolean includesFeature(java.lang.String feature)
          Returns true if the specified feature is registered in the ServiceDiscoveryManager.
 void publishItems(java.lang.String entityID, DiscoverItems discoverItems)
          Publishes new items to a parent entity.
 void publishItems(java.lang.String entityID, java.lang.String node, DiscoverItems discoverItems)
          Publishes new items to a parent entity and node.
 void removeExtendedInfo()
          Removes the data form containing extended service discovery information from the information returned by this XMPP entity.
 void removeFeature(java.lang.String feature)
          Removes the specified feature from the supported features by this XMPP entity.
 void removeNodeInformationProvider(java.lang.String node)
          Removes the NodeInformationProvider responsible for providing information (ie items) related to a given node.
 void setEntityCapsManager(EntityCapsManager manager)
          Loads the ServiceDiscoveryManager with an EntityCapsManger that speeds up certain lookups
 void setExtendedInfo(DataForm info)
          Registers extended discovery information of this XMPP entity.
static void setIdentityName(java.lang.String name)
          Sets the name of the client that will be returned when asked for the client identity in a disco request.
static void setIdentityType(java.lang.String type)
          Sets the type of client that will be returned when asked for the client identity in a disco request.
 void setNodeInformationProvider(java.lang.String node, NodeInformationProvider listener)
          Sets the NodeInformationProvider responsible for providing information (ie items) related to a given node.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ServiceDiscoveryManager

public ServiceDiscoveryManager(Connection connection)
Creates a new ServiceDiscoveryManager for a given Connection. This means that the service manager will respond to any service discovery request that the connection may receive.

Parameters:
connection - the connection to which a ServiceDiscoveryManager is going to be created.
Method Detail

getInstanceFor

public static ServiceDiscoveryManager getInstanceFor(Connection connection)
Returns the ServiceDiscoveryManager instance associated with a given Connection.

Parameters:
connection - the connection used to look for the proper ServiceDiscoveryManager.
Returns:
the ServiceDiscoveryManager associated with a given Connection.

getIdentityName

public static java.lang.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.

setIdentityName

public static void setIdentityName(java.lang.String name)
Sets 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.

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

getIdentityType

public static java.lang.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.

setIdentityType

public static void setIdentityType(java.lang.String type)
Sets 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.

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

getIdentities

public static java.util.List<DiscoverInfo.Identity> getIdentities()
Returns all identities of this client as unmodifiable Collection

Returns:

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(java.lang.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(java.lang.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 java.util.Iterator<java.lang.String> getFeatures()
Returns the supported features by this XMPP entity.

Returns:
an Iterator on the supported features by this XMPP entity.

getFeaturesList

public java.util.List<java.lang.String> getFeaturesList()
Returns the supported features by this XMPP entity.

Returns:
a copy of the List on the supported features by this XMPP entity.

addFeature

public void addFeature(java.lang.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 packet 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(java.lang.String feature)
Removes the specified feature from the supported features by this XMPP entity.

Since no packet 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(java.lang.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 packet 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:
See Also:
XEP-128: Service Discovery Extensions

getExtendedInfoAsList

public java.util.List<PacketExtension> 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:

removeExtendedInfo

public void removeExtendedInfo()
Removes the data form containing extended service discovery information from the information returned by this XMPP entity.

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


discoverInfo

public DiscoverInfo discoverInfo(java.lang.String entityID)
                          throws XMPPException
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 - if the operation failed for some reason.

discoverInfo

public DiscoverInfo discoverInfo(java.lang.String entityID,
                                 java.lang.String node)
                          throws XMPPException
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 - if the operation failed for some reason.
See Also:
XEP-30 Basic Protocol, XEP-30 Info Nodes

discoverItems

public DiscoverItems discoverItems(java.lang.String entityID)
                            throws XMPPException
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 - if the operation failed for some reason.

discoverItems

public DiscoverItems discoverItems(java.lang.String entityID,
                                   java.lang.String node)
                            throws XMPPException
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 - if the operation failed for some reason.

canPublishItems

public boolean canPublishItems(java.lang.String entityID)
                        throws XMPPException
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 - if the operation failed for some reason.

canPublishItems

public static boolean canPublishItems(DiscoverInfo info)
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:
DiscoverInfo - the discover info packet to check.
Returns:
true if the server supports publishing of items.

publishItems

public void publishItems(java.lang.String entityID,
                         DiscoverItems discoverItems)
                  throws XMPPException
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 - if the operation failed for some reason.

publishItems

public void publishItems(java.lang.String entityID,
                         java.lang.String node,
                         DiscoverItems discoverItems)
                  throws XMPPException
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 - if the operation failed for some reason.

setEntityCapsManager

public void setEntityCapsManager(EntityCapsManager manager)
Loads the ServiceDiscoveryManager with an EntityCapsManger that speeds up certain lookups

Parameters:
manager -

Smack

Copyright © 2003-2007 Jive Software.