Change-Log for JSIP v1.2

Package javax.sip

• Add new class IOExceptionEvent.java
  Asynchronous IO Exceptions may occur as a result of errors during retransmission of requests. The transaction state machine require to report IO Exceptions to the application immediately (according to RFC 3261). The current design only supports delayed reporting through timeouts. This class represents an IOException event that is passed from a SipProvider to its SipListener. This event enables an implementation to propagate the asynchronous handling of IO Exceptions to the application. An application (SipListener) will register with the SIP protocol stack (SipProvider) and listen for IO Exceptions from the SipProvider.

• Limit the architecture to have a single SipProvider in the architecture.  Multiple SipProviders were supported in JSIPv1.1 to enable messaging over different transports. This can still be achieved by limiting a single SipProvider in the system and mandating that the SipProvider uses the same transport for sending responses that was used for sending the outbound request.
  

SipProvider

• Add new method getNewClientDialog(Response).
  Creates a client dialog using the given response. The client calls this method when it receives a response to a previously sent request. This method may only be called when a response is received for a a previously sent dialog creating request. This method is useful when the application wants to manage its own Dialog layer. For example a use agent may create multiple dialogs.
  
• Add new method getNewServerDialog(Response).
  Create a server dialog using the given response. This method may only be called when sending a response to a dialog creating request. The server side of a dialog calls this method before sending out the response to a dialog creating request. The caller is required to set up the tags and other information in the response before calling this method. This method is useful when the application wants to manage its own Dialog layer for example a proxy server.

• Deprecate setListeningPoint() and getListeningPoint() methods
  This method is deprecated as a single SipProvider can be used to send messages independent of the type of transport. That is that a separate SipProvider object is no longer required to send messages across different transports.
• Documentation clarification on refined architecture object model.
  This specification defines a one-to-one relationship between a SipProvider and a SipStack and a one-to-one relationship between a SipProvider and a SipListener.
  

Dialog

• sendAck() method behavior clarified as follows:
  Sends ACK or PRACK Request to the remote party of this dialog. This method implies that the application is functioning as User Agent Client hence the underlying SipProvider acts statefully. This method does not increment the local sequence number.

Transaction

• getDialog() method behavior clarified as follows:
  Gets the dialog object of this transaction object. A dialog only exists for a transaction when a session is setup between a User Agent Client and a User Agent Server, either by a 1xx Provisional Response for an early dialog or a 200OK Response for a committed dialog. If the stack is configured with the AUTOMATIC_DIALOG_SUPPORT property set to on ( default behavior ) then the following behavior is defined:
• If the transaction is associated with an existing Dialog or could result in a Dialog being created in the future (i.e.. the stack is configured to recognize the method as a Dialog creating method or is one of the natively supported dialog creating methods such as INVITE, SUBSCRIBE or NOTIFY), then the implementation must either associate the transaction with the existing Dialog or create a Dialog with null state. 
• If the Transaction is neither dialog creating nor can be associated with an existing dialog, then the implementation must return null when the application issues getDialog on the transaction. If the stack is configured with AUTOMATIC_DIALOG_SUPPORT property set to off then the stack does not automatically create a Dialog for a transaction nor does it maintain an association between dialog and transaction on behalf of the application. Hence this method will return 'null' - in this case it is the responsibility of the application to create a Dialog and associate it with the transaction when the response is sent if required.
• Add new getApplicationData() and setApplicationData(Object) methods.
  Gets application specific data to this transaction. This specification does not define the format of this data. This is the responsibility of the application and is dependent upon the application. For example this capability may be useful for proxy servers to associate the transaction to some application state.
  

TransactionState

• Override equals() and hashCode() methods.
  These methods tighten up equality tests and hashcode generation.
  

ListeningPoint

• Add new getIPAddress() method.
  This method returns the IP address of the ListeningPoint. Assigning IP Address to the ListeningPoint enables the stack to support multi-homed hosts.
  

SipListener

• Add new method processIOException
  This method enables applications to receive asynchronously reported IOExceptionEvents from the SipProvider. 

SipStack

• Add new method createListeningPoint(String, int, String)
  This method enables applications to create ListeningPoints with a specified IP Address. In a multi-homed host, you may create different dialogs with different IP addresses and ports. When this method is called, the listening point will be created with the specified IP address and the default IP address of the stack is ignored. 
• createListeningPoint(int, String) method behavior as follows:
  With the inclusion of the new createListeningPoint method the original method that does not specify the IP address as a parameter will use the default address of the stack. 
• Add new AUTOMATIC_DIALOG_SUPPORT property.
  This property specifies the defined values 'ON' and 'OFF'. The default value is 'ON' and aligns to the defined stack operation behavior defined by JSIPv1.1. The default behavior represents a common mode of stack operation and allows the construction of simple user agents. This is summarized as:
• A dialog gets created on a dialog creating transaction.
• The first 2xx response to the transaction will drive the dialog to the CONFIRMED state.
• Additional 2xx responses to the transaction will be Acked automatically if the RETRANSMISSION_FILTER is enabled.
• Additional 2xx responses to the transaction will be presented to the application with a 'null' transaction identifier if the RETRANSMISSION_FILTER is disabled.

The ability to turn of dialog support is motivated by dialog free servers (such as proxy servers) that do not want to pay the overhead of the dialog layer and user agents that may want to create multiple dialogs for a single INVITE (as a result of forking by proxy servers). The following behavior is defined when the configuration parameter is set to 'OFF'.

