Package org.jivesoftware.smackx.pubsub

Class Node

java.lang.Object

org.jivesoftware.smackx.pubsub.Node

Direct Known Subclasses:

CollectionNode, LeafNode

public abstract class Node
extends Object

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Node.ItemDeleteTranslator	This class translates low level item deletion events into api level objects for user consumption.
static class	Node.ItemEventTranslator	This class translates low level item publication events into api level objects for user consumption.
static class	Node.NodeConfigTranslator	This class translates low level node configuration events into api level objects for user consumption.

Field Summary

Fields

Modifier and Type	Field	Description
protected ConcurrentHashMap<NodeConfigListener,StanzaListener>	configEventToListenerMap
protected String	id
protected ConcurrentHashMap<ItemDeleteListener,StanzaListener>	itemDeleteToListenerMap
protected ConcurrentHashMap<ItemEventListener<Item>,StanzaListener>	itemEventToListenerMap
protected PubSubManager	pubSubManager

Method Summary

Modifier and Type	Method	Description
void	addConfigurationListener(NodeConfigListener listener)	Register a listener for configuration events.
void	addItemDeleteListener(ItemDeleteListener listener)	Register an listener for item delete events.
void	addItemEventListener(ItemEventListener listener)	Register a listener for item publication events.
protected PubSub	createPubsubPacket(IQ.Type type, NodeExtension ext)
DiscoverInfo	discoverInfo()	Discover node information in standard DiscoverInfo format.
List<Affiliation>	getAffiliations()	Get the affiliations of this node.
List<Affiliation>	getAffiliations(List<ExtensionElement> additionalExtensions, Collection<ExtensionElement> returnedExtensions)	Get the affiliations of this node.
List<Affiliation>	getAffiliationsAsOwner()	Retrieve the affiliation list for this node as owner.
List<Affiliation>	getAffiliationsAsOwner(List<ExtensionElement> additionalExtensions, Collection<ExtensionElement> returnedExtensions)	Retrieve the affiliation list for this node as owner.
String	getId()	Get the NodeId.
ConfigureForm	getNodeConfiguration()	Returns a configuration form, from which you can create an answer form to be submitted via the sendConfigurationForm(FillableConfigureForm).
SubscribeForm	getSubscriptionOptions(String jid)	Returns a SubscribeForm for subscriptions, from which you can create an answer form to be submitted via the sendConfigurationForm(FillableConfigureForm).
SubscribeForm	getSubscriptionOptions(String jid, String subscriptionId)	Get the options for configuring the specified subscription.
List<Subscription>	getSubscriptions()	Get the subscriptions currently associated with this node.
List<Subscription>	getSubscriptions(List<ExtensionElement> additionalExtensions, Collection<ExtensionElement> returnedExtensions)	Get the subscriptions currently associated with this node.
List<Subscription>	getSubscriptionsAsOwner()	Get the subscriptions currently associated with this node as owner.
List<Subscription>	getSubscriptionsAsOwner(List<ExtensionElement> additionalExtensions, Collection<ExtensionElement> returnedExtensions)	Get the subscriptions currently associated with this node as owner.
PubSub	modifyAffiliationAsOwner(List<Affiliation> affiliations)	Modify the affiliations for this PubSub node as owner.
PubSub	modifySubscriptionsAsOwner(List<Subscription> changedSubs)	Modify the subscriptions for this PubSub node as owner.
void	removeConfigurationListener(NodeConfigListener listener)	Unregister a listener for configuration events.
void	removeItemDeleteListener(ItemDeleteListener listener)	Unregister a listener for item delete events.
void	removeItemEventListener(ItemEventListener listener)	Unregister a listener for publication events.
void	sendConfigurationForm(FillableConfigureForm configureForm)	Update the configuration with the contents of the new FillableConfigureForm.
protected PubSub	sendPubsubPacket(PubSub packet)
Subscription	subscribe(String jidString)	Deprecated. use subscribe(Jid) instead.
Subscription	subscribe(String jidString, FillableSubscribeForm subForm)	Deprecated. use subscribe(Jid, FillableSubscribeForm) instead.
Subscription	subscribe(Jid jid)	The user subscribes to the node using the supplied jid.
Subscription	subscribe(Jid jid, FillableSubscribeForm subForm)	The user subscribes to the node using the supplied jid and subscription options.
String	toString()
void	unsubscribe(String jid)	Remove the subscription related to the specified JID.
void	unsubscribe(String jid, String subscriptionId)	Remove the specific subscription related to the specified JID.

