org.jivesoftware.smackx.pubsub
Class Node

java.lang.Object
  extended by org.jivesoftware.smackx.pubsub.Node

public class Node
extends java.lang.Object

The main class for the majority of pubsub functionality. In general almost all pubsub capabilities are related to the concept of a node. All items are published to a node, and typically subscribed to by other users. These users then retrieve events based on this subscription.

Author:
Robin Collier

Nested Class Summary
 class Node.ItemDeleteTranslator
          This class translates low level item deletion events into api level objects for user consumption.
 class Node.ItemEventTranslator
          This class translates low level item publication events into api level objects for user consumption.
 class Node.NodeConfigTranslator
          This class translates low level node configuration events into api level objects for user consumption.
 
Method Summary
 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.
 void deleteAllItems()
          Purges the node of all items.
 void deleteItem(java.util.Collection<java.lang.String> itemIds)
          Delete the items with the specified id's from the node.
 void deleteItem(java.lang.String itemId)
          Delete the item with the specified id from the node.
 DiscoverInfo discoverInfo()
          Discover node information in standard DiscoverInfo format.
 DiscoverItems discoverItems()
          Get information on the items in the node in standard DiscoverItems format.
 java.lang.String getId()
          Get the NodeId
 java.util.List<Item> getItems()
          Get the current items stored in the node.
 java.util.List<Item> getItems(java.util.Collection<java.lang.String> ids)
          Get the items specified from the node.
 java.util.List<Item> getItems(int maxItems)
          Get items persisted on the node, limited to the specified number.
 ConfigureForm getNodeConfiguration()
          Returns a configuration form, from which you can create an answer form to be submitted via the sendConfigurationForm(Form).
 SubscribeForm getSubscriptionOptions(java.lang.String jid)
          Returns a SubscribeForm for subscriptions, from which you can create an answer form to be submitted via the sendConfigurationForm(Form).
 SubscribeForm getSubscriptionOptions(java.lang.String jid, java.lang.String subscriptionId)
          Get the options for configuring the specified subscription.
 java.util.List<Subscription> getSubscriptions()
          Get the subscriptions currently associated with this node.
 void publish()
          Publishes an event to the node.
 void publish(java.util.Collection<Item> items)
          Publishes multiple events to the node.
 void publish(Item item)
          Publishes an event to the node.
 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 send()
          Publishes an event to the node.
 void send(java.util.Collection<Item> items)
          Publishes multiple events to the node.
 void send(Item item)
          Publishes an event to the node.
 void sendConfigurationForm(org.jivesoftware.smackx.Form submitForm)
          Update the configuration with the contents of the new Form
 Subscription subscribe(java.lang.String jid)
          The user subscribes to the node using the supplied jid.
 Subscription subscribe(java.lang.String jid, SubscribeForm subForm)
          The user subscribes to the node using the supplied jid and subscription options.
 java.lang.String toString()
           
 void unsubscribe(java.lang.String jid)
          Remove the subscription related to the specified JID.
 void unsubscribe(java.lang.String jid, java.lang.String subscriptionId)
          Remove the specific subscription related to the specified JID.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getId

public java.lang.String getId()
Get the NodeId

Returns:
the node id

getNodeConfiguration

public ConfigureForm getNodeConfiguration()
                                   throws org.jivesoftware.smack.XMPPException
Returns a configuration form, from which you can create an answer form to be submitted via the sendConfigurationForm(Form).

Returns:
the configuration form
Throws:
org.jivesoftware.smack.XMPPException

sendConfigurationForm

public void sendConfigurationForm(org.jivesoftware.smackx.Form submitForm)
                           throws org.jivesoftware.smack.XMPPException
Update the configuration with the contents of the new Form

Parameters:
submitForm -
Throws:
org.jivesoftware.smack.XMPPException

discoverInfo

public DiscoverInfo discoverInfo()
                          throws org.jivesoftware.smack.XMPPException
Discover node information in standard DiscoverInfo format.

Returns:
The discovery information about the node.
Throws:
org.jivesoftware.smack.XMPPException

discoverItems

public DiscoverItems discoverItems()
                            throws org.jivesoftware.smack.XMPPException
Get information on the items in the node in standard DiscoverItems format.

Returns:
The item details in DiscoverItems format
Throws:
org.jivesoftware.smack.XMPPException

getSubscriptions

public java.util.List<Subscription> getSubscriptions()
                                              throws org.jivesoftware.smack.XMPPException
Get the subscriptions currently associated with this node.

Returns:
List of Subscription
Throws:
org.jivesoftware.smack.XMPPException

subscribe

public Subscription subscribe(java.lang.String jid)
                       throws org.jivesoftware.smack.XMPPException
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:
org.jivesoftware.smack.XMPPException

subscribe

public Subscription subscribe(java.lang.String jid,
                              SubscribeForm subForm)
                       throws org.jivesoftware.smack.XMPPException
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.
Returns:
The subscription
Throws:
org.jivesoftware.smack.XMPPException

unsubscribe

public void unsubscribe(java.lang.String jid)
                 throws org.jivesoftware.smack.XMPPException
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:
org.jivesoftware.smack.XMPPException

