org.jivesoftware.smackx.pubsub.package-info Maven / Gradle / Ivy
/**
*
* 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.
*
*
* - 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:
*
*
* {@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
*
*
* - 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.
*
*
* {@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.
*
*
* - 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.
*
*
* {@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;