NIST-SIP: The Reference Implementation for JAIN-SIP 1.2

gov.nist.javax.sip
Class SipProviderImpl

java.lang.Object
  extended by gov.nist.javax.sip.SipProviderImpl
All Implemented Interfaces:
SIPTransactionEventListener, EventListener, SipProvider

public class SipProviderImpl
extends Object
implements SipProvider, SIPTransactionEventListener

Implementation of the JAIN-SIP provider interface.

Version:
1.2 $Revision: 1.66 $ $Date: 2009/08/20 19:01:24 $
Author:
M. Ranganathan

Method Summary
 void addListeningPoint(ListeningPoint listeningPoint)
          This method adds the supplied ListeningPoint to the list of ListeningPoints associated to this SipProvider.
 void addSipListener(SipListener sipListener)
          This method registers the SipListener object to this SipProvider, once registered the SIP Listener recieve events emitted from the SipProvider.
 boolean equals(Object obj)
           
 ListeningPoint getListeningPoint()
          Returns the ListeningPoint of this SipProvider.
 ListeningPoint getListeningPoint(String transport)
          Get the listening point for a given transport.
 ListeningPoint[] getListeningPoints()
          Returns all the ListeningPoints of this SipProvider.
 CallIdHeader getNewCallId()
          Returns a unique CallIdHeader for identifying dialogues between two SIP applications.
 ClientTransaction getNewClientTransaction(Request request)
          Before an application can send a new request it must first request a new client transaction to handle that Request.
 Dialog getNewDialog(Transaction transaction)
          Create a dialog for the given transaction.
 ServerTransaction getNewServerTransaction(Request request)
          An application has the responsibility of deciding to respond to a Request that does not match an existing server transaction.
 SipStack getSipStack()
          Returns the SipStack that created this SipProvider.
 void handleEvent(EventObject sipEvent, SIPTransaction transaction)
          Handle the SIP event - because we have only one listener and we are already in the context of a separate thread, we dont need to enque the event and signal another thread.
 boolean isAutomaticDialogSupportEnabled()
           
 void removeListeningPoint(ListeningPoint listeningPoint)
          Removes the specified ListeningPoint from this SipProvider.
 void removeListeningPoints()
          Remove all the listening points for this sip provider.
 void removeSipListener(SipListener sipListener)
          Removes the specified SipListener from this SipProvider.
 void sendRequest(Request request)
          Sends the Request statelessly, that is no transaction record is associated with this action.
 void sendResponse(Response response)
          Sends the Response statelessly, that is no transaction record is associated with this action.
 void setAutomaticDialogSupportEnabled(boolean automaticDialogSupportEnabled)
          Enable or disable automatic dialog creation for this Provider.
 void setListeningPoint(ListeningPoint listeningPoint)
          This method sets the ListeningPoint of the SipProvider.
 void transactionErrorEvent(SIPTransactionErrorEvent transactionErrorEvent)
          Invoked when an error has ocurred with a transaction.
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getListeningPoint

public ListeningPoint getListeningPoint(String transport)
Description copied from interface: SipProvider
Get the listening point for a given transport. Null is returned if there is no listening point for that transport.

Specified by:
getListeningPoint in interface SipProvider
Parameters:
transport - -- the transport for the listening point

handleEvent

public void handleEvent(EventObject sipEvent,
                        SIPTransaction transaction)
Handle the SIP event - because we have only one listener and we are already in the context of a separate thread, we dont need to enque the event and signal another thread.

Parameters:
sipEvent - is the event to process.

equals

public boolean equals(Object obj)
Overrides:
equals in class Object

addSipListener

public void addSipListener(SipListener sipListener)
                    throws TooManyListenersException
Description copied from interface: SipProvider
This method registers the SipListener object to this SipProvider, once registered the SIP Listener recieve events emitted from the SipProvider. This specification restricts a unicast Listener model, that is only one Listener may be registered on the SipProvider. If an attempt is made to re-register the existing registered SipListener this method returns silently.

Specified by:
addSipListener in interface SipProvider
Parameters:
sipListener - the SipListener to be registered with the SipProvider.
Throws:
TooManyListenersException - when a new SipListener attempts to register with the SipProvider when another SipListener is already registered with this SipProvider.

getListeningPoint

public ListeningPoint getListeningPoint()
Description copied from interface: SipProvider
Returns the ListeningPoint of this SipProvider. A SipProvider has a single Listening Point at any specific point in time.

Specified by:
getListeningPoint in interface SipProvider

getNewCallId

public CallIdHeader getNewCallId()
Description copied from interface: SipProvider
Returns a unique CallIdHeader for identifying dialogues between two SIP applications.

Specified by:
getNewCallId in interface SipProvider
Returns:
the new CallIdHeader unique within the SipProvider.

