javax.sip.header

Interface SubscriptionStateHeader

All Superinterfaces:

Cloneable, Header, Parameters, Serializable

All Known Implementing Classes:

SubscriptionState

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).

Version:

1.2

Author:

BEA Systems, NIST

Field Summary

Fields

Modifier and Type	Field and Description
static String	ACTIVE State: The subscription has been accepted and (in general) has been authorized.
static String	DEACTIVATED Reason Code: The subscription has been terminated, but the subscriber SHOULD retry immediately with a new subscription.
static String	GIVE_UP Reason Code: The subscription has been terminated because the notifier could not obtain authorization in a timely fashion.
static String	NAME Name of SubscriptionStateHeader
static String	NO_RESOURCE Reason Code: The subscription has been terminated because the resource state which was being monitored no longer exists.
static 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 String	PROBATION Reason Code: The subscription has been terminated, but the client SHOULD retry at some later time.
static String	REJECTED Reason Code: The subscription has been terminated due to change in authorization policy.
static 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 String	TIMEOUT Reason Code: The subscription has been terminated because it was not refreshed before it expired.
static String	UNKNOWN Reason Code: The reason why the subscription was terminated is Unknown.

Method Summary

Methods

Modifier and Type	Method and Description
int	getExpires() Gets the expires value of the SubscriptionStateHeader.
String	getReasonCode() Gets the reason code of SubscriptionStateHeader.
int	getRetryAfter() Gets the retry after value of the SubscriptionStateHeader.
String	getState() Gets the state of SubscriptionStateHeader.
void	setExpires(int expires) Sets the relative expires value of the SubscriptionStateHeader.
void	setReasonCode(String reasonCode) Sets the reason code value of the SubscriptionStateHeader.
void	setRetryAfter(int retryAfter) Sets the retry after value of the SubscriptionStateHeader.
void	setState(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 String NAME

Name of SubscriptionStateHeader

See Also:

Constant Field Values

UNKNOWN

static final String UNKNOWN

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

See Also:

Constant Field Values

DEACTIVATED

static final 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 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 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 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 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 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 String ACTIVE

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

See Also:

Constant Field Values

TERMINATED

static final 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 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

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(String reasonCode)
                   throws ParseException

Sets the reason code value of the SubscriptionStateHeader.

Parameters:

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

Throws:

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

getState

String getState()

Gets the state of SubscriptionStateHeader.

Returns:

the state of this SubscriptionStateHeader.

setState

void setState(String state)
              throws ParseException

Sets the state value of the SubscriptionStateHeader.

Parameters:

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

Throws:

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