javax.sip.header
Interface SubscriptionStateHeader

All Superinterfaces:

java.lang.Cloneable, Header, Parameters, java.io.Serializable

public interface SubscriptionStateHeader
extends Parameters, Header

This interface represents the Subscription State header, as defined by RFC3265, this header is not part of RFC3261.

NOTIFY requests MUST contain SubscriptionState headers which indicate the status of the subscription. The subscription states are:

• active - If the SubscriptionState header value is "active", it means that the subscription has been accepted and (in general) has been authorized. If the header also contains an "expires" parameter, the subscriber SHOULD take it as the authoritative subscription duration and adjust accordingly. The "retry-after" and "reason" parameters have no semantics for "active".
• pending - If the SubscriptionState value is "pending", the subscription has been received by the notifier, but there is insufficient policy information to grant or deny the subscription yet. If the header also contains an "expires" parameter, the subscriber SHOULD take it as the authoritative subscription duration and adjust accordingly. No further action is necessary on the part of the subscriber. The "retry-after" and "reason" parameters have no semantics for "pending".
• terminated - If the SubscriptionState value is "terminated", the subscriber should consider the subscription terminated. The "expires" parameter has no semantics for "terminated". If a reason code is present, the client should behave as described in the reason code defined in this Header. If no reason code or an unknown reason code is present, the client MAY attempt to re-subscribe at any time (unless a "retry-after" parameter is present, in which case the client SHOULD NOT attempt re-subscription until after the number of seconds specified by the "retry-after" parameter).

Author:

BEA Systems, NIST

Field Summary

static java.lang.String	ACTIVE State: The subscription has been accepted and (in general) has been authorized.
static java.lang.String	DEACTIVATED Reason Code: The subscription has been terminated, but the subscriber SHOULD retry immediately with a new subscription.
static java.lang.String	GIVE_UP Reason Code: The subscription has been terminated because the notifier could not obtain authorization in a timely fashion.
static java.lang.String	NAME Name of SubscriptionStateHeader
static java.lang.String	NO_RESOURCE Reason Code: The subscription has been terminated because the resource state which was being monitored no longer exists.
static java.lang.String	PENDING State: The subscription has been received by the notifier, but there is insufficient policy information to grant or deny the subscription yet.
static java.lang.String	PROBATION Reason Code: The subscription has been terminated, but the client SHOULD retry at some later time.
static java.lang.String	REJECTED Reason Code: The subscription has been terminated due to change in authorization policy.
static java.lang.String	TERMINATED State: The subscription has been terminated, if a reason code is present, the client should behave as described in the reason code.
static java.lang.String	TIMEOUT Reason Code: The subscription has been terminated because it was not refreshed before it expired.
static java.lang.String	UNKNOWN Reason Code: The reason why the subscription was terminated is Unknown.

Method Summary

int	getExpires() Gets the expires value of the SubscriptionStateHeader.
java.lang.String	getReasonCode() Gets the reason code of SubscriptionStateHeader.
int	getRetryAfter() Gets the retry after value of the SubscriptionStateHeader.
java.lang.String	getState() Gets the state of SubscriptionStateHeader.
void	setExpires(int expires) Sets the relative expires value of the SubscriptionStateHeader.
void	setReasonCode(java.lang.String reasonCode) Sets the reason code value of the SubscriptionStateHeader.
void	setRetryAfter(int retryAfter) Sets the retry after value of the SubscriptionStateHeader.
void	setState(java.lang.String state) Sets the state value of the SubscriptionStateHeader.

Methods inherited from interface javax.sip.header.Parameters

getParameter, getParameterNames, removeParameter, setParameter

Methods inherited from interface javax.sip.header.Header

clone, equals, getName, hashCode, toString

Field Detail

NAME

static final java.lang.String NAME

Name of SubscriptionStateHeader

See Also:

Constant Field Values

UNKNOWN

static final java.lang.String UNKNOWN

Reason Code: The reason why the subscription was terminated is Unknown.

See Also:

Constant Field Values

DEACTIVATED

static final java.lang.String DEACTIVATED