getNewClientTransaction

public ClientTransaction getNewClientTransaction(Request request)
                                          throws TransactionUnavailableException
Description copied from interface: SipProvider
Before an application can send a new request it must first request a new client transaction to handle that Request. This method is called by the application to create the new client transaction befores it sends the Request on that transaction. This methods returns a new unique client transaction that can be passed to send Requests statefully.Do not call this method for ACK requests.

Specified by:
getNewClientTransaction in interface SipProvider
Parameters:
request - the new Request message that is to handled statefully by the ClientTransaction.
Returns:
a new unique client transaction.
Throws:
TransactionUnavailableException - if a new transaction can not be created, for example the next hop of the request can not be determined or the method is "ACK"
See Also:
ClientTransaction

getNewServerTransaction

public ServerTransaction getNewServerTransaction(Request request)
                                          throws TransactionAlreadyExistsException,
                                                 TransactionUnavailableException
Description copied from interface: SipProvider
An application has the responsibility of deciding to respond to a Request that does not match an existing server transaction. This method is called by an application that decides to respond to an unmatched Request statefully. This methods return a new unique server transaction that can be used to respond to the request statefully. Do ~not~ call this method for ACK requests.

Specified by:
getNewServerTransaction in interface SipProvider
Parameters:
request - the Request message that the doesn't match an existing transaction that the application decides to handle statefully.
Returns:
a new unique server transaction.
Throws:
TransactionAlreadyExistsException - if a transaction already exists that is already handling this Request. This may happen if the application gets retransmits of the same request before the initial transaction is allocated.
TransactionUnavailableException - if a new transaction can not be created, for example the next hop of the request can not be determined or the method is "ACK"
See Also:
ServerTransaction

getSipStack

public SipStack getSipStack()
Description copied from interface: SipProvider
Returns the SipStack that created this SipProvider. A SipProvider can only be attached to a single SipStack object that belongs to the same implementation as this SipProvider.

Specified by:
getSipStack in interface SipProvider
Returns:
the SipStack that created this SipProvider.
See Also:
SipStack

removeSipListener

public void removeSipListener(SipListener sipListener)
Description copied from interface: SipProvider
Removes the specified SipListener from this SipProvider. This method returns silently if the SipListener is not registered with the SipProvider.

Specified by:
removeSipListener in interface SipProvider
Parameters:
sipListener - the SipListener to be removed from this SipProvider.

sendRequest

public void sendRequest(Request request)
                 throws SipException
Description copied from interface: SipProvider
Sends the Request statelessly, that is no transaction record is associated with this action. This method implies that the application is functioning as a stateless proxy, hence the underlying SipProvider acts statelessly. A stateless proxy simply forwards every request it receives downstream and discards information about the Request message once the message has been forwarded. A stateless proxy does not have any notion of a transaction.

Once the Request message has been passed to this method, the SipProvider will forget about this Request. No transaction semantics will be associated with the Request and the SipProvider will not handle retranmissions for the Request. If these semantics are required it is the responsibility of the application not the SipProvider.

Specified by:
sendRequest in interface SipProvider
Parameters:
request - the Request message to send statelessly
Throws:
SipException - if the SipProvider cannot send the Request for any reason.
See Also:
Request

sendResponse

public void sendResponse(Response response)
                  throws SipException
Description copied from interface: SipProvider
Sends the Response statelessly, that is no transaction record is associated with this action. This method implies that the application is functioning as either a stateless proxy or a stateless UAS.

Specified by:
sendResponse in interface SipProvider
Parameters:
response - the Response to send statelessly.
Throws:
SipException - if the SipProvider cannot send the Response for any reason.
See Also:
Response, Response

setListeningPoint

public void setListeningPoint(ListeningPoint listeningPoint)
Description copied from interface: SipProvider
This method sets the ListeningPoint of the SipProvider.

Specified by:
setListeningPoint in interface SipProvider

getNewDialog

public Dialog getNewDialog(Transaction transaction)
                    throws SipException
Description copied from interface: SipProvider
Create a dialog for the given transaction. This method is only called when AUTOMATIC_DIALOG_SUPPORT is off. This method is invoked when the application wants to explicitly manage the association between transaction and dialog. This must may only be called on a dialog-creating transaction. Dialogs are created in advance, before any responses are sent or received, using the initial client or server transaction. The Dialog state is set to null when the dialog is created. The server side of a dialog calls this method before sending out the response to a dialog creating request. The client side of the dialog calls this method before sending out the initial request via the dialog creating transaction. The caller is required to set up the tags and other information in the request/response before calling this method.

