java.lang.Object
- org.jivesoftware.openfire.pubsub.NodeSubscription

```
public class NodeSubscription
extends Object
```
A subscription to a node. Entities may subscribe to a node to be notified when new events are published to the node. Published events may contain a PublishedItem. Only nodes that are configured to not deliver payloads with event notifications and to not persist items will let publishers to publish events without items thus not including items in the notifications sent to subscribers.
Node subscriptions may need to be configured by the subscriber or approved by a node owner to become active. The node configuration establishes whether configuration or approval are required. In any case, the subscriber will not get event notifications until the subscription is active.
Depending on the node configuration it may be possible for the same subscriber to subscribe multiple times to the node. Each subscription may have a different configuration like for instance different keywords. Keywords can be used as a way to filter the type of PublishedItem to be notified of. When the same subscriber has subscribed multiple times to the node a single notification is going to be sent to the subscriber instead of sending a notification for each subscription.

Author:

Matt Tucker

Nested Class Summary

Nested Classes
Modifier and Type Class Description

static class NodeSubscription.State
Subscriptions to a node may exist in several states.

static class NodeSubscription.Type

Constructor Summary

Constructors
Constructor	Description
`NodeSubscription(Node node, org.xmpp.packet.JID owner, org.xmpp.packet.JID jid, NodeSubscription.State state, String id)`	Creates a new subscription of the specified user with the node.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`boolean`	`canSendPublicationEvent(LeafNode leafNode, PublishedItem publishedItem)`	Returns true if an event notification can be sent to the subscriber for the specified published item based on the subscription configuration and subscriber status.
`void`	`configure(org.xmpp.packet.IQ originalIQ, org.xmpp.forms.DataForm options)`	Configures the subscription based on the sent `DataForm` included in the IQ packet sent by the subscriber.
`NodeAffiliate`	`getAffiliate()`	Returns the `NodeAffiliate` that owns this subscription.
`org.xmpp.forms.DataForm`	`getConfigurationForm(Locale preferredLocale)`	Returns a data form with the subscription configuration.
`int`	`getDepth()`	Returns 1 when the subscriber wants to receive notifications only from first-level children of the collection.
`int`	`getDigestFrequency()`	Returns the minimum number of milliseconds between sending any two notification digests.
`Date`	`getExpire()`	Returns the Date at which a leased subscription will end or has ended.
`String`	`getID()`	Returns the ID that uniquely identifies the subscription of the user in the node.
`org.xmpp.packet.JID`	`getJID()`	Returns the JID that is going to receive the event notifications.
`String`	`getKeyword()`	Returns the keyword that the event needs to match.
`Node`	`getNode()`	Returns the node that holds this subscription.
`org.xmpp.packet.JID`	`getOwner()`	Returns the JID of the entity that owns this subscription.
`Collection<String>`	`getPresenceStates()`	The presence states for which an entity wants to receive notifications.
`NodeSubscription.State`	`getState()`	Returns the current subscription state.
`NodeSubscription.Type`	`getType()`	Returns if the owner has subscribed to receive notification of new items only or of new nodes only.
`boolean`	`isActive()`	Returns true if the subscription is active.
`boolean`	`isAuthorizationPending()`	Returns true if the subscription needs to be approved by a node owner to become active.
`boolean`	`isConfigurationPending()`	Returns true if configuration is required by the node and is still pending to be configured by the subscriber.
`boolean`	`isIncludingBody()`	Returns whether an entity wants to receive an XMPP message body in addition to the payload format.
`boolean`	`isUsingDigest()`	Returns whether an entity wants to receive digests (aggregations) of notifications or all notifications individually.
`void`	`sendAuthorizationRequest()`	Sends an request to authorize the pending subscription to all owners.
`void`	`sendAuthorizationRequest(org.xmpp.packet.JID owner)`	Sends a request to authorize the pending subscription to the specified owner.
`boolean`	`shouldDeliverNotifications()`	Returns whether an entity wants to receive or has disabled notifications.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - NodeSubscription
```
public NodeSubscription(Node node,
                        org.xmpp.packet.JID owner,
                        org.xmpp.packet.JID jid,
                        NodeSubscription.State state,
                        String id)
```
    Creates a new subscription of the specified user with the node.
    
    Parameters:
    
    node - Node to which this subscription is interested in.
    
    owner - the JID of the entity that owns this subscription.
    
    jid - the JID of the user that owns the subscription.
    
    state - the state of the subscription with the node.
    
    id - the id the uniquely identifies this subscription within the node.
