+This section details the usage of an API designed for accessing an XMPP based +implementation of a publish and subscribe +based messaging system. It has functionality for creation, configuration of, +subscription and publishing to pubsub nodes.
+ +
+ +Description
+Allowed users may create and configure pubsub nodes. There are two types of nodes that can be created, +leaf nodes and collection nodes. +
+ +In order to create a node you will need to first create an instance of PubSubManager. There +are several options for node creation which range from creating an instant node, default configuration, or +a fully configured node.
+ +Examples
+
+Create an instant node:
+
++ +Create a node with default configuration and then configure it:+ // Create a pubsub manager using an existing XMPPConnection + PubSubManager mgr = new PubSubManager(con); + + // Create the node + LeafNode leaf = mgr.createNode(); ++
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+
+ // Create the node
+ LeafNode leaf = mgr.createNode("testNode");
+ ConfigureForm form = new ConfigureForm(FormType.submit);
+ form.setAccessModel(AccessModel.open);
+ form.setDeliverPayloads(false);
+ form.setNotifyRetract(true);
+ form.setPersistentItems(true);
+ form.setPublishModel(PublishModel.open);
+
+ leaf.sendConfigurationForm(form);
+
+
+
+Create and configure a node:
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+
+ // Create the node
+ ConfigureForm form = new ConfigureForm(FormType.submit);
+ form.setAccessModel(AccessModel.open);
+ form.setDeliverPayloads(false);
+ form.setNotifyRetract(true);
+ form.setPersistentItems(true);
+ form.setPublishModel(PublishModel.open);
+ LeafNode leaf = mgr.createNode("testNode", form);
+
+
+
++ +Description
+This section deals with the publish portion of pubsub. + +Usage of a node typically involves either sending or receiving data, referred to as items. +Depending on the context of the nodes usage, the item being sent to it can have different +properties. + +It can contain application data known as payload, or the publisher may choose to supply +meaningful unique id's. Determination of an items acceptable properties is defined by a +combination of node configuration and its purpose. +
+ +Usage+To publish to a node, you will have to either create or retrieve an existing node and then +create and send items to that node. The ability for any given person to publish to the node +will be dependent on its configuration. +
+ +Examples
+In this example we publish an item to a node that does not take payload:
+
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+
+ // Get the node
+ LeafNode node = mgr.getNode("testNode");
+
+ // Publish an Item, let service set the id
+ node.send(new Item());
+
+ // Publish an Item with the specified id
+ node.send(new Item("123abc"));
+
+
+In this example we publish an item to a node that does take payload:
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+
+ // Get the node
+ LeafNode node = mgr.getNode("testNode");
+
+ // Publish an Item with payload
+ node.send(new PayloadItem("test" + System.currentTimeMillis(),
+ new SimplePayload("book", "pubsub:test:book", "Two Towers
+
+
++ +Description
+This section deals with the subscribe portion of pubsub. + +As mentioned in the last section, usage of a node typically involves either sending or receiving +items. Subscribers are interested in being notified when items are published to the pubsub +node. These items may or may not have application specific data (payload), as that +is dependent on the context in which the node is being used. +
+ +Usage+To get messages asynchronously when items are published to a node, you will have to +
+Please note that you should register the listener before subscribing so that all messages +sent after subscribing are received. If done in the reverse order, messages that are sent +after subscribing but before registering a listener may not be processed as expected. +
+ +Examples
+
+In this example we can see how to create a listener and register it and then subscribe for
+messages.
+
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+
+ // Get the node
+ LeafNode node = mgr.getNode("testNode");
+
+ node.addItemEventListener(new ItemEventCoordinator<Item>());
+ node.subscribe(myJid);
+
+
+
+Where the listener is defined like so:
+
+++ +In addition to receiving published items, there are notifications for several other +events that occur on a node as well. ++ + class ItemEventCoordinator+implements ItemEventListener + { + @Override + public void handlePublishedItems(ItemPublishEvent items) + { + System.out.println("Item count: " + items.getItems().size()); + System.out.println(items); + } + } +
+In this example we can see how to create a listener, register it and then subscribe for
+item deletion messages.
+
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+
+ // Get the node
+ LeafNode node = mgr.getNode("testNode");
+
+ node.addItemDeleteListener(new ItemDeleteCoordinator<Item>());
+ node.subscribe(myJid);
+ node.deleteItem("id_one");
+
+
+
+Where the handler is defined like so:
+
+++In this example we can see how to create a listener, register it and then subscribe for +node configuration messages.+ + class ItemDeleteCoordinator implements ItemDeleteListener++ { + @Override + public void handleDeletedItems(ItemDeleteEvent items) + { + System.out.println("Item count: " + items.getItemIds().size()); + System.out.println(items); + } + + @Override + public void handlePurge() + { + System.out.println("All items have been deleted from node"); + } + } +
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+
+ // Get the node
+ Node node = mgr.getNode("testNode");
+
+ node.addConfigurationListener(new NodeConfigCoordinator());
+ node.subscribe(myJid);
+
+ ConfigureForm form = new ConfigureForm(FormType.submit);
+ form.setAccessModel(AccessModel.open);
+ form.setDeliverPayloads(false);
+ form.setNotifyRetract(true);
+ form.setPersistentItems(true);
+ form.setPublishModel(PublishModel.open);
+
+ node.sendConfigurationForm(form);
+
+
+
+
+Where the handler is defined like so:
+
++++ + class NodeConfigCoordinator implements NodeConfigListener++ { + @Override + public void handleNodeConfiguration(ConfigurationEvent config) + { + System.out.println("New configuration"); + System.out.println(config.getConfiguration()); + } + } +
+ +Description
+ +When persistent nodes are used, the subscription and registration methods described in the last section +will not enable the retrieval of items that already exist in the node. This section deals with the +specific methods for retrieving these items. + +There are several means of retrieving existing items. You can retrieve all items at once, the last N +items, or the items specified by a collection of id's. + +Please note that the service may, according to the pubsub specification, reply with a list of items +that contains only the item id's (no payload) to save on bandwidth. This will not occur when the id's +are specified since this is the means of guaranteeing retrieval of payload.
+ +Usage+ +To synchronously retrieve existing items from a persistent node, you will have to get an instance +of a LeafNode and call one of the retrieve methods. +
+ +Examples
+
+In this example we can see how to retrieve the existing items from a node:
+
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+
+ // Get the node
+ LeafNode node = mgr.getNode("testNode");
+
+ Collection<? extends Item> items = node.getItems();
+
+
+
+
+In this example we can see how to retrieve the last N existing items:
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+
+ // Get the node
+ LeafNode node = mgr.getNode("testNode");
+
+ List<? extends Item> items = node.getItems(100);
+
+
+
+In this example we can see how to retrieve the specified existing items:
+
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+
+ // Get the node
+ LeafNode node = mgr.getNode("testNode");
+ Collection<String> ids = new ArrayList<String>(3);
+ ids.add("1");
+ ids.add("3");
+ ids.add("4");
+
+ List<? extends Item> items = node.getItems(ids);
+
+
+
++ +Description
+ +A user may want to query a server or node for a variety of pubsub related information.
+ +Usage+ +To retrieve information, a user will simply use either the PubSubManager +or Node classes depending on what type of information is required. + +Examples
+
+In this example we can see how to get pubsub capabilities:
+
++ +In this example we can see how to get pubsub subscriptions for all nodes:+ // Create a pubsub manager using an existing XMPPConnection + PubSubManager mgr = new PubSubManager(con); + + // Get the pubsub features that are supported + DiscoverInfo supportedFeatures = mgr.getSupportedFeatures(); ++
++ +In this example we can see how to get all affiliations for the users bare JID on the pubsub service:+ // Create a pubsub manager using an existing XMPPConnection + PubSubManager mgr = new PubSubManager(con); + + // Get all the subscriptions in the pubsub service + List<Subscription> subscriptions = mgr.getSubscriptions(); ++
++ +In this example we can see how to get information about the node:+ // Create a pubsub manager using an existing XMPPConnection + PubSubManager mgr = new PubSubManager(con); + + // Get the affiliations for the users bare JID + List<Affiliation> affiliations = mgr.getAffiliations(); ++
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+ Node node = mgr.getNode("testNode");
+
+ // Get the node information
+ DiscoverInfo nodeInfo = node.discoverInfo();
+
+
+
+In this example we can see how to discover the node items:
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+ Node node = mgr.getNode("testNode");
+
+ // Discover the node items
+ DiscoverItems nodeItems = node.discoverItems();
+
+
+
+In this example we can see how to get node subscriptions:
+
+ // Create a pubsub manager using an existing XMPPConnection
+ PubSubManager mgr = new PubSubManager(con);
+ Node node = mgr.getNode("testNode");
+
+ // Discover the node subscriptions
+ List<Subscription> subscriptions = node.getSubscriptions();
+
+
+