For UAC's Forked calls are handled as follows: The response of a forked call that completes the initially created dialog will use the original dialog that is associated with the transaction. Subsequent responses that correspond to other branches of the fork ( ie. with the same From header tag, and Call ID but different To header tags) result in the creation of additional dialogs that are associated with these responses. The created dialog is made available to the UAC ( Listener ) via the method ResponseEvent.getDialog

Transactions that belong to the Dialog are automatically associated with the Dialog by the stack and can be retrieved with Transaction.getDialog().

Specified by:
getNewDialog in interface SipProvider
Parameters:
transaction - - transaction that is used to extract the relevant information to create the dialog.
Throws:
SipException - if one or more of the following is true:
  1. The Method of the Request is not a Dialog creating
  2. There is missing required information such as From header Tag in the Request
  3. This method is called after the response recieved on the client side
  4. This method is called after the response is sent out on the server side of the dialog.

transactionErrorEvent

public void transactionErrorEvent(SIPTransactionErrorEvent transactionErrorEvent)
Invoked when an error has ocurred with a transaction. Propagate up to the listeners.

Specified by:
transactionErrorEvent in interface SIPTransactionEventListener
Parameters:
transactionErrorEvent - Error event.

getListeningPoints

public ListeningPoint[] getListeningPoints()
Description copied from interface: SipProvider
Returns all the ListeningPoints of this SipProvider. A SipProvider may have a Listening Point for each specific transport type at any specific point in time. A SipProvider must use the same transport for sending responses that was used for sending the outbound request.

Specified by:
getListeningPoints in interface SipProvider
Returns:
an array of ListeningPoints associated to this SipProvider.

addListeningPoint

public void addListeningPoint(ListeningPoint listeningPoint)
                       throws ObjectInUseException
Description copied from interface: SipProvider
This method adds the supplied ListeningPoint to the list of ListeningPoints associated to this SipProvider. A SipProvider can only have a single ListeningPoint for each transport type at any specific time. Multiple SipProviders are prohibited to listen on the same ListeningPoints. This method returns silently if the same ListeningPoint argument is re-set on the SipProvider. If there is a ListeningPoint with the same transport but different IP or port, the implementation is expected to throw an exception.

Specified by:
addListeningPoint in interface SipProvider
Parameters:
listeningPoint - - the listening point to add to this ListeningPoint
Throws:
ObjectInUseException - if the supplied ListeningPoint is being used by another SipProvider or if there is already a ListeningPoint for the given transport.

removeListeningPoint

public void removeListeningPoint(ListeningPoint listeningPoint)
                          throws ObjectInUseException
Description copied from interface: SipProvider
Removes the specified ListeningPoint from this SipProvider. This method returns silently if the ListeningPoint is not associated to this SipProvider. A SipProvider must have at least a single ListeningPoint at all times. When the ListeningPoint is removed the SipProvider no further requests will be sent out over this ListeningPoint.

Specified by:
removeListeningPoint in interface SipProvider
Parameters:
listeningPoint - the ListenPoint to be removed from this SipProvider.
Throws:
ObjectInUseException - if the ListeningPoint is already in use or is the last ListeningPoint associated with this SipProvider.

removeListeningPoints

public void removeListeningPoints()
Remove all the listening points for this sip provider. This is called when the stack removes the Provider


setAutomaticDialogSupportEnabled

public void setAutomaticDialogSupportEnabled(boolean automaticDialogSupportEnabled)
Description copied from interface: SipProvider
Enable or disable automatic dialog creation for this Provider. By default, each provider inherits the automatic dialog support property from the stack(i.e. the value implied by the stack configuration property javax.sip.AUTOMATIC_DIALOG_SUPPORT) . This method allows for selective overriding of the stack-wide property on a per provider basis. This is useful for applications that need to support both user agent and proxy functionality in a single stack such as IMS applications and 3rd party call control. Provider instances that need to proxy requests while functioning transaction statefully should turn this property off. Provider instances that need to at as user agents can turn this support on and get the benifit of automatic dialog creation. If this support is enabled, then Dialog creating Transactions (i.e. INVITE) that are associated with this Provider automatically create a Dialog when the Transaction is created. If this support is disabled, then Transactions associated with this Provider do not result in the automatic creation of an associated Dialog at the time of Transaction creation.

Specified by:
setAutomaticDialogSupportEnabled in interface SipProvider
Parameters:
automaticDialogSupportEnabled - - enables or disables automatic dialog support for this provider.
See Also:
SipStack

isAutomaticDialogSupportEnabled

public boolean isAutomaticDialogSupportEnabled()
Returns:
Returns the automaticDialogSupportEnabled.

NIST-SIP: The Reference Implementation for JAIN-SIP 1.2

A product of the NIST/ITL Advanced Networking Technologies Division.
See conditions of use.
Submit a bug report or feature request.