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 : EventHeader.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 java.text.ParseException;
025:
026: /**
027: * This interface represents the Event SIP header, as defined by
028: * <a href = "http://www.ietf.org/rfc/rfc3265.txt">RFC3265</a>, this header is
029: * not part of RFC3261.
030: * <p>
031: * For the purposes of matching responses and NOTIFY messages with SUBSCRIBE
032: * messages, the event-type portion of the "Event" header is compared
033: * byte-by-byte, and the "id" parameter token (if present) is compared
034: * byte-by-byte. An "Event" header containing an "id" parameter never matches
035: * an "Event" header without an "id" parameter. No other parameters are
036: * considered when performing a comparison, i.e. "Event: foo; id=1234" would
037: * match "Event: foo; param=abcd; id=1234", but not "Event: Foo; id=1234".
038: * <p>
039: * There MUST be exactly one event type listed per event header. Multiple events
040: * per message are disallowed i.e Subscribers MUST include exactly one "Event"
041: * header in SUBSCRIBE requests, indicating to which event or class of events
042: * they are subscribing. The "Event" header will contain a token which indicates
043: * the type of state for which a subscription is being requested. This token
044: * will correspond to an event package which further describes the semantics of
045: * the event or event class. The "Event" header MAY also contain an "id" parameter.
046: * When a subscription is created in
047: * the notifier, it stores the event package name and the "Event" header "id"
048: * parameter (if present) as part of the subscription information.
049: * <p>
050: * This "id" parameter, if present:
051: * <ul>
052: * <li>contains an opaque token which identifies the specific subscription
053: * within a dialog.
054: * <li>is only valid within the scope of a single dialog.
055: * <li>if contained in the initial SUBSCRIBE message on the "Event" header, then
056: * refreshes of the subscription must also contain an identical "id" parameter,
057: * they will otherwise be considered new subscriptions in an existing dialog.
058: * <li>if present in the SUBSCRIBE message, that "id" parameter MUST also be
059: * present in the corresponding NOTIFY messages.
060: * </ul>
061: * If the event package to which the event token corresponds defines behavior
062: * associated with the body of its SUBSCRIBE requests or parameters for the
063: * Event header, those semantics apply.
064: *
065: * @author BEA Systems, NIST
066: * @version 1.2
067: */
068:
069: public interface EventHeader extends Parameters, Header {
070:
071: /**
072: * Sets the eventType to the newly supplied eventType string.
073: *
074: * @param eventType - the new string defining the eventType supported
075: * in this EventHeader
076: * @throws ParseException which signals that an error has been reached
077: * unexpectedly while parsing the eventType value.
078: */
079: public void setEventType(String eventType) throws ParseException;
080:
081: /**
082: * Gets the eventType of the EventHeader.
083: *
084: * @return the string object identifing the eventType of EventHeader.
085: */
086: public String getEventType();
087:
088: /**
089: * Sets the id to the newly supplied eventId string.
090: *
091: * @param eventId - the new string defining the eventId of this EventHeader
092: * @throws ParseException which signals that an error has been reached
093: * unexpectedly while parsing the eventId value.
094: */
095: public void setEventId(String eventId) throws ParseException;
096:
097: /**
098: * Gets the id of the EventHeader. This method may return null if the
099: * eventId is not set.
100: *
101: * @return the string object identifing the eventId of EventHeader.
102: */
103: public String getEventId();
104:
105: /**
106: * Name of EventHeader
107: */
108: public final static String NAME = "Event";
109:
110: }
|