Package org.jivesoftware.smackx.pubsub
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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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);
In this example we can see how to create a listener, register it and then subscribe for node configuration messages.
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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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);
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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(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 = PubSubManager.getInstanceFor(con);
Node node = mgr.getNode("testNode");
// Discover the node subscriptions
List<Subscription> subscriptions = node.getSubscriptions();
- See Also:
-
ClassDescriptionThis enumeration represents the access models for the PubSub node as defined in the PubSub specification section 16.4.3.Represents a affiliation between a user and a node, where the
Affiliation.Type
defines the type of affiliation.Represents the affiliations element of the reply to a request for affiliations.This enumeration represents the children association policy for associating leaf nodes with collection nodes as defined in the PubSub specification section 16.4.3.Represents the configuration element of a PubSub message event which associates a configuration form to the node which was configured.This enumeration represents all the fields of a node configuration form.This interface definesExtensionElement
implementations that contain other extensions.Represents the top level element of a PubSub event extension.This enumeration defines the possible event types that are supported within PubSub event messages.Generic stanza extension which represents any PubSub form that is parsed from the incoming stream or being sent out to the server.The types of forms supported by the PubSub specification.Represents a request to subscribe to a node.This class represents an item that has been, or will be published to a PubSub node.Represents an event in which items have been deleted from the node.ItemPublishEvent<T extends Item>Represents an event generated by an item(s) being published to a node.These are the options for the node configuration settingFillableConfigureForm.setItemReply(ItemReply)
, which defines who should receive replies to items.This class is used for multiple purposes.The main class for the majority of PubSub functionality.This class translates low level item deletion events into api level objects for user consumption.This class translates low level item publication events into api level objects for user consumption.This class translates low level node configuration events into api level objects for user consumption.A class which represents a common element within the pubsub defined schemas.Defines the available types of nodes.Specify the delivery style for event notifications.A stanza extension representing the options element.PayloadItem<E extends XmlElement>This class represents an item that has been, or will be published to a pubsub node.Defines the possible valid presence states for node subscription viaSubscribeFormReader.getShowValues()
.PublishItem<T extends Item>Represents a request to publish an item(s) to a specific node.Determines who may publish to a node.Defines all the possible element types as defined for all the pubsub schemas in all 3 namespaces.The features a PubSub service may provides.This is the starting point for access to the pubsub service.Represents and item that has been deleted from a node.The default payload representation forPayloadItem.getPayload()
.Represents a request to subscribe to a node.Defines the possible field options for a subscribe options form as defined by Section 16.4.2.Represents a subscription to node for both requests and replies.Base class to represents events that are associated to subscriptions.Represents the element holding the list of subscription elements.Represents an unsubscribe element.