Find JSRs
Submit this Search

Ad Banner

JSR 32 - JAIN SIP Specification

JSR 32 - JAIN SIP v1.1 Specification
Final Change Log

Author: Phelim O'Doherty, Sun Microsystems

  1. Repackage the JAIN SIP Specification under 'javax.sip' as opposed to 'jain.protocol.ip.sip'. 

    IMPACT: There is agreement in the development community that this is a better packaging structure, however this has implications on the backwards compatibility of the API, the maintenance lead has worked with the JAIN SIP Community at '' to ensure this non backwards compatibility change is acceptable to the development community. 

  2. The JAIN SIP specification will tighten its default behaviour/scope to explicitly state that two types of configurations are allowed for a JAIN SIP implementation, stateful and stateless. A stateful implementation of JAIN SIP implements the state machine which must be an exact representation of the SIP common transaction layer for User Agent [CS] and stateful Proxies as specified by Chapter 17 of the SIP RFC 3261, which is independent of the TU core used i.e UAC,  UAS or stateful proxy. A stateless implementation of JAIN SIP leaves the TU core i.e. stateless proxy or protocol tester in charge of implementing the state machine, it is the TU's responsibility to manage retransmissions and all responses and requests corresponding to the outstanding transactions are made visible to the TU.

    IMPACT: JAIN SIP upon instantiation will operate in either stateful or stateless behaviour, with a mechanism that allow stateful implementations to handle specific requests statelessly, i.e. unrecognized transactions.

  3. Explicitly tighten up JAIN SIP architecture model.

    IMPACT:  Muliple ListeningPoints can be contained by a single SipStack at any specific time. A single SipStack can be associated with multiple SipProviders, however a single SipProvider can only be associated with a single SipStack. A single SipProvider can be associated with one ListeningPoint. JAIN SIP allows only a single SipListener in the system, therefore a single SipListener can be registered with a SipProvider at any specific time. Therefore there is an explicit M:1:M:1 relationship between ListeningPoint:SipStack:SipProvider:SipListener. A JAIN SIP application must implement a single SipListener Object that will act as a proxy object and pass all events to the TU. This higher level core application programming logic is outside the scope of JAIN SIP. A SIP Lite implementation, SIP Servlet or an EJB SIP implementation can implement the UAS, UAC and Proxy cores respectively on top of JAIN-SIP as defined by RFC3261.

  4. JAIN SIP will provide a convenience utility to allow a JAIN SIP implementation to be configured to handle all retransmissions i.e. 2xx's and ACK's for an invite transaction, when being used by a UA core. This feature can be turned 'on or off' and is not default behaviour.

    IMPACT: Specify a mechanism to set retransmission scheme to FULL and define restrictions associated with this behaviour and define a mechanism to alert the application when no response was recieved after the maximum number of retransmissions, i.e. TRANSACTION_EXPIRED.

  5. JAIN SIP must be able to support recieiving messages same port and interface for TCP. This is because a message may need to be sent using TCP, rather than UDP, if it is too large.

    IMPACT: Enable multiple providers on the same port with different transports.

  6. Update JAIN SIP specification to the latest protocol changes in the SIP RFC3261 including Dialog semantics.

    IMPACT:  Support new functionality supported in the current SIP RFC.

  7. Add generic Error handling mechanism for transport or implementational defined errors.

    IMPACT: Additional mechanism to report errors not defined in the specification.

  8. Deprecate lazy parsing at the JAIN SIP API level this can be handled within the implementation of the specification.

    IMPACT: This involves removing 'throws SIPParseException' of all get methods.

  9. Support functionality outlined in the following SIP RFC's:  RFC 3261 functionality and the following SIP extensions; the INFO method (RFC 2976), Reliability of provisional responses (RFC 3262), Event Notification Framework (RFC 3265), the UPDATE method (RFC 3311), the Reason Header (RFC 3326), the Message method (RFC 3428) defined for instant messaging and the REFER method (RFC 3515).

    IMPACT: Update JAIN SIP API with relevent changes outlined in RFC's.

  10. Define a simple generic framework for handling protocol extensions.  

    IMPACT: Allows JAIN SIP to be extensible with regards to additional protocol extensions.

SipProvider Interface

  1. Deprecate the sendBye method with invite transaction and replace with a new createRequest method on an Dialog.

    IMPACT: As the JAIN SIP API support Dialog's, a BYE is better suited to Dialog's as opposed to INVITE transactions.

  2. Remove 'throws SipListenerNotRegisteredException' from removeSipListener method and deprecate Exception. 

    IMPACT:  Application programmer no longers need to catch exception not defined in the JavaBean event pattern.

  3. Remove 'throws SipListenerAlreadyRegisteredException' from addSipListener method and deprecate Exception.

    IMPACT:  Application programmer no longers need to catch exception not defined in the JavaBean event pattern. 

  4. Clearly define semantics of stateful and stateless behaviour of an implementation through the transaction model. This is necessary as multiple TU's in a SIP application server may expect different behaviour from the same SIP Stack servicing the Application server. JAIN SIP must also be able to transition between stateful and stateless behaviour for handling of requests assuming no contracts have been broken that prevent this.

    IMPACT: A single JAIN SIP Provider must be able to support a TU's that requires both stateful or stateless behaviour during operation. This allows a TU applications with different behavioural requirements to interact with the same JAIN SIP stack on a per call basis. These semantics prevent hard coding the TU operation mode in the JAIN SIP implementation.

