From ad7c383943243a85e32f4bc5f5781cc285f338cd Mon Sep 17 00:00:00 2001 From: Gaston Dombiak Date: Sat, 18 Oct 2003 21:04:39 +0000 Subject: [PATCH] Initial check-in git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@2149 b35dd754-fafc-0310-a699-88a17e54d16e --- documentation/extensions/disco.html | 193 ++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 documentation/extensions/disco.html diff --git a/documentation/extensions/disco.html b/documentation/extensions/disco.html new file mode 100644 index 000000000..d2aaf719d --- /dev/null +++ b/documentation/extensions/disco.html @@ -0,0 +1,193 @@ + + +Service Discovery + + + + + +
Service Discovery

+ +The service discovery extension allows to discover items and information about XMPP +entities. Follow these links to learn how to use this extension. + +

+JEP related: JEP-30 + +
+ +
Manage XMPP entity features

+ +Description

+ +Any XMPP entity may receive a discovery request and must answer with its associated items or +information. Therefore, your Smack client may receive a discovery request that must respond +to (i.e., if your client supports XHTML-IM). This extension automatically responds to a +discovery request with the information that you previously configured.

+ +

+Note: This version only allows you to configure supported features by the client. In future +version we will add the ability to configure associated items within the Smack client.

+ +Usage

+ +In order to configure the supported features by your client you should first obtain the +ServiceDiscoveryManager associated with your XMPPConnection. To get your ServiceDiscoveryManager +send getInstanceFor(connection) to the class ServiceDiscoveryManager where +connection is your XMPPConnection.

+ +

Once you have your ServiceDiscoveryManager you will be able to manage the supported features. To +register a new feature send addFeature(feature) to your ServiceDiscoveryManager +where feature is a String that represents the supported feature. To remove a supported feature send +removeFeature(feature) to your ServiceDiscoveryManager where feature is a +String that represents the feature to remove.

+ +Examples

+ +In this example we can see how to add and remove supported features:
+

+
      // Obtain the ServiceDiscoveryManager associated with my XMPPConnection
+      ServiceDiscoveryManager discoManager = ServiceDiscoveryManager.getInstanceFor(connection);
+      
+      // Register that a new feature is supported by this XMPP entity
+      discoManager.addFeature(namespace1);
+
+      // Remove the specified feature from the supported features by this XMPP entity
+      discoManager.removeFeature(namespace2);
+
+
+ +
+ +
Discover items associated with an XMPP entity

+ +Description

+ +In order to obtain information about a specific item you have to first discover the items available +in an XMPP entity.

+ +Usage

+ +

Once you have your ServiceDiscoveryManager you will be able to discover items associated with +an XMPP entity. To discover the items of a given XMPP entity send discoverItems(entityID) +to your ServiceDiscoveryManager where entityID is the ID of the entity. The message +discoverItems(entityID) will answer an instance of DiscoverItems that contains +the discovered items.

+ +Examples

+ +In this example we can see how to discover the items associated with an online catalog service:
+

+
      // Obtain the ServiceDiscoveryManager associated with my XMPPConnection
+      ServiceDiscoveryManager discoManager = ServiceDiscoveryManager.getInstanceFor(connection);
+      
+      // Get the items of a given XMPP entity
+      // This example gets the items associated with online catalog service
+      DiscoverItems discoItems = discoManager.discoverItems("plays.shakespeare.lit");
+
+      // Get the discovered items of the queried XMPP entity
+      Iterator it = discoItems.getItems();
+      // Display the items of the remote XMPP entity
+      while (it.hasNext()) {
+          DiscoverItems.Item item = (DiscoverItems.Item) it.next();
+          System.out.println(item.getEntityID());
+          System.out.println(item.getNode());
+          System.out.println(item.getName());
+      }
+
+
+ +
+ +
Discover information about an XMPP entity

+ +Description

+ +Once you have discovered the entity ID and name of an item, you may want to find out more +about the item. The information desired generally is of two kinds: 1) The item's identity +and 2) The features offered by the item.

+ +

This information helps you determine what actions are possible with regard to this +item (registration, search, join, etc.) as well as specific feature types of interest, if +any (e.g., for the purpose of feature negotiation).

+ +Usage

+ +

Once you have your ServiceDiscoveryManager you will be able to discover information associated with +an XMPP entity. To discover the information of a given XMPP entity send discoverInfo(entityID) +to your ServiceDiscoveryManager where entityID is the ID of the entity. The message +discoverInfo(entityID) will answer an instance of DiscoverInfo that contains +the discovered information.

+ +Examples

+ +In this example we can see how to discover the information of a conference room:
+

+
      // Obtain the ServiceDiscoveryManager associated with my XMPPConnection
+      ServiceDiscoveryManager discoManager = ServiceDiscoveryManager.getInstanceFor(connection);
+      
+      // Get the information of a given XMPP entity
+      // This example gets the information of a conference room
+      DiscoverInfo discoInfo = discoManager.discoverInfo("balconyscene@plays.shakespeare.lit");
+
+      // Get the discovered identities of the remote XMPP entity
+      Iterator it = discoInfo.getIdentities();
+      // Display the identities of the remote XMPP entity
+      while (it.hasNext()) {
+          DiscoverInfo.Identity identity = (DiscoverInfo.Identity) it.next();
+          System.out.println(identity.getName());
+          System.out.println(identity.getType());
+          System.out.println(identity.getCategory());
+      }
+
+      // Check if room is password protected
+      discoInfo.containsFeature("muc_passwordprotected");
+
+
+ +
+ +
Publish publicly available items

+ +Description

+ +Publish your entity items to some kind of persistent storage. This enables other entities to query +that entity using the disco#items namespace and receive a result even when the entity being queried +is not online (or available).

+ +Usage

+ +

Once you have your ServiceDiscoveryManager you will be able to publish items to some kind of +persistent storage. To publish the items of a given XMPP entity you have to first create an instance +of DiscoverItems and configure it with the items to publish. Then you will have to +send publishItems(String entityID, DiscoverItems discoverItems) to your ServiceDiscoveryManager +where entityID is the address of the XMPP entity that will persist the items and discoverItems contains the items +to publish.

+ +Examples

+ +In this example we can see how to publish new items:
+

+
      // Obtain the ServiceDiscoveryManager associated with my XMPPConnection
+      ServiceDiscoveryManager discoManager = ServiceDiscoveryManager.getInstanceFor(connection);
+      
+      // Create a DiscoverItems with the items to publish
+      DiscoverItems itemsToPublish = new DiscoverItems();
+      DiscoverItems.Item itemToPublish = new DiscoverItems.Item("pubsub.shakespeare.lit");
+      itemToPublish.setName("Avatar");
+      itemToPublish.setNode("romeo/avatar");
+      itemToPublish.setAction(DiscoverItems.Item.UPDATE_ACTION);
+      itemsToPublish.addItem(itemToPublish);
+
+      // Publish the new items by sending them to the server
+      discoManager.publishItems("host", itemsToPublish);
+
+
+ + + \ No newline at end of file