• The application is responsible to create the Dialog if desired.
• The application may create a Dialog and associate it with a response (provisional or final) of a dialog creating request. 

• Clarify RETRANSMISSION_FILTER property behavior.
  Add additional behavior to define that if the AUTOMATIC_DIALOG_SUPPORT is set to 'OFF' and the RETRANSMISSION_FILTER is set to 'ON' then the stack will handle retransmission's for any application created dialogs. Clarify application responsibility when retransmission filter is enabled/disabled for example when the dialog creating transaction times out and retransmission filter is enabled, the Dialog is marked TERMINATED. The application is responsible to send the BYE on the terminated dialog.
• Add new NETWORK_LAYER_PATH property.
  The Network Layer object allows the application to have explicit access to the Sockets that the stack creates.  This property sets the fully qualified classpath to the application supplied Network Layer object that determines how to route messages before a dialog is established i.e. com.sun.javax.sip.address.NetworkLayerImpl. An application defined network layer object must implement the javax.sip.address.NetworkLayer interface. The classpath can not be  the same as the underlying stack implementation as a vendor will  provide an implementation of this interface also. This property is optional. 
• Deprecate createSipProvider(ListeningPoint) method.
  This method is no longer required as a single ListeningPoint is no longer required to be associated with a SipProvider. That is a single transport (hence listeningPoint) per SipProvider.
• Add new createSipProvider() method.
  This method enables a single SipProvider to be created in the system independent of any transport. The association to ListeningPoints can be made from SipStack interface as there is a one-to-one relationship between SipProvider and SipStack.
• Add new method stop(int)
  This method shuts down the stack gracefully. An implementation of this method should mark the stack as in the stopping state. The stack can handle gracefully handle all existing transactions and dialog. Once all existing  transactions and dialogs are completed, all SipProviders are removed, all ListeningPoints are removed and any other stack resources are released. A stopping stack may not create any dialogs or transactions or process any further messages until it is re-created. A timeout parameter may be passed to this method to forcefully remove all dialogs and transaction after the specified timeout period. A state machine may be introduced to the SipStack as a result of this method.
  

RequestEvent

• Add new method getDialog()
  This method separates transaction support from dialog support. This enables application developers to access the dialog associated to this event without having to query the transaction associated to the event. 

ResponseEvent

• Add new method getDialog()
  This method separates transaction support from dialog support. This enables application developers to access the dialog associated to this event without having to query the transaction associated to the event. For example the transaction associated with the event may return 'null' because the final response for the transaction has already been received and the stack has no more record of the transaction. This situation can occur when a UAC sends requests out through a forking proxy. Responses that all refer to the same transaction may be sent by the targets of the fork but each response may be stamped with a different To tag, thus referring to different Dialogs on the UAC. The first final response terminates the transaction but the UAC may want to create a Dialog on a subsequent response.

Package javax.sip.address

• Add new interface NetworkLayer.java
  This new interface enable applications access to the sockets that are used by the stack to send out messages e.g. a STUN application. An application may implement this interface and register it as a property when the stack is created. A compliant implementation of this specification will provide a default implementation of this interface, which may be overridden by the application.

• Override equals() method
  This provides clarity around object equality.
  

• Add new methods getPhoneContext() and setPhoneContext(String)
  These new methods enable the phone context parameter to read and written in the TelURL.
• Override equals() method
  This provides clarity around object equality.
  

Package javax.sip.header

HeaderFactory

• createToHeader() method behavior clarified as follows:
  Define that 'null' is accepted for the tag value of a ToHeader.

Package javax.sip.message

Request

• clone() method behavior clarified as follows:
  The message contents are cloned as follows:
  • If the content is of type byte[] a new byte[] array is allocated and the original contents are copied over to the cloned request.
  • If the content is of type String then a new String equal to the old String is allocated and assigned to the cloned request.
  • If the content is of type Object and it has a public clone method then it is invoked and the resultant Object is used in the new cloned SipRequest.

Message

• getUnrecognizedHeaders() method behavior clarified as follows:
  Gets a ListIterator over all the UnrecognizedHeaders in this Message. Note the order of the UnrecognizedHeaders in the ListIterator is the same as order in which they appeared in the SIP Message. UnrecognizedHeaders are headers that the underlying implementation does not recognize. If the message is missing a required header (From, To, Call-ID, CSeq, Via) the entire message  willbe dropped by the underlying implementation and the header will not be included in the list. Headers that are part of the supported set of headers but are not properly formatted will be included in this list. Note that Headers that are not part of the supported set of headers are retrieved as Extension Headers. These must have a name:value format else they will be rejected by the underling implementation and included in this list. A Proxy should not delete UnrecognizedHeaders and should add these Headers to the end of the header list of the Message that is being forwarded. A User Agent may display these unrecognized headers to the user.
• Add new method addHeaderFirst(Header)
  This method adds the new Header to the head of the existing list of Headers contained in this Message. The Header is added to the beginning of the List and will appear in that order in the SIP Message. Required Headers that are singletons should not be added to the message as they already exist in the message and therefore should be changed using the Message.setHeader(Header) method. For example adding a Record-Route header to the start of the header list in a message.
  

MessageFactory

• createRequest(String) method behavior clarified as follows:
  If the argument passed to this method is null then an empty Request is created. An empty request may be used to send out "keep alive" messages for a connection.
• Add new method createResponse(String)
  Creates and parses a Response from a string. This is useful for applications such as protocol test tools that may need to create responses independent of requests.