SipStack Interface

  1. Return empty Iterators instead of null values in getListeningPoints and getSipProviders.

    IMPACT: Make application programmer code simplier, by removing explicit check for null as opposed to using the hasMore( ) method on Iterator.

  2. Introduce management capabilities for ListeningPoints. 

    IMPACT: This allows users to dynamically create listening points and start/stop the existing SIP stack while configuring the ListeningPoint of a JAIN SIP Stack, therefore these methods must throw exceptions for those stacks that don't allow permissions to configure the underlying JAIN SIP Stack. 

  3. Deprecate getSipProviders and replace with getSipProvider.

    IMPACT: The JAIN SIP architecture now mandates a single SIP Provider.

  4. Introduce management capabilities to route requests based on arbitrary routing schemes rather than just on the request URI, as well as capibilities to set the OutBound Proxy.

    IMPACT: These management capabilities can be implemented by  the JAIN-SIP stack to make routing decisions so that these are not hard-coded into the implementation itself. A Router interface could have methods to return a list of destinations in order of priority.

  5. Introduce management capabilities to handle both stateful and stateless operating modes and clearly define retransmission schemes associated with each mode.

    IMPACT: This ensures clear semantics of behaviour of a JAIN SIP implementation however does not limit the flexibility of JAIN SIP for different  applications.

SipFactory Interface

  1. Deprecate getPathName and setPathName methods and add string classname argument to the createSipStack method.

    IMPACT: Removes additional programming step from SipStack creation.

Request Interface

  1. Introduce an easy way of including extension headers and bodies in Response messages. 

    IMPACT: This involves adding a new method to the Request interface to create a default response from this request.

AddressFactory Interface

  1. Deprecate createURI(String scheme, String schemeData) method.

    IMPACT: Align with SipServlet specification.

HeaderFactory Interface

  1. Add factory methods for newly supported headers, see Headers.

    IMPACT: Enables the creation of newly formatted headers.

  2. Deprecate HideHeader, EncryptionHeader and ResponseKeyHeader factory methods, see Headers.

    IMPACT: Deprecate headers removed from RFC 3261.

  3. Add hasEncoding and removeEncoding methods to the AcceptEncodingHeader.

    IMPACT: Enables the Accept-Encoding to be empty.

AllowHeader Class

  1. Fix name constant in class from 'Accept' to 'Allow'

    IMPACT: Fixes bug in JAIN SIP v1.0 specification.


  1. Add new Header interfaces for AlertInfoHeader, AuthentificationInfoHeader, CallInfoHeader, ContentDispositionHeader, ContentLanguageHeader, ErrorInfoHeader, InReplyToHeader, MIMEVersionHeader, MinExpiresHeader, ReplyToHeader and SupportedHeader.

    IMPACT: This updates JAIN SIP with the latest Headers in RFC3261.

  2. Deprecate HideHeader, EncryptionHeader and ResponseKeyHeader.

    IMPACT: This updates JAIN SIP with the latest Headers in RFC3261.

  3. Add new Headers from RFC's:
    RFC3262 - RAckHeader and RSeqHeaders for the reliable delivery of provisional responses.
    RFC3265 - AllowEventsHeader, EventHeader and SubscriptionStateHeader to support the event notification framework.
    RFC3326 - ReasonHeader to support information on why the request was issued.
    RFC3515 - ReferToHeader to support recipients to refer requests to another resource

    IMPACT: This updates JAIN SIP with the latest Headers in newly supporting RFC's.

  4. Deprecated setDate(String), setDate(Date), getDate and isDate in ExpiresHeader and RetryAfterHeader.

    IMPACT: These methods are not required within the headers.

  5. Deprecated the getAction, hasAction, removeAction and setAction in ContactHeader.

    IMPACT: These methods are not required within the header.

  6. Add the magic cookie "z9hG4bK" as a constant in ViaHeader.

    IMPACT: Convenience constant for Via headers.


  1. Deprecate (3XX)SEE_OTHER, (4XX)CONFLICT, LENGTH_REQUIRED Responses.

    IMPACT: This updates JAIN SIP with the latest Responses in RFC3261.


    IMPACT: This updates JAIN SIP with the latest Responses in RFC3261.

  3. Deprecate URI_TOO_LARGE and replace with URI_TOO_LONG.

    IMPACT: This keeps consistent with RFC 3261.


    IMPACT: This keeps consistent with RFC 3261.


    IMPACT: This keeps consistent with RFC 3261.

  6. Deprecate GATEWAY_TIME_OUT and replace with SERVER_TIMEOUT.

    IMPACT: This keeps consistent with RFC 3261.


    IMPACT: This keeps consistent with RFC 3261.

  8. Deprecate NOT_ACCEPTABLE_ANYWHERE and replace with NOT_ACCEPTABLE.

    IMPACT: This keeps consistent with RFC 3261.

Message Interface

  1. Add Deep Copy Clone semantics to the all SIP Messages.

    IMPACT: This facility will dramatically reduce the overhead for proxy TU's.


  1. Add additional TelURL class as defined by RFC 2806 in the address package.

    IMPACT: Missing in previous draft of specification.

  2. Deprecate SipURL and replace with SipURI for both "sip:" and "sips:" schemes following RFC 2396.

    IMPACT: Update to recent addressing schema defined in the RFC3261.

REJECTED CHANGES - Not deemed necessary by Spec leads

Define a new ParserUtility Interface.

- ParserUtility Interface

  1. Add parseURI(String URI) method.
  2. Add parseAddress(String addressName) method.
  3. Add generic parseHeader(String header) method.
  4. Add generic parseMessage(String message) method.
REASON: Factory methods take care of this Parsing, a better logical fit within the specification.

URI Interface

Deprecate URI interface and replace with

REASON: is final and can't be extended by SIP URI and Tel URL.