Methods inherited from class java.lang.Object

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

Field Detail

pubSubManager

protected final PubSubManager pubSubManager

id

protected final String id

itemEventToListenerMap

protected ConcurrentHashMap<ItemEventListener<Item>,StanzaListener> itemEventToListenerMap

itemDeleteToListenerMap

protected ConcurrentHashMap<ItemDeleteListener,StanzaListener> itemDeleteToListenerMap

configEventToListenerMap

protected ConcurrentHashMap<NodeConfigListener,StanzaListener> configEventToListenerMap

Method Detail

getId

public String getId()

Get the NodeId.

Returns:

the node id

getNodeConfiguration

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

Returns a configuration form, from which you can create an answer form to be submitted via the sendConfigurationForm(FillableConfigureForm).

Returns:

the configuration form

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.

InterruptedException - if the calling thread was interrupted.

sendConfigurationForm

public void sendConfigurationForm(FillableConfigureForm configureForm)
                           throws SmackException.NoResponseException,
                                  XMPPException.XMPPErrorException,
                                  SmackException.NotConnectedException,
                                  InterruptedException

Update the configuration with the contents of the new FillableConfigureForm.

Parameters:

configureForm - the filled node configuration form with the nodes new configuration.

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.

InterruptedException - if the calling thread was interrupted.

discoverInfo

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

Discover node information in standard DiscoverInfo format.

Returns:

The discovery information about the node.

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.

InterruptedException - if the calling thread was interrupted.

getSubscriptions

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

Get the subscriptions currently associated with this node.

Returns:

List of Subscription

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.

InterruptedException - if the calling thread was interrupted.

getSubscriptions

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

Get the subscriptions currently associated with this node.

additionalExtensions can be used e.g. to add a "Result Set Management" extension. returnedExtensions will be filled with the stanza extensions found in the answer.

Parameters:

additionalExtensions - TODO javadoc me please

returnedExtensions - a collection that will be filled with the returned packet extensions

Returns:

List of Subscription

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.

InterruptedException - if the calling thread was interrupted.

getSubscriptionsAsOwner

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

Get the subscriptions currently associated with this node as owner.

Returns:

List of Subscription

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.

InterruptedException - if the calling thread was interrupted.

Since:

4.1

See Also:

getSubscriptionsAsOwner(List, Collection)

getSubscriptionsAsOwner

public List<Subscription> getSubscriptionsAsOwner(List<ExtensionElement> additionalExtensions,
                                                  Collection<ExtensionElement> returnedExtensions)
                                           throws SmackException.NoResponseException,
                                                  XMPPException.XMPPErrorException,
                                                  SmackException.NotConnectedException,
                                                  InterruptedException

Get the subscriptions currently associated with this node as owner.

Unlike getSubscriptions(List, Collection), which only retrieves the subscriptions of the current entity ("user"), this method returns a list of all subscriptions. This requires the entity to have the sufficient privileges to manage subscriptions.

additionalExtensions can be used e.g. to add a "Result Set Management" extension. returnedExtensions will be filled with the stanza extensions found in the answer.

Parameters:

additionalExtensions - TODO javadoc me please

returnedExtensions - a collection that will be filled with the returned stanza extensions

Returns:

List of Subscription

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.

InterruptedException - if the calling thread was interrupted.

Since:

4.1

See Also:

XEP-60 § 8.8.1 - Retrieve Subscriptions List

modifySubscriptionsAsOwner

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

Modify the subscriptions for this PubSub node as owner.

Note that the subscriptions are _not_ checked against the existing subscriptions since these are not cached (and indeed could change asynchronously)

Parameters:

changedSubs - subscriptions that have changed

Returns:

null or a PubSub stanza with additional information on success.

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.

InterruptedException - if the calling thread was interrupted.

Since:

4.3

See Also:

XEP-60 § 8.8.2 Modify Subscriptions

getAffiliations

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

Get the affiliations of this node.

Returns:

List of Affiliation

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.

InterruptedException - if the calling thread was interrupted.

getAffiliations

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

Get the affiliations of this node.

additionalExtensions can be used e.g. to add a "Result Set Management" extension. returnedExtensions will be filled with the stanza extensions found in the answer.

Parameters:

additionalExtensions - additional PacketExtensions add to the request

