org.jivesoftware.smackx.pubsub

Class PubSubManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.pubsub.PubSubManager

public final class PubSubManager
extends Manager

This is the starting point for access to the pubsub service. It will provide access to general information about the service, as well as create or retrieve pubsub LeafNode instances. These instances provide the bulk of the functionality as defined in the pubsub specification XEP-0060.

Field Summary

Fields

Modifier and Type	Field and Description
static String	AUTO_CREATE_FEATURE

Method Summary

Modifier and Type	Method and Description
boolean	canCreateNodesAndPublishItems() Check if it is possible to create PubSub nodes on this service.
LeafNode	createNode() Creates an instant node, if supported.
LeafNode	createNode(String nodeId) Creates a node with default configuration.
Node	createNode(String nodeId, Form config) Creates a node with specified configuration.
void	deleteNode(String nodeId) Delete the specified node.
DiscoverItems	discoverNodes(String nodeId) Get all the nodes that currently exist as a child of the specified collection node.
List<Affiliation>	getAffiliations() Gets the affiliations on the root node.
ConfigureForm	getDefaultConfiguration() Returns the default settings for Node configuration.
static PubSubManager	getInstance(XMPPConnection connection) Get a PubSub manager for the default PubSub service of the connection.
static PubSubManager	getInstance(XMPPConnection connection, org.jxmpp.jid.BareJid pubSubService) Get the PubSub manager for the given connection and PubSub service.
LeafNode	getLeafNode(String id) Try to get a leaf node with the given node ID.
<T extends Node> T	getNode(String id) Retrieves the requested node, if it exists.
LeafNode	getOrCreateLeafNode(String id) Try to get a leaf node and create one if it does not already exist.
static org.jxmpp.jid.DomainBareJid	getPubSubService(XMPPConnection connection) Get the "default" PubSub service for a given XMPP connection.
org.jxmpp.jid.BareJid	getServiceJid() Get the JID of the PubSub service managed by this manager.
List<Subscription>	getSubscriptions() Gets the subscriptions on the root node.
DiscoverInfo	getSupportedFeatures() Gets the supported features of the servers pubsub implementation as a standard DiscoverInfo instance.
boolean	supportsAutomaticNodeCreation() Check if the PubSub service supports automatic node creation.
<I extends Item> LeafNode	tryToPublishAndPossibleAutoCreate(String id, I item) Try to publish an item and, if the node with the given ID does not exists, auto-create the node.

Methods inherited from class org.jivesoftware.smack.Manager

connection, getAuthenticatedConnectionOrThrow, schedule

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AUTO_CREATE_FEATURE

public static final String AUTO_CREATE_FEATURE

See Also:

Constant Field Values

Method Detail

getInstance

public static PubSubManager getInstance(XMPPConnection connection)

Get a PubSub manager for the default PubSub service of the connection.

Parameters:

connection -

Returns:

the default PubSub manager.

getInstance

public static PubSubManager getInstance(XMPPConnection connection,
                                        org.jxmpp.jid.BareJid pubSubService)

Get the PubSub manager for the given connection and PubSub service.

Parameters:

connection - the XMPP connection.

pubSubService - the PubSub service.

Returns:

a PubSub manager for the connection and service.

createNode

public LeafNode createNode()
                    throws SmackException.NoResponseException,
                           XMPPException.XMPPErrorException,
                           SmackException.NotConnectedException,
                           InterruptedException

Creates an instant node, if supported.

Returns:

The node that was created

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

createNode

public LeafNode createNode(String nodeId)
                    throws SmackException.NoResponseException,
                           XMPPException.XMPPErrorException,
                           SmackException.NotConnectedException,
                           InterruptedException

Creates a node with default configuration.

Parameters:

nodeId - The id of the node, which must be unique within the pubsub service

Returns:

The node that was created

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

createNode

public Node createNode(String nodeId,
                       Form config)
                throws SmackException.NoResponseException,
                       XMPPException.XMPPErrorException,
                       SmackException.NotConnectedException,
                       InterruptedException

Creates a node with specified configuration. Note: This is the only way to create a collection node.

Parameters:

nodeId - The name of the node, which must be unique within the pubsub service

config - The configuration for the node

Returns:

The node that was created

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

getNode

public <T extends Node> T getNode(String id)
                           throws SmackException.NoResponseException,
                                  XMPPException.XMPPErrorException,
                                  SmackException.NotConnectedException,
                                  InterruptedException,
                                  PubSubException.NotAPubSubNodeException

Retrieves the requested node, if it exists. It will throw an exception if it does not.

Type Parameters:

T - type of the node.

Parameters:

id - - The unique id of the node

Returns:

the node

Throws:

XMPPException.XMPPErrorException - The node does not exist

SmackException.NoResponseException - if there was no response from the server.

SmackException.NotConnectedException

InterruptedException

PubSubException.NotAPubSubNodeException

getOrCreateLeafNode

public LeafNode getOrCreateLeafNode(String id)
                             throws SmackException.NoResponseException,
                                    SmackException.NotConnectedException,
                                    InterruptedException,
                                    XMPPException.XMPPErrorException,
                                    PubSubException.NotALeafNodeException

Try to get a leaf node and create one if it does not already exist.

Parameters:

id - The unique ID of the node.

Returns:

the leaf node.

Throws:

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

XMPPException.XMPPErrorException

PubSubException.NotALeafNodeException - in case the node already exists as collection node.

Since:

4.2.1