Reason Code: The subscription has been terminated, but the subscriber SHOULD retry immediately with a new subscription. One primary use of such a status code is to allow migration of subscriptions between nodes. The "retry-after" parameter has no semantics for "deactivated".

See Also:

Constant Field Values

PROBATION

static final java.lang.String PROBATION

Reason Code: The subscription has been terminated, but the client SHOULD retry at some later time. If a "retry-after" parameter is also present, the client SHOULD wait at least the number of seconds specified by that parameter before attempting to re-subscribe.

See Also:

Constant Field Values

REJECTED

static final java.lang.String REJECTED

Reason Code: The subscription has been terminated due to change in authorization policy. Clients SHOULD NOT attempt to re-subscribe. The "retry-after" parameter has no semantics for "rejected".

See Also:

Constant Field Values

TIMEOUT

static final java.lang.String TIMEOUT

Reason Code: The subscription has been terminated because it was not refreshed before it expired. Clients MAY re-subscribe immediately. The "retry-after" parameter has no semantics for "timeout".

See Also:

Constant Field Values

GIVE_UP

static final java.lang.String GIVE_UP

Reason Code: The subscription has been terminated because the notifier could not obtain authorization in a timely fashion. If a "retry-after" parameter is also present, the client SHOULD wait at least the number of seconds specified by that parameter before attempting to re-subscribe; otherwise, the client MAY retry immediately, but will likely get put back into pending state.

See Also:

Constant Field Values

NO_RESOURCE

static final java.lang.String NO_RESOURCE

Reason Code: The subscription has been terminated because the resource state which was being monitored no longer exists. Clients SHOULD NOT attempt to re-subscribe. The "retry-after" parameter has no semantics for "noresource".

See Also:

Constant Field Values

ACTIVE

static final java.lang.String ACTIVE

State: The subscription has been accepted and (in general) has been authorized.

See Also:

Constant Field Values

TERMINATED

static final java.lang.String TERMINATED

State: The subscription has been terminated, if a reason code is present, the client should behave as described in the reason code.

See Also:

Constant Field Values

PENDING

static final java.lang.String PENDING

State: The subscription has been received by the notifier, but there is insufficient policy information to grant or deny the subscription yet.

See Also:

Constant Field Values

Method Detail

setExpires

void setExpires(int expires)
                throws InvalidArgumentException

Sets the relative expires value of the SubscriptionStateHeader. The expires value MUST be greater than zero and MUST be less than 2**31.

Parameters:

expires - - the new expires value of this SubscriptionStateHeader.

Throws:

InvalidArgumentException - if supplied value is less than zero.

getExpires

int getExpires()

Gets the expires value of the SubscriptionStateHeader. This expires value is relative time.

Returns:

the expires value of the SubscriptionStateHeader.

setRetryAfter

void setRetryAfter(int retryAfter)
                   throws InvalidArgumentException

Sets the retry after value of the SubscriptionStateHeader. The retry after value MUST be greater than zero and MUST be less than 2**31.

Parameters:

retryAfter - - the new retry after value of this SubscriptionStateHeader

Throws:

InvalidArgumentException - if supplied value is less than zero.

getRetryAfter

int getRetryAfter()

Gets the retry after value of the SubscriptionStateHeader. This retry after value is relative time.

Returns:

the retry after value of the SubscriptionStateHeader.

getReasonCode

java.lang.String getReasonCode()

Gets the reason code of SubscriptionStateHeader.

Returns:

the comment of this SubscriptionStateHeader, return null if no reason code is available.

setReasonCode

void setReasonCode(java.lang.String reasonCode)
                   throws java.text.ParseException

Sets the reason code value of the SubscriptionStateHeader.

Parameters:

reasonCode - - the new reason code string value of the SubscriptionStateHeader.

Throws:

java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the reason code.

getState

java.lang.String getState()

Gets the state of SubscriptionStateHeader.

Returns:

the state of this SubscriptionStateHeader.

setState

void setState(java.lang.String state)
              throws java.text.ParseException

Sets the state value of the SubscriptionStateHeader.

Parameters:

state - - the new state string value of the SubscriptionStateHeader.

Throws:

java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the state.