mirror of
https://github.com/vanitasvitae/Smack.git
synced 2024-11-22 20:12:07 +01:00
SMACK-272 Add support for XEP-0060 (pubsub)
git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@11345 b35dd754-fafc-0310-a699-88a17e54d16e
This commit is contained in:
rcollier
parent
a1e791172c
commit
92ba2d7f33
1 changed files with 448 additions and 0 deletions
448
documentation/extensions/pubsub.html
Normal file
448
documentation/extensions/pubsub.html
Normal file
|
|
@ -0,0 +1,448 @@
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<title>PubSub</title>
|
||||||
|
<link rel="stylesheet" type="text/css" href="style.css" />
|
||||||
|
</head>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
|
||||||
|
<div class="header">Pubsub</div><p>
|
||||||
|
This section details the usage of an API designed for accessing an XMPP based
|
||||||
|
implementation of a <a href="http://en.wikipedia.org/wiki/Publish/subscribe">publish and subscribe</a>
|
||||||
|
based messaging system. It has functionality for creation, configuration of,
|
||||||
|
subscription and publishing to pubsub nodes.<p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><a href="#create">Node creation and configuration</a></li>
|
||||||
|
<li><a href="#publish">Publishing to a node</a></li>
|
||||||
|
<li><a href="#subscribe">Receiving pubsub messages</a></li>
|
||||||
|
<li><a href="#retrieve">Retrieving persisted pubsub messages</a></li>
|
||||||
|
<li><a href="#discopubsub">Discover pubsub information</a></li>
|
||||||
|
</ul>
|
||||||
|
<b>XEP related:</b> <a href="http://xmpp.org/extensions/xep-0060.html">XEP-0060</a>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<div class="subheader"><a name="create">Node creation and configuration</a></div><p>
|
||||||
|
|
||||||
|
<b>Description</b><p>
|
||||||
|
Allowed users may create and configure pubsub nodes. There are two types of nodes that can be created,
|
||||||
|
leaf nodes and collection nodes.
|
||||||
|
<li>Leaf Nodes - contains only messages</li>
|
||||||
|
<li>Collection Nodes - contains only nodes (both Leaf and Collection are allowed), but no messages</li>
|
||||||
|
|
||||||
|
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 <b>persistent</b> or not and whether it will deliver payload or not.</p>
|
||||||
|
|
||||||
|
<b>Usage</b><p>
|
||||||
|
|
||||||
|
In order to create a node you will need to first create an instance of <i><b>PubSubManager</b></i>. There
|
||||||
|
are several options for node creation which range from creating an instant node, default configuration, or
|
||||||
|
a fully configured node.</p><p>
|
||||||
|
|
||||||
|
<b>Examples</b><p>
|
||||||
|
|
||||||
|
Create an instant node: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Create the node</font>
|
||||||
|
LeafNode leaf = mgr.createNode();
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
Create a node with default configuration and then configure it: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Create the node</font>
|
||||||
|
LeafNode leaf = mgr.createNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
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);
|
||||||
|
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
Create and configure a node: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Create the node</font>
|
||||||
|
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(<font color="#0000FF">"testNode"</font>, form);
|
||||||
|
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<div class="subheader"><a name="publish">Publishing to a node</a></div><p>
|
||||||
|
|
||||||
|
<b>Description</b><p>
|
||||||
|
This section deals with the <b>publish</b> 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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<b>Usage</b><p>
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<b>Examples</b><p>
|
||||||
|
In this example we publish an item to a node that does not take payload: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the node</font>
|
||||||
|
LeafNode node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Publish an Item, let service set the id</font>
|
||||||
|
node.send(new Item());
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Publish an Item with the specified id</font>
|
||||||
|
node.send(new Item(<font color="#0000FF">"123abc"</font>));
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
In this example we publish an item to a node that does take payload: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the node</font>
|
||||||
|
LeafNode node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Publish an Item with payload</font>
|
||||||
|
node.send(new PayloadItem<SimplePayload>(<font color="#0000FF">"test"</font> + System.currentTimeMillis(),
|
||||||
|
new SimplePayload(<font color="#0000FF">"book"</font>, <font color="#0000FF">"pubsub:test:book"</font>, <font color="#0000FF">"<book xmlns='pubsub:test:book'><title>Two Towers</title></book>"</font>)));
|
||||||
|
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
<div class="subheader"><a name="subscribe">Receiving pubsub messages</a></div><p>
|
||||||
|
|
||||||
|
<b>Description</b><p>
|
||||||
|
This section deals with the <b>subscribe</b> 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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<b>Usage</b><p>
|
||||||
|
To get messages asynchronously when items are published to a node, you will have to
|
||||||
|
<li>Get a node.</li>
|
||||||
|
<li>Create and register a listener.</li>
|
||||||
|
<li>Subscribe to the node.</li>
|
||||||
|
<p>
|
||||||
|
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.
|
||||||
|
</p></p>
|
||||||
|
|
||||||
|
<b>Examples</b><p>
|
||||||
|
|
||||||
|
In this example we can see how to create a listener and register it and then subscribe for
|
||||||
|
messages. <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the node</font>
|
||||||
|
LeafNode node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
|
||||||
|
node.addItemEventListener(new ItemEventCoordinator<Item>());
|
||||||
|
node.subscribe(myJid);
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
Where the listener is defined like so:
|
||||||
|
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
|
||||||
|
class ItemEventCoordinator <T extends Item> implements ItemEventListener<T>
|
||||||
|
{
|
||||||
|
@Override
|
||||||
|
public void handlePublishedItems(ItemPublishEvent<T> items)
|
||||||
|
{
|
||||||
|
System.out.println(<font color="#0000FF">"Item count: "</font> + items.getItems().size());
|
||||||
|
System.out.println(items);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
In addition to receiving published items, there are notifications for several other
|
||||||
|
events that occur on a node as well.
|
||||||
|
<li>Deleting items or purging all items from a node</li>
|
||||||
|
<li>Changing the node configuration</li>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
In this example we can see how to create a listener, register it and then subscribe for
|
||||||
|
item deletion messages. <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the node</font>
|
||||||
|
LeafNode node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
|
||||||
|
node.addItemDeleteListener(new ItemDeleteCoordinator<Item>());
|
||||||
|
node.subscribe(myJid);
|
||||||
|
node.deleteItem(<font color="#0000FF">"id_one"</font>);
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
Where the handler is defined like so:
|
||||||
|
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
|
||||||
|
class ItemDeleteCoordinator implements ItemDeleteListener<T>
|
||||||
|
{
|
||||||
|
@Override
|
||||||
|
public void handleDeletedItems(ItemDeleteEvent items)
|
||||||
|
{
|
||||||
|
System.out.println(<font color="#0000FF">"Item count: "</font> + items.getItemIds().size());
|
||||||
|
System.out.println(items);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void handlePurge()
|
||||||
|
{
|
||||||
|
System.out.println(<font color="#0000FF">"All items have been deleted from node"</font>);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
In this example we can see how to create a listener, register it and then subscribe for
|
||||||
|
node configuration messages. <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the node</font>
|
||||||
|
Node node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
|
||||||
|
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);
|
||||||
|
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
Where the handler is defined like so:
|
||||||
|
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
|
||||||
|
class NodeConfigCoordinator implements NodeConfigListener<T>
|
||||||
|
{
|
||||||
|
@Override
|
||||||
|
public void handleNodeConfiguration(ConfigurationEvent config)
|
||||||
|
{
|
||||||
|
System.out.println(<font color="#0000FF">"New configuration"</font>);
|
||||||
|
System.out.println(config.getConfiguration());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<div class="subheader"><a name="retrieve">Retrieving persisted pubsub messages</a></div><p>
|
||||||
|
|
||||||
|
<b>Description</b><p>
|
||||||
|
|
||||||
|
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.</p>
|
||||||
|
|
||||||
|
<b>Usage</b><p>
|
||||||
|
|
||||||
|
To synchronously retrieve existing items from a persistent node, you will have to get an instance
|
||||||
|
of a <i><b>LeafNode</b></i> and call one of the retrieve methods.
|
||||||
|
<p>
|
||||||
|
|
||||||
|
<b>Examples</b><p>
|
||||||
|
|
||||||
|
In this example we can see how to retrieve the existing items from a node: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the node</font>
|
||||||
|
LeafNode node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
|
||||||
|
Collection<? extends Item> items = node.getItems();
|
||||||
|
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
In this example we can see how to retrieve the last N existing items: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the node</font>
|
||||||
|
LeafNode node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
|
||||||
|
List<? extends Item> items = node.getItems(100);
|
||||||
|
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
In this example we can see how to retrieve the specified existing items: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the node</font>
|
||||||
|
LeafNode node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
Collection<String> ids = new ArrayList<String>(3);
|
||||||
|
ids.add("1");
|
||||||
|
ids.add("3");
|
||||||
|
ids.add("4");
|
||||||
|
|
||||||
|
List<? extends Item> items = node.getItems(ids);
|
||||||
|
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<div class="subheader"><a name="discopubsub">Discover pubsub information</a></div><p>
|
||||||
|
|
||||||
|
<b>Description</b><p>
|
||||||
|
|
||||||
|
A user may want to query a server or node for a variety of pubsub related information.</p>
|
||||||
|
|
||||||
|
<b>Usage</b><p>
|
||||||
|
|
||||||
|
To retrieve information, a user will simply use either the <i><b>PubSubManager</b></i>
|
||||||
|
or <i><b>Node</b></i> classes depending on what type of information is required.
|
||||||
|
|
||||||
|
<b>Examples</b><p>
|
||||||
|
|
||||||
|
In this example we can see how to get pubsub capabilities: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the pubsub features that are supported</font>
|
||||||
|
DiscoverInfo supportedFeatures = mgr.getSupportedFeatures();
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
In this example we can see how to get pubsub subscriptions for all nodes: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get all the subscriptions in the pubsub service</font>
|
||||||
|
List<Subscription> subscriptions = mgr.getSubscriptions();
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
In this example we can see how to get all affiliations for the users bare JID on the pubsub service: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the affiliations for the users bare JID</font>
|
||||||
|
List<Affiliation> affiliations = mgr.getAffiliations();
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
In this example we can see how to get information about the node: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
Node node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Get the node information</font>
|
||||||
|
DiscoverInfo nodeInfo = node.discoverInfo();
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
In this example we can see how to discover the node items: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
Node node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Discover the node items</font>
|
||||||
|
DiscoverItems nodeItems = node.discoverItems();
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
In this example we can see how to get node subscriptions: <br>
|
||||||
|
<blockquote>
|
||||||
|
<pre>
|
||||||
|
<font color="#3f7f5f">// Create a pubsub manager using an existing XMPPConnection</font>
|
||||||
|
PubSubManager mgr = new PubSubManager(con);
|
||||||
|
Node node = mgr.getNode(<font color="#0000FF">"testNode"</font>);
|
||||||
|
|
||||||
|
<font color="#3f7f5f">// Discover the node subscriptions</font>
|
||||||
|
List<Subscription> subscriptions = node.getSubscriptions();
|
||||||
|
</pre>
|
||||||
|
</blockquote>
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
|
||||||
|
</body>
|
||||||
|
|
||||||
|
</html>
|
||||||
Loading…
Reference in a new issue