returnedExtensions - a collection that will be filled with the returned packet extensions

Returns:

List of Affiliation

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.

InterruptedException - if the calling thread was interrupted.

getAffiliationsAsOwner

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

Retrieve the affiliation list for this node as owner.

Returns:

list of entities whose affiliation is not 'none'.

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.

InterruptedException - if the calling thread was interrupted.

Since:

4.2

See Also:

getAffiliations(List, Collection)

getAffiliationsAsOwner

public List<Affiliation> getAffiliationsAsOwner(List<ExtensionElement> additionalExtensions,
                                                Collection<ExtensionElement> returnedExtensions)
                                         throws SmackException.NoResponseException,
                                                XMPPException.XMPPErrorException,
                                                SmackException.NotConnectedException,
                                                InterruptedException

Retrieve the affiliation list for this node as owner.

Note that this is an optional PubSub feature ('pubsub#modify-affiliations').

Parameters:

additionalExtensions - optional additional extension elements add to the request.

returnedExtensions - an optional collection that will be filled with the returned extension elements.

Returns:

list of entities whose affiliation is not 'none'.

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.

InterruptedException - if the calling thread was interrupted.

Since:

4.2

See Also:

XEP-60 § 8.9.1 Retrieve Affiliations List

modifyAffiliationAsOwner

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

Modify the affiliations for this PubSub node as owner. The Affiliations given must be created with the Affiliation(org.jxmpp.jid.BareJid, Affiliation.Type) constructor.

Note that this is an optional PubSub feature ('pubsub#modify-affiliations').

Parameters:

affiliations - TODO javadoc me please

Returns:

null or a PubSub stanza with additional information on success.

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.

InterruptedException - if the calling thread was interrupted.

Since:

4.2

See Also:

XEP-60 § 8.9.2 Modify Affiliation

subscribe

public Subscription subscribe(Jid jid)
                       throws SmackException.NoResponseException,
                              XMPPException.XMPPErrorException,
                              SmackException.NotConnectedException,
                              InterruptedException

The user subscribes to the node using the supplied jid. The bare jid portion of this one must match the jid for the connection. Please note that the Subscription.State should be checked on return since more actions may be required by the caller. Subscription.State.pending - The owner must approve the subscription request before messages will be received. Subscription.State.unconfigured - If the Subscription.isConfigRequired() is true, the caller must configure the subscription before messages will be received. If it is false the caller can configure it but is not required to do so.

Parameters:

jid - The jid to subscribe as.

Returns:

The subscription

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.

InterruptedException - if the calling thread was interrupted.

subscribe

@Deprecated
public Subscription subscribe(String jidString)
                       throws SmackException.NoResponseException,
                              XMPPException.XMPPErrorException,
                              SmackException.NotConnectedException,
                              InterruptedException

Deprecated.

use subscribe(Jid) instead.

The user subscribes to the node using the supplied jid. The bare jid portion of this one must match the jid for the connection. Please note that the Subscription.State should be checked on return since more actions may be required by the caller. Subscription.State.pending - The owner must approve the subscription request before messages will be received. Subscription.State.unconfigured - If the Subscription.isConfigRequired() is true, the caller must configure the subscription before messages will be received. If it is false the caller can configure it but is not required to do so.

Parameters:

jidString - The jid to subscribe as.

Returns:

The subscription

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.

InterruptedException - if the calling thread was interrupted.

IllegalArgumentException - if the provided string is not a valid JID.

subscribe

public Subscription subscribe(Jid jid,
                              FillableSubscribeForm subForm)
                       throws SmackException.NoResponseException,
                              XMPPException.XMPPErrorException,
                              SmackException.NotConnectedException,
                              InterruptedException

The user subscribes to the node using the supplied jid and subscription options. The bare jid portion of this one must match the jid for the connection. Please note that the Subscription.State should be checked on return since more actions may be required by the caller. Subscription.State.pending - The owner must approve the subscription request before messages will be received. Subscription.State.unconfigured - If the Subscription.isConfigRequired() is true, the caller must configure the subscription before messages will be received. If it is false the caller can configure it but is not required to do so.

Parameters:

jid - The jid to subscribe as.

subForm - TODO javadoc me please

Returns:

The subscription

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.

InterruptedException - if the calling thread was interrupted.

subscribe