- Method Detail
  - getNode
```
public Node getNode()
```
    Returns the node that holds this subscription.
    
    Returns:
    
    the node that holds this subscription.
  - getID
```
public String getID()
```
    Returns the ID that uniquely identifies the subscription of the user in the node.
    
    Returns:
    
    the ID that uniquely identifies the subscription of the user in the node.
  - getJID
```
public org.xmpp.packet.JID getJID()
```
    Returns the JID that is going to receive the event notifications. This JID can be the owner JID or a full JID if the owner wants to receive the notification at a particular resource.
    Moreover, since subscriber and owner are separated it should be theoretically possible to have a different owner JID (e.g. gato@server1.com) and a subscriber JID (e.g. gato@server2.com). Note that letting this case to happen may open the pubsub service to get spam or security problems. However, the pubsub service should avoid this case to happen.
    
    Returns:
    
    the JID that is going to receive the event notifications.
  - getOwner
```
public org.xmpp.packet.JID getOwner()
```
    Returns the JID of the entity that owns this subscription. The owner entity will have a NodeAffiliate for the owner JID. The owner may have more than one subscription with the node based on what this message Node.isMultipleSubscriptionsEnabled().
    
    Returns:
    
    he JID of the entity that owns this subscription.
  - getState
```
public NodeSubscription.State getState()
```
    Returns the current subscription state. Subscriptions with status of pending should be authorized by a node owner.
    
    Returns:
    
    the current subscription state.
  - isConfigurationPending
```
public boolean isConfigurationPending()
```
    Returns true if configuration is required by the node and is still pending to be configured by the subscriber. Otherwise return false. Once a subscription is configured it might need to be approved by a node owner to become active.
    
    Returns:
    
    true if configuration is required by the node and is still pending to be configured by the subscriber.
  - isAuthorizationPending
```
public boolean isAuthorizationPending()
```
    Returns true if the subscription needs to be approved by a node owner to become active. Until the subscription is not activated the subscriber will not receive event notifications.
    
    Returns:
    
    true if the subscription needs to be approved by a node owner to become active.
  - shouldDeliverNotifications
```
public boolean shouldDeliverNotifications()
```
    Returns whether an entity wants to receive or has disabled notifications.
    
    Returns:
    
    true when notifications should be sent to the subscriber.
  - isUsingDigest
```
public boolean isUsingDigest()
```
    Returns whether an entity wants to receive digests (aggregations) of notifications or all notifications individually.
    
    Returns:
    
    true when an entity wants to receive digests (aggregations) of notifications.
  - getDigestFrequency
```
public int getDigestFrequency()
```
    Returns the minimum number of milliseconds between sending any two notification digests. Default is 24 hours.
    
    Returns:
    
    the minimum number of milliseconds between sending any two notification digests.
  - getExpire
```
public Date getExpire()
```
    Returns the Date at which a leased subscription will end or has ended. A value of null means that the subscription will never expire.
    
    Returns:
    
    the Date at which a leased subscription will end or has ended. A value of null means that the subscription will never expire.
  - isIncludingBody
```
public boolean isIncludingBody()
```
    Returns whether an entity wants to receive an XMPP message body in addition to the payload format.
    
    Returns:
    
    true when an entity wants to receive an XMPP message body in addition to the payload format
  - getPresenceStates
```
public Collection<String> getPresenceStates()
```
    The presence states for which an entity wants to receive notifications. When the owner is in any of the returned presence states then he is allowed to receive notifications.
    
    Returns:
    
    the presence states for which an entity wants to receive notifications. (e.g. available, away, etc.)
  - getType
