001: /**
002: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
003: * Unpublished - rights reserved under the Copyright Laws of the United States.
004: * Copyright © 2003 Sun Microsystems, Inc. All rights reserved.
005: * Copyright © 2005 BEA Systems, Inc. All rights reserved.
006: *
007: * Use is subject to license terms.
008: *
009: * This distribution may include materials developed by third parties.
010: *
011: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
012: *
013: * Module Name : JSIP Specification
014: * File Name : SubscriptionStateHeader.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 13/12/2002 Phelim O'Doherty Initial version, extension header to
020: * support RFC3265
021: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
022: */package javax.sip.header;
023:
024: import javax.sip.InvalidArgumentException;
025: import java.text.ParseException;
026:
027: /**
028: * This interface represents the Subscription State header, as
029: * defined by <a href = "http://www.ietf.org/rfc/rfc3265.txt">RFC3265</a>, this
030: * header is not part of RFC3261.
031: * <p>
032: * NOTIFY requests MUST contain SubscriptionState headers which indicate the
033: * status of the subscription. The subscription states are:
034: * <ul>
035: * <li> active - If the SubscriptionState header value is "active", it means
036: * that the subscription has been accepted and (in general) has been authorized.
037: * If the header also contains an "expires" parameter, the subscriber SHOULD
038: * take it as the authoritative subscription duration and adjust accordingly.
039: * The "retry-after" and "reason" parameters have no semantics for "active".
040: * <li> pending - If the SubscriptionState value is "pending", the
041: * subscription has been received by the notifier, but there is insufficient
042: * policy information to grant or deny the subscription yet. If the header also
043: * contains an "expires" parameter, the subscriber SHOULD take it as the
044: * authoritative subscription duration and adjust accordingly. No further
045: * action is necessary on the part of the subscriber. The "retry-after" and
046: * "reason" parameters have no semantics for "pending".
047: * <li> terminated - If the SubscriptionState value is "terminated", the
048: * subscriber should consider the subscription terminated. The "expires"
049: * parameter has no semantics for "terminated". If a reason code is present, the
050: * client should behave as described in the reason code defined in this Header.
051: * If no reason code or an unknown reason code is present, the client MAY
052: * attempt to re-subscribe at any time (unless a "retry-after" parameter is
053: * present, in which case the client SHOULD NOT attempt re-subscription until
054: * after the number of seconds specified by the "retry-after" parameter).
055: * </ul>
056: *
057: * @author BEA Systems, NIST
058: * @version 1.2
059: */
060:
061: public interface SubscriptionStateHeader extends Parameters, Header {
062:
063: /**
064: * Sets the relative expires value of the SubscriptionStateHeader. The
065: * expires value MUST be greater than zero and MUST be less than 2**31.
066: *
067: * @param expires - the new expires value of this SubscriptionStateHeader.
068: * @throws InvalidArgumentException if supplied value is less than zero.
069: */
070: public void setExpires(int expires) throws InvalidArgumentException;
071:
072: /**
073: * Gets the expires value of the SubscriptionStateHeader. This expires value is
074: * relative time.
075: *
076: * @return the expires value of the SubscriptionStateHeader.
077: */
078: public int getExpires();
079:
080: /**
081: * Sets the retry after value of the SubscriptionStateHeader. The retry after value
082: * MUST be greater than zero and MUST be less than 2**31.
083: *
084: * @param retryAfter - the new retry after value of this SubscriptionStateHeader
085: * @throws InvalidArgumentException if supplied value is less than zero.
086: */
087: public void setRetryAfter(int retryAfter)
088: throws InvalidArgumentException;
089:
090: /**
091: * Gets the retry after value of the SubscriptionStateHeader. This retry after
092: * value is relative time.
093: *
094: * @return the retry after value of the SubscriptionStateHeader.
095: */
096: public int getRetryAfter();
097:
098: /**
099: * Gets the reason code of SubscriptionStateHeader.
100: *
101: * @return the comment of this SubscriptionStateHeader, return null if no reason code
102: * is available.
103: */
104: public String getReasonCode();
105:
106: /**
107: * Sets the reason code value of the SubscriptionStateHeader.
108: *
109: * @param reasonCode - the new reason code string value of the SubscriptionStateHeader.
110: * @throws ParseException which signals that an error has been reached
111: * unexpectedly while parsing the reason code.
112: */
113: public void setReasonCode(String reasonCode) throws ParseException;
114:
115: /**
116: * Gets the state of SubscriptionStateHeader.
117: *
118: * @return the state of this SubscriptionStateHeader.
119: */
120: public String getState();
121:
122: /**
123: * Sets the state value of the SubscriptionStateHeader.
124: *
125: * @param state - the new state string value of the SubscriptionStateHeader.
126: * @throws ParseException which signals that an error has been reached
127: * unexpectedly while parsing the state.
128: */
129: public void setState(String state) throws ParseException;
130:
131: /**
132: * Name of SubscriptionStateHeader
133: */
134: public final static String NAME = "Subscription-State";
135:
136: //Reason Code Constants
137:
138: /**
139: * Reason Code: The reason why the subscription was terminated is Unknown.
140: */
141: public final static String UNKNOWN = "Unknown";
142:
143: /**
144: * Reason Code: The subscription has been terminated, but the subscriber SHOULD retry
145: * immediately with a new subscription. One primary use of such a status
146: * code is to allow migration of subscriptions between nodes. The
147: * "retry-after" parameter has no semantics for "deactivated".
148: */
149: public final static String DEACTIVATED = "Deactivated";
150:
151: /**
152: * Reason Code: The subscription has been terminated, but the client SHOULD retry at
153: * some later time. If a "retry-after" parameter is also present, the client
154: * SHOULD wait at least the number of seconds specified by that parameter
155: * before attempting to re-subscribe.
156: */
157: public final static String PROBATION = "Probation";
158:
159: /**
160: * Reason Code: The subscription has been terminated due to change in authorization
161: * policy. Clients SHOULD NOT attempt to re-subscribe. The "retry-after"
162: * parameter has no semantics for "rejected".
163: */
164: public final static String REJECTED = "Rejected";
165:
166: /**
167: * Reason Code: The subscription has been terminated because it was not refreshed before
168: * it expired. Clients MAY re-subscribe immediately. The "retry-after"
169: * parameter has no semantics for "timeout".
170: */
171: public final static String TIMEOUT = "Timeout";
172:
173: /**
174: * Reason Code: The subscription has been terminated because the notifier could not
175: * obtain authorization in a timely fashion. If a "retry-after" parameter
176: * is also present, the client SHOULD wait at least the number of seconds
177: * specified by that parameter before attempting to re-subscribe; otherwise,
178: * the client MAY retry immediately, but will likely get put back into
179: * pending state.
180: */
181: public final static String GIVE_UP = "Give-Up";
182:
183: /**
184: * Reason Code: The subscription has been terminated because the resource state which was
185: * being monitored no longer exists. Clients SHOULD NOT attempt to
186: * re-subscribe. The "retry-after" parameter has no semantics for "noresource".
187: */
188: public final static String NO_RESOURCE = "No-Resource";
189:
190: // State constants
191:
192: /**
193: * State: The subscription has been accepted and (in general) has been
194: * authorized.
195: */
196: public final static String ACTIVE = "Active";
197:
198: /**
199: * State: The subscription has been terminated, if a reason code is present,
200: * the client should behave as described in the reason code.
201: */
202: public final static String TERMINATED = "Terminated";
203:
204: /**
205: * State: The subscription has been received by the notifier, but there is
206: * insufficient policy information to grant or deny the subscription yet.
207: */
208: public final static String PENDING = "Pending";
209:
210: }
|