@Deprecated
public Subscription subscribe(String jidString,
                              FillableSubscribeForm subForm)
                       throws SmackException.NoResponseException,
                              XMPPException.XMPPErrorException,
                              SmackException.NotConnectedException,
                              InterruptedException

Deprecated.

use subscribe(Jid, FillableSubscribeForm) instead.

The user subscribes to the node using the supplied jid and subscription options. The bare jid portion of this one must match the jid for the connection. Please note that the Subscription.State should be checked on return since more actions may be required by the caller. Subscription.State.pending - The owner must approve the subscription request before messages will be received. Subscription.State.unconfigured - If the Subscription.isConfigRequired() is true, the caller must configure the subscription before messages will be received. If it is false the caller can configure it but is not required to do so.

Parameters:

jidString - The jid to subscribe as.

subForm - TODO javadoc me please

Returns:

The subscription

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.

InterruptedException - if the calling thread was interrupted.

IllegalArgumentException - if the provided string is not a valid JID.

unsubscribe

public void unsubscribe(String jid)
                 throws SmackException.NoResponseException,
                        XMPPException.XMPPErrorException,
                        SmackException.NotConnectedException,
                        InterruptedException

Remove the subscription related to the specified JID. This will only work if there is only 1 subscription. If there are multiple subscriptions, use unsubscribe(String, String).

Parameters:

jid - The JID used to subscribe to the node

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.

InterruptedException - if the calling thread was interrupted.

unsubscribe

public void unsubscribe(String jid,
                        String subscriptionId)
                 throws SmackException.NoResponseException,
                        XMPPException.XMPPErrorException,
                        SmackException.NotConnectedException,
                        InterruptedException

Remove the specific subscription related to the specified JID.

Parameters:

jid - The JID used to subscribe to the node

subscriptionId - The id of the subscription being removed

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.

InterruptedException - if the calling thread was interrupted.

getSubscriptionOptions

public SubscribeForm getSubscriptionOptions(String jid)
                                     throws SmackException.NoResponseException,
                                            XMPPException.XMPPErrorException,
                                            SmackException.NotConnectedException,
                                            InterruptedException

Returns a SubscribeForm for subscriptions, from which you can create an answer form to be submitted via the sendConfigurationForm(FillableConfigureForm).

Parameters:

jid - TODO javadoc me please

Returns:

A subscription options form

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.

InterruptedException - if the calling thread was interrupted.

getSubscriptionOptions

public SubscribeForm getSubscriptionOptions(String jid,
                                            String subscriptionId)
                                     throws SmackException.NoResponseException,
                                            XMPPException.XMPPErrorException,
                                            SmackException.NotConnectedException,
                                            InterruptedException

Get the options for configuring the specified subscription.

Parameters:

jid - JID the subscription is registered under

subscriptionId - The subscription id

Returns:

The subscription option form

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.

InterruptedException - if the calling thread was interrupted.

addItemEventListener

public void addItemEventListener(ItemEventListener listener)

Register a listener for item publication events. This listener will get called whenever an item is published to this node.

Parameters:

listener - The handler for the event

removeItemEventListener

public void removeItemEventListener(ItemEventListener listener)

Unregister a listener for publication events.

Parameters:

listener - The handler to unregister

addConfigurationListener

public void addConfigurationListener(NodeConfigListener listener)

Register a listener for configuration events. This listener will get called whenever the node's configuration changes.

Parameters:

listener - The handler for the event

removeConfigurationListener

public void removeConfigurationListener(NodeConfigListener listener)

Unregister a listener for configuration events.

Parameters:

listener - The handler to unregister

addItemDeleteListener

public void addItemDeleteListener(ItemDeleteListener listener)

Register an listener for item delete events. This listener gets called whenever an item is deleted from the node.

Parameters:

listener - The handler for the event

removeItemDeleteListener

public void removeItemDeleteListener(ItemDeleteListener listener)

Unregister a listener for item delete events.

Parameters:

listener - The handler to unregister

toString

public String toString()

Overrides:

toString in class Object

createPubsubPacket

protected PubSub createPubsubPacket(IQ.Type type,
                                    NodeExtension ext)

sendPubsubPacket

protected PubSub sendPubsubPacket(PubSub packet)
                           throws SmackException.NoResponseException,
                                  XMPPException.XMPPErrorException,
                                  SmackException.NotConnectedException,
                                  InterruptedException

Throws:

SmackException.NoResponseException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

InterruptedException