unsubscribe

public void unsubscribe(java.lang.String jid,
                        java.lang.String subscriptionId)
                 throws org.jivesoftware.smack.XMPPException
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:
org.jivesoftware.smack.XMPPException

getSubscriptionOptions

public SubscribeForm getSubscriptionOptions(java.lang.String jid)
                                     throws org.jivesoftware.smack.XMPPException
Returns a SubscribeForm for subscriptions, from which you can create an answer form to be submitted via the sendConfigurationForm(Form).

Returns:
A subscription options form
Throws:
org.jivesoftware.smack.XMPPException

getSubscriptionOptions

public SubscribeForm getSubscriptionOptions(java.lang.String jid,
                                            java.lang.String subscriptionId)
                                     throws org.jivesoftware.smack.XMPPException
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:
org.jivesoftware.smack.XMPPException

getItems

public java.util.List<Item> getItems()
                              throws org.jivesoftware.smack.XMPPException
Get the current items stored in the node.

Returns:
List of Item in the node
Throws:
org.jivesoftware.smack.XMPPException

getItems

public java.util.List<Item> getItems(java.util.Collection<java.lang.String> ids)
                              throws org.jivesoftware.smack.XMPPException
Get the items specified from the node. This would typically be used when the server does not return the payload due to size constraints. The user would be required to retrieve the payload after the items have been retrieved via getItems() or an event, that did not include the payload.

Parameters:
ids - Item ids of the items to retrieve
Returns:
The list of Item with payload
Throws:
org.jivesoftware.smack.XMPPException

getItems

public java.util.List<Item> getItems(int maxItems)
                              throws org.jivesoftware.smack.XMPPException
Get items persisted on the node, limited to the specified number.

Parameters:
maxItems - Maximum number of items to return
Returns:
List of Item
Throws:
org.jivesoftware.smack.XMPPException

publish

public void publish()
Publishes an event to the node. This is an empty event with no item. This is only acceptable for nodes with ConfigureForm.isPersistItems()=false and ConfigureForm.isDeliverPayloads()=false. This is an asynchronous call which returns as soon as the packet has been sent. For synchronous calls use send().


publish

public void publish(Item item)
Publishes an event to the node. This is a simple item with no payload. If the id is null, an empty item (one without an id) will be sent. Please note that this is not the same as send(), which publishes an event with NO item. This is an asynchronous call which returns as soon as the packet has been sent. For synchronous calls use send(Item)).

Parameters:
item - - The item being sent

publish

public void publish(java.util.Collection<Item> items)
Publishes multiple events to the node. Same rules apply as in publish(Item). In addition, if ConfigureForm.isPersistItems()=false, only the last item in the input list will get stored on the node, assuming it stores the last sent item. This is an asynchronous call which returns as soon as the packet has been sent. For synchronous calls use send(Collection)).

Parameters:
items - - The collection of items being sent

send

public void send()
          throws org.jivesoftware.smack.XMPPException
Publishes an event to the node. This is an empty event with no item. This is only acceptable for nodes with ConfigureForm.isPersistItems()=false and ConfigureForm.isDeliverPayloads()=false. This is a synchronous call which will throw an exception on failure. For asynchronous calls, use publish().

Throws:
org.jivesoftware.smack.XMPPException

send

public void send(Item item)
          throws org.jivesoftware.smack.XMPPException
Publishes an event to the node. This can be either a simple item with no payload, or one with it. This is determined by the Node configuration. If the node has deliver_payload=false, the Item must not have a payload. If the id is null, an empty item (one without an id) will be sent. Please note that this is not the same as send(), which publishes an event with NO item. This is a synchronous call which will throw an exception on failure. For asynchronous calls, use publish(Item).

Parameters:
item - - The item being sent
Throws:
org.jivesoftware.smack.XMPPException

send

public void send(java.util.Collection<Item> items)
          throws org.jivesoftware.smack.XMPPException
Publishes multiple events to the node. Same rules apply as in send(Item). In addition, if ConfigureForm.isPersistItems()=false, only the last item in the input list will get stored on the node, assuming it stores the last sent item. This is a synchronous call which will throw an exception on failure. For asynchronous calls, use publish(Collection)).

Parameters:
items - - The collection of Item objects being sent
Throws:
org.jivesoftware.smack.XMPPException

deleteAllItems

public void deleteAllItems()
                    throws org.jivesoftware.smack.XMPPException
Purges the node of all items.

Note: Some implementations may keep the last item sent.

Throws:
org.jivesoftware.smack.XMPPException

deleteItem

public void deleteItem(java.lang.String itemId)
                throws org.jivesoftware.smack.XMPPException
Delete the item with the specified id from the node.

Parameters:
itemId - The id of the item
Throws:
org.jivesoftware.smack.XMPPException

deleteItem

public void deleteItem(java.util.Collection<java.lang.String> itemIds)
                throws org.jivesoftware.smack.XMPPException
Delete the items with the specified id's from the node.

Parameters:
itemIds - The list of id's of items to delete
Throws:
org.jivesoftware.smack.XMPPException

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 java.lang.String toString()
Overrides:
toString in class java.lang.Object