getLeafNode

public LeafNode getLeafNode(String id)
                     throws PubSubException.NotALeafNodeException,
                            SmackException.NoResponseException,
                            SmackException.NotConnectedException,
                            InterruptedException,
                            XMPPException.XMPPErrorException,
                            PubSubException.NotAPubSubNodeException

Try to get a leaf node with the given node ID.

Parameters:

id - the node ID.

Returns:

the requested leaf node.

Throws:

PubSubException.NotALeafNodeException - in case the node exists but is a collection node.

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

XMPPException.XMPPErrorException

PubSubException.NotAPubSubNodeException

Since:

4.2.1

tryToPublishAndPossibleAutoCreate

public <I extends Item> LeafNode tryToPublishAndPossibleAutoCreate(String id,
                                                                   I item)
                                                            throws SmackException.NoResponseException,
                                                                   XMPPException.XMPPErrorException,
                                                                   SmackException.NotConnectedException,
                                                                   InterruptedException

Try to publish an item and, if the node with the given ID does not exists, auto-create the node.

Not every PubSub service supports automatic node creation. You can discover if this service supports it by using supportsAutomaticNodeCreation().

Type Parameters:

I - type of the item.

Parameters:

id - The unique id of the node.

item - The item to publish.

Returns:

the LeafNode on which the item was published.

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

Since:

4.2.1

discoverNodes

public DiscoverItems discoverNodes(String nodeId)
                            throws SmackException.NoResponseException,
                                   XMPPException.XMPPErrorException,
                                   SmackException.NotConnectedException,
                                   InterruptedException

Get all the nodes that currently exist as a child of the specified collection node. If the service does not support collection nodes then all nodes will be returned. To retrieve contents of the root collection node (if it exists), or there is no root collection node, pass null as the nodeId.

Parameters:

nodeId - - The id of the collection node for which the child nodes will be returned.

Returns:

DiscoverItems representing the existing nodes

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException - if there was no response from the server.

SmackException.NotConnectedException

InterruptedException

getSubscriptions

public List<Subscription> getSubscriptions()
                                    throws SmackException.NoResponseException,
                                           XMPPException.XMPPErrorException,
                                           SmackException.NotConnectedException,
                                           InterruptedException

Gets the subscriptions on the root node.

Returns:

List of exceptions

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

getAffiliations

public List<Affiliation> getAffiliations()
                                  throws SmackException.NoResponseException,
                                         XMPPException.XMPPErrorException,
                                         SmackException.NotConnectedException,
                                         InterruptedException

Gets the affiliations on the root node.

Returns:

List of affiliations

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

deleteNode

public void deleteNode(String nodeId)
                throws SmackException.NoResponseException,
                       XMPPException.XMPPErrorException,
                       SmackException.NotConnectedException,
                       InterruptedException

Delete the specified node.

Parameters:

nodeId -

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

getDefaultConfiguration

public ConfigureForm getDefaultConfiguration()
                                      throws SmackException.NoResponseException,
                                             XMPPException.XMPPErrorException,
                                             SmackException.NotConnectedException,
                                             InterruptedException

Returns the default settings for Node configuration.

Returns:

configuration form containing the default settings.

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

getServiceJid

public org.jxmpp.jid.BareJid getServiceJid()

Get the JID of the PubSub service managed by this manager.

Returns:

the JID of the PubSub service.

getSupportedFeatures

public DiscoverInfo getSupportedFeatures()
                                  throws SmackException.NoResponseException,
                                         XMPPException.XMPPErrorException,
                                         SmackException.NotConnectedException,
                                         InterruptedException

Gets the supported features of the servers pubsub implementation as a standard DiscoverInfo instance.

Returns:

The supported features

Throws:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

supportsAutomaticNodeCreation

public boolean supportsAutomaticNodeCreation()
                                      throws SmackException.NoResponseException,
                                             XMPPException.XMPPErrorException,
                                             SmackException.NotConnectedException,
                                             InterruptedException

Check if the PubSub service supports automatic node creation.

Returns:

true if the PubSub service supports automatic node creation.

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

Since:

4.2.1

See Also:

XEP-0060 § 7.1.4 Automatic Node Creation

canCreateNodesAndPublishItems

public boolean canCreateNodesAndPublishItems()
                                      throws SmackException.NoResponseException,
                                             SmackException.NotConnectedException,
                                             InterruptedException,
                                             XMPPException.XMPPErrorException

Check if it is possible to create PubSub nodes on this service. It could be possible that the PubSub service allows only certain XMPP entities (clients) to create nodes and publish items to them.

Note that since XEP-60 does not provide an API to determine if an XMPP entity is allowed to create nodes, therefore this method creates an instant node calling createNode() to determine if it is possible to create nodes.

Returns:

true if it is possible to create nodes, false otherwise.

Throws:

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

XMPPException.XMPPErrorException

getPubSubService

public static org.jxmpp.jid.DomainBareJid getPubSubService(XMPPConnection connection)
                                                    throws SmackException.NoResponseException,
                                                           XMPPException.XMPPErrorException,
                                                           SmackException.NotConnectedException,
                                                           InterruptedException

Get the "default" PubSub service for a given XMPP connection. The default PubSub service is simply an arbitrary XMPP service with the PubSub feature and an identity of category "pubsub" and type "service".

Parameters:

connection -

Returns:

the default PubSub service or null.

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException

See Also:

XEP-60 § 5.1 Discover Features