Package 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	Description
static java.lang.String	AUTO_CREATE_FEATURE
static java.lang.String	PLUS_NOTIFY

Method Summary

Modifier and Type	Method	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(java.lang.String nodeId)	Creates a node with default configuration.
Node	createNode(java.lang.String nodeId, FillableConfigureForm config)	Creates a node with specified configuration.
boolean	deleteNode(java.lang.String nodeId)	Delete the specified node.
DiscoverItems	discoverNodes(java.lang.String nodeId)	Get all the nodes that currently exist as a child of the specified collection node.
java.util.List<Affiliation>	getAffiliations()	Gets the affiliations on the root node.
ConfigureForm	getDefaultConfiguration()	Returns the default settings for Node configuration.
static PubSubManager	getInstance(XMPPConnection connection)	Deprecated. use getInstanceFor(XMPPConnection) instead.
static PubSubManager	getInstance(XMPPConnection connection, BareJid pubSubService)	Deprecated. use getInstanceFor(XMPPConnection, BareJid) instead.
static PubSubManager	getInstanceFor(XMPPConnection connection)	Get a PubSub manager for the default PubSub service of the connection.
static PubSubManager	getInstanceFor(XMPPConnection connection, BareJid pubSubService)	Get the PubSub manager for the given connection and PubSub service.
LeafNode	getLeafNode(java.lang.String id)	Try to get a leaf node with the given node ID.
Node	getNode(java.lang.String id)	Retrieves the requested node, if it exists.
LeafNode	getOrCreateLeafNode(java.lang.String id)	Try to get a leaf node and create one if it does not already exist.
static DomainBareJid	getPubSubService(XMPPConnection connection)	Get the "default" PubSub service for a given XMPP connection.
BareJid	getServiceJid()	Get the JID of the PubSub service managed by this manager.
java.util.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(java.lang.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, schedule, scheduleBlocking

Methods inherited from class java.lang.Object

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

Field Detail

PLUS_NOTIFY

public static final java.lang.String PLUS_NOTIFY

See Also:

Constant Field Values

AUTO_CREATE_FEATURE

public static final java.lang.String AUTO_CREATE_FEATURE

See Also:

Constant Field Values

Method Detail

getInstanceFor

public static PubSubManager getInstanceFor(XMPPConnection connection)

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

Parameters:

connection - TODO javadoc me please

Returns:

the default PubSub manager.

getInstanceFor

public static PubSubManager getInstanceFor(XMPPConnection connection,
                                           BareJid pubSubService)

Get the PubSub manager for the given connection and PubSub service. Use null as argument for pubSubService to retrieve a PubSubManager for the users PEP service.

Parameters:

connection - the XMPP connection.

pubSubService - the PubSub service, may be null.

Returns:

a PubSub manager for the connection and service.

getInstance

@Deprecated
public static PubSubManager getInstance(XMPPConnection connection)

Deprecated.

use getInstanceFor(XMPPConnection) instead.

Deprecated.

Parameters:

connection - the connection.

Returns:

the PubSub manager for the given connection.

getInstance

@Deprecated
public static PubSubManager getInstance(XMPPConnection connection,
                                        BareJid pubSubService)

Deprecated.

use getInstanceFor(XMPPConnection, BareJid) instead.

Deprecated.

Parameters:

connection - the connection.

pubSubService - the XMPP address of the PubSub service.

Returns:

the PubSub manager for the given connection.

createNode

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

Creates an instant node, if supported.

Returns:

The node that was created

Throws:

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

createNode

public LeafNode createNode(java.lang.String nodeId)
                    throws SmackException.NoResponseException,
                           XMPPException.XMPPErrorException,
                           SmackException.NotConnectedException,
                           java.lang.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 - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

createNode

public Node createNode(java.lang.String nodeId,
                       FillableConfigureForm config)
                throws SmackException.NoResponseException,
                       XMPPException.XMPPErrorException,
                       SmackException.NotConnectedException,
                       java.lang.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 - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

getNode

public Node getNode(java.lang.String id)
             throws SmackException.NoResponseException,
                    XMPPException.XMPPErrorException,
                    SmackException.NotConnectedException,
                    java.lang.InterruptedException,
                    PubSubException.NotAPubSubNodeException

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

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 - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

PubSubException.NotAPubSubNodeException - if a involved node is not a PubSub node.

getOrCreateLeafNode

public LeafNode getOrCreateLeafNode(java.lang.String id)
                             throws SmackException.NoResponseException,
                                    SmackException.NotConnectedException,
                                    java.lang.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 - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

XMPPException.XMPPErrorException - if there was an XMPP error returned.

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

Since:

4.2.1

getLeafNode

public LeafNode getLeafNode(java.lang.String id)
                     throws PubSubException.NotALeafNodeException,
                            SmackException.NoResponseException,
                            SmackException.NotConnectedException,
                            java.lang.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 - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

XMPPException.XMPPErrorException - if there was an XMPP error returned.

PubSubException.NotAPubSubNodeException - if a involved node is not a PubSub node.

Since:

4.2.1

tryToPublishAndPossibleAutoCreate

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

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 - if there was no response from the remote entity.

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

PubSubException.NotALeafNodeException - if a PubSub leaf node operation was attempted on a non-leaf node.

Since:

4.2.1

discoverNodes

public DiscoverItems discoverNodes(java.lang.String nodeId)
                            throws SmackException.NoResponseException,
                                   XMPPException.XMPPErrorException,
                                   SmackException.NotConnectedException,
                                   java.lang.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 - if there was an XMPP error returned.

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

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

getSubscriptions

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

Gets the subscriptions on the root node.

Returns:

List of exceptions

Throws:

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

getAffiliations

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

Gets the affiliations on the root node.

Returns:

List of affiliations

Throws:

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

deleteNode

public boolean deleteNode(java.lang.String nodeId)
                   throws SmackException.NoResponseException,
                          XMPPException.XMPPErrorException,
                          SmackException.NotConnectedException,
                          java.lang.InterruptedException

Delete the specified node.

Parameters:

nodeId - TODO javadoc me please

Returns:

true if this node existed and was deleted and false if this node did not exist.

Throws:

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

getDefaultConfiguration

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

Returns the default settings for Node configuration.

Returns:

configuration form containing the default settings.

Throws:

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

getServiceJid

public 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,
                                         java.lang.InterruptedException

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

Returns:

The supported features

Throws:

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

supportsAutomaticNodeCreation

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

Check if the PubSub service supports automatic node creation.

Returns:

true if the PubSub service supports automatic node creation.

Throws:

SmackException.NoResponseException - if there was no response from the remote entity.

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

Since:

4.2.1

See Also:

XEP-0060 § 7.1.4 Automatic Node Creation

canCreateNodesAndPublishItems

public boolean canCreateNodesAndPublishItems()
                                      throws SmackException.NoResponseException,
                                             SmackException.NotConnectedException,
                                             java.lang.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 - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

XMPPException.XMPPErrorException - if there was an XMPP error returned.

getPubSubService

public static DomainBareJid getPubSubService(XMPPConnection connection)
                                      throws SmackException.NoResponseException,
                                             XMPPException.XMPPErrorException,
                                             SmackException.NotConnectedException,
                                             java.lang.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 - TODO javadoc me please

Returns:

the default PubSub service or null.

Throws:

SmackException.NoResponseException - if there was no response from the remote entity.

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

See Also:

XEP-60 § 5.1 Discover Features