vanitasvitae/Smack
1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2024-11-22 20:12:07 +01:00
Code Issues Releases Wiki Activity

SMACK-272 Add support for XEP-0060 (pubsub)

Browse source 
git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@11345 b35dd754-fafc-0310-a699-88a17e54d16e
This commit is contained in:
rcollier 2009-10-28 22:36:54 +00:00
parent a1e791172c
commit 92ba2d7f33
1 changed files with 448 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

448
documentation/extensions/pubsub.html Normal file
View 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&ltItem&gt());
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&ltItem&gt());
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&lt? extends Item&gt 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&lt? extends Item&gt 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&ltString&gt ids = new ArrayList&ltString&gt(3);
ids.add("1");
ids.add("3");
ids.add("4");
List&lt? extends Item&gt 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&ltSubscription&gt 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&ltAffiliation&gt 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&ltSubscription&gt subscriptions = node.getSubscriptions();
</pre>
</blockquote>
<hr>
</body>
</html>