```
public NodeSubscription.Type getType()
```
    Returns if the owner has subscribed to receive notification of new items only or of new nodes only. When subscribed to a Leaf Node then only items is available.
    
    Returns:
    
    whether the owner has subscribed to receive notification of new items only or of new nodes only.
  - getDepth
```
public int getDepth()
```
    Returns 1 when the subscriber wants to receive notifications only from first-level children of the collection. A value of 0 means that the subscriber wants to receive notifications from all descendents.
    
    Returns:
    
    1 when the subscriber wants to receive notifications only from first-level children of the collection or 0 when notififying only from all descendents.
  - getKeyword
```
public String getKeyword()
```
    Returns the keyword that the event needs to match. When null all event are going to be notified to the subscriber.
    
    Returns:
    
    the keyword that the event needs to match. When null all event are going to be notified to the subscriber.
  - configure
```
public void configure(org.xmpp.packet.IQ originalIQ,
                      org.xmpp.forms.DataForm options)
```
    Configures the subscription based on the sent DataForm included in the IQ packet sent by the subscriber. If the subscription was pending of configuration then the last published item is going to be sent to the subscriber. The originalIQ parameter may be null when using this API internally. When no IQ packet was sent then no IQ result will be sent to the sender. The rest of the functionality is the same.
    
    Parameters:
    
    originalIQ - the IQ packet sent by the subscriber to configure his subscription or null when using this API internally.
    
    options - the data form containing the new subscription configuration.
  - getConfigurationForm
```
public org.xmpp.forms.DataForm getConfigurationForm(Locale preferredLocale)
```
    Returns a data form with the subscription configuration. The data form can be used to edit the subscription configuration.
    
    Parameters:
    
    preferredLocale - The preferred locale to localize the form.
    
    Returns:
    
    data form used by the subscriber to edit the subscription configuration.
  - canSendPublicationEvent
```
public boolean canSendPublicationEvent(LeafNode leafNode,
                                       PublishedItem publishedItem)
```
    Returns true if an event notification can be sent to the subscriber for the specified published item based on the subscription configuration and subscriber status.
    
    Parameters:
    
    leafNode - the node that received the publication.
    
    publishedItem - the published item to send or null if the publication didn't contain an item.
    
    Returns:
    
    true if an event notification can be sent to the subscriber for the specified published item.
  - isActive
```
public boolean isActive()
```
    Returns true if the subscription is active. A subscription is considered active if it has not expired, it has been approved and configured.
    
    Returns:
    
    true if the subscription is active.
  - getAffiliate
```
public NodeAffiliate getAffiliate()
```
    Returns the NodeAffiliate that owns this subscription. Users that have a subscription with the node will ALWAYS have an affiliation even if the affiliation is of type none.
    
    Returns:
    
    the NodeAffiliate that owns this subscription.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - sendAuthorizationRequest
```
public void sendAuthorizationRequest(org.xmpp.packet.JID owner)
```
    Sends a request to authorize the pending subscription to the specified owner.
    
    Parameters:
    
    owner - the JID of the user that will get the authorization request.
  - sendAuthorizationRequest
```
public void sendAuthorizationRequest()
```
    Sends an request to authorize the pending subscription to all owners. The first answer sent by a owner will be processed. Rest of the answers will be discarded.

Modifier and Type	Class	Description
`static class`	`NodeSubscription.State`	Subscriptions to a node may exist in several states.
`static class`	`NodeSubscription.Type`

Class NodeSubscription

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

NodeSubscription

Method Detail

getNode

getID

getJID

getOwner

getState

isConfigurationPending

isAuthorizationPending

shouldDeliverNotifications

isUsingDigest

getDigestFrequency

getExpire

isIncludingBody

getPresenceStates

getType

getDepth

getKeyword

configure

getConfigurationForm

canSendPublicationEvent

isActive

getAffiliate

toString

sendAuthorizationRequest

sendAuthorizationRequest