/** * * Copyright 2015-2023 Florian Schmaus * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * Smack's API for XEP-0060: Publish-Subscribe. XMPP based * publish and subscribe is based around nodes to which * items can be published. Subscribers of those nodes will be notified about new items. *

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. *

* *

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: *

* * 
{@code
 * // 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: *

* * 
{@code
 * // 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: *

* * 
{@code
 * // 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: *

* * 
{@code
 * // 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: *

* * 
{@code
 * // 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 *

* *

* 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. *

* * 
{@code
 * // 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());
 * node.subscribe(myJid);
 * }
*

* Where the listener is defined like so: *

* * 

 * class ItemEventCoordinator implements ItemEventListener {
 *     {@literal @}@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. *

* *

* In this example we can see how to create a listener, register it and then subscribe for item deletion messages. *

* * 
{@code
 * // 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());
 * node.subscribe(myJid);
 * node.deleteItem("id_one");
 * }
*

* Where the handler is defined like so: *

* * 

 * class ItemDeleteCoordinator implements ItemDeleteListener {
 *     {@literal @}Override
 *     public void handleDeletedItems(ItemDeleteEvent items) {
 *         System.out.println("Item count: " + items.getItemIds().size());
 *         System.out.println(items);
 *     }
 *
 *     {@literal @}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. *

* * 
{@code
 * // 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 {
 *     {@literal @}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: *

* * 
{@code
 * // Create a pubsub manager using an existing XMPPConnection
 * PubSubManager mgr = PubSubManager.getInstanceFor(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: *

* * 
{@code
 * // Create a pubsub manager using an existing XMPPConnection
 * PubSubManager mgr = PubSubManager.getInstanceFor(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: *

* * 
{@code
 * // Create a pubsub manager using an existing XMPPConnection
 * PubSubManager mgr = PubSubManager.getInstanceFor(con);
 *
 * // Get the node
 * LeafNode node = mgr.getNode("testNode");
 * Collection ids = new ArrayList(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: *

* * 
{@code
 * // 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: *

* * 
{@code
 * // Create a pubsub manager using an existing XMPPConnection
 * PubSubManager mgr = PubSubManager.getInstanceFor(con);
 *
 * // Get all the subscriptions in the pubsub service
 * List subscriptions = mgr.getSubscriptions();
 * }
*

* In this example we can see how to get all affiliations for the users bare JID on the pubsub service: *

* * 
{@code
 * // Create a pubsub manager using an existing XMPPConnection
 * PubSubManager mgr = PubSubManager.getInstanceFor(con);
 *
 * // Get the affiliations for the users bare JID
 * List affiliations = mgr.getAffiliations();
 * }
*

* In this example we can see how to get information about the node: *

* * 
{@code
 * // 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: *

* * 
{@code
 * // 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: *

* * 
{@code
 * // Create a pubsub manager using an existing XMPPConnection
 * PubSubManager mgr = PubSubManager.getInstanceFor(con);
 * Node node = mgr.getNode("testNode");
 *
 * // Discover the node subscriptions
 * List subscriptions = node.getSubscriptions();
 * }
* * @see XEP-0060: Publish-Subscribe */ package org.jivesoftware.smackx.pubsub;