Package org.jivesoftware.smackx.pubsub

Class PubSubManager

  • public final class PubSubManager
extends org.jivesoftware.smack.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.

    • Method Detail

      • getInstanceFor

        public static PubSubManager getInstanceFor​(org.jivesoftware.smack.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​(org.jivesoftware.smack.XMPPConnection connection,
                                           org.jxmpp.jid.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​(org.jivesoftware.smack.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​(org.jivesoftware.smack.XMPPConnection connection,
                                        org.jxmpp.jid.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 org.jivesoftware.smack.SmackException.NoResponseException,
                           org.jivesoftware.smack.XMPPException.XMPPErrorException,
                           org.jivesoftware.smack.SmackException.NotConnectedException,
                           java.lang.InterruptedException
        Creates an instant node, if supported.
        Returns:
        The node that was created
        Throws:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.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 org.jivesoftware.smack.SmackException.NoResponseException,
                           org.jivesoftware.smack.XMPPException.XMPPErrorException,
                           org.jivesoftware.smack.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:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.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 org.jivesoftware.smack.SmackException.NoResponseException,
                       org.jivesoftware.smack.XMPPException.XMPPErrorException,
                       org.jivesoftware.smack.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:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.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 org.jivesoftware.smack.SmackException.NoResponseException,
                    org.jivesoftware.smack.XMPPException.XMPPErrorException,
                    org.jivesoftware.smack.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:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - The node does not exist
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the server.
        org.jivesoftware.smack.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 org.jivesoftware.smack.SmackException.NoResponseException,
                                    org.jivesoftware.smack.SmackException.NotConnectedException,
                                    java.lang.InterruptedException,
                                    org.jivesoftware.smack.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:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
        org.jivesoftware.smack.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,
                            org.jivesoftware.smack.SmackException.NoResponseException,
                            org.jivesoftware.smack.SmackException.NotConnectedException,
                            java.lang.InterruptedException,
                            org.jivesoftware.smack.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.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
        org.jivesoftware.smack.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 org.jivesoftware.smack.SmackException.NoResponseException,
                                                                   org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                                   org.jivesoftware.smack.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:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.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 org.jivesoftware.smack.SmackException.NoResponseException,
                                   org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                   org.jivesoftware.smack.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:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the server.
        org.jivesoftware.smack.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 org.jivesoftware.smack.SmackException.NoResponseException,
                                                     org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                     org.jivesoftware.smack.SmackException.NotConnectedException,
                                                     java.lang.InterruptedException
        Gets the subscriptions on the root node.
        Returns:
        List of exceptions
        Throws:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.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 org.jivesoftware.smack.SmackException.NoResponseException,
                                                   org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                   org.jivesoftware.smack.SmackException.NotConnectedException,
                                                   java.lang.InterruptedException
        Gets the affiliations on the root node.
        Returns:
        List of affiliations
        Throws:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.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 org.jivesoftware.smack.SmackException.NoResponseException,
                          org.jivesoftware.smack.XMPPException.XMPPErrorException,
                          org.jivesoftware.smack.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:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.

      • getDefaultConfiguration

        public ConfigureForm getDefaultConfiguration()
                                      throws org.jivesoftware.smack.SmackException.NoResponseException,
                                             org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                             org.jivesoftware.smack.SmackException.NotConnectedException,
                                             java.lang.InterruptedException
        Returns the default settings for Node configuration.
        Returns:
        configuration form containing the default settings.
        Throws:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.

      • 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 org.jivesoftware.smack.SmackException.NoResponseException,
                                         org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                         org.jivesoftware.smack.SmackException.NotConnectedException,
                                         java.lang.InterruptedException
        Gets the supported features of the servers pubsub implementation as a standard DiscoverInfo instance.
        Returns:
        The supported features
        Throws:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.

      • supportsAutomaticNodeCreation

        public boolean supportsAutomaticNodeCreation()
                                      throws org.jivesoftware.smack.SmackException.NoResponseException,
                                             org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                             org.jivesoftware.smack.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:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.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 org.jivesoftware.smack.SmackException.NoResponseException,
                                             org.jivesoftware.smack.SmackException.NotConnectedException,
                                             java.lang.InterruptedException,
                                             org.jivesoftware.smack.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:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.

      • getPubSubService

        public static org.jxmpp.jid.DomainBareJid getPubSubService​(org.jivesoftware.smack.XMPPConnection connection)
                                                    throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                           org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                           org.jivesoftware.smack.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:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.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