Pubsub ====== This section details the usage of an API designed for accessing an XMPP based implementation of a [publish and subscribe](http://en.wikipedia.org/wiki/Publish/subscribe) based messaging system. It has functionality for creation, configuration of, subscription and publishing to pubsub nodes. * Node creation and configuration * Publishing to a node * Receiving pubsub messages * Retrieving persisted pubsub messages * Discover pubsub information **XEP related:** [XEP-0060](http://xmpp.org/extensions/xep-0060.html) Node creation and configuration ------------------------------- ### Description Allowed users may create and configure pubsub nodes. There are two types of nodes that can be created, leaf nodes and collection nodes. * Leaf Nodes - contains only messages * Collection Nodes - contains only nodes (both Leaf and Collection are allowed), but no messages The current version of this API only supports Leaf Nodes. There are many configuration options available for nodes, but the two main options are whether the node is **persistent** or not and whether it will deliver payload or not. ### Usage 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 pubsub manager using an existing XMPPConnection PubSubManager mgr = new PubSubManager(con); // Create the node LeafNode leaf = mgr.createNode(); ``` 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("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); ``` Publishing to a node -------------------- **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"))); ``` Receiving pubsub messages ------------------------- **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 * Get a node. * Create and register a listener. * Subscribe to the node. 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: ``` class ItemEventCoordinator implements ItemEventListener { @Override public void handlePublishedItems(ItemPublishEvent items) { System.out.println("Item count: " + System.out.println(items); } } ``` In addition to receiving published items, there are notifications for several other events that occur on a node as well. * Deleting items or purging all items from a node * Changing the node configuration 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: ``` 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"); } } ``` In this example we can see how to create a listener, register it and then subscribe for node configuration messages. ``` // 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()); } } ``` Retrieving persisted pubsub messages ------------------------------------ **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 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 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 items = node.getItems(ids); ``` Discover pubsub information --------------------------- **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: ``` // 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 pubsub subscriptions for all nodes: ``` // 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 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 the affiliations for the users bare JID List<Affiliation;> affiliations = mgr.getAffiliations(); ``` 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); 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(); ```