NIST SIP Parser and Stack (v1.2) API

gov.nist.javax.sip
Class SipProviderImpl

java.lang.Object
  |
  +--gov.nist.javax.sip.SipProviderImpl
All Implemented Interfaces:
EventListener, SipProvider, SIPTransactionEventListener

public final class SipProviderImpl
extends Object
implements SipProvider, SIPTransactionEventListener

Implementation of the JAIN-SIP provider interface.

Version:
JAIN-SIP-1.1
Author:
M. Ranganathan
This code is in the public domain.

Constructor Summary
SipProviderImpl()
          Creates a new instance of SipProviderImpl
 
Method Summary
 void addSipListener(SipListener sipListener)
          This method registers the SipListener object to this SipProvider, once registered the SIP Listener can send events on the SipProvider and recieve events emitted from the SipProvider.
 boolean equals(Object obj)
           
 ListeningPoint getListeningPoint()
          Returns the ListeningPoint of this SipProvider.
 CallIdHeader getNewCallId()
          Returns a unique CallIdHeader for identifying dialogues between two SIP applications.
 ClientTransaction getNewClientTransaction(Request request)
          Once an application wants to a send a new request it must first request a new client transaction identifier.
 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 this SipProvider is attached to.
 void handleEvent(EventObject sipEvent)
          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.
 void removeSipListener(SipListener sipListener)
          Removes the SipListener from this SipProvider.
 void sendRequest(ClientTransaction clientTransaction, Request request)
          Sends specified Request on a unique client transaction identifier.
 void sendResponse(ServerTransaction serverTransaction, Response response)
          Sends specified Response message to a Request which is identified by the specified server transaction identifier.
 void sendStatelessRequest(Request request)
          Sends specified Request and returns void i.e.
 void sendStatelessResponse(Response response)
          Sends specified Response and returns void i.e.
 void setListeningPoint(ListeningPoint listeningPoint)
          This method sets the listening point 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
 

Constructor Detail

SipProviderImpl

public SipProviderImpl()
Creates a new instance of SipProviderImpl

Method Detail

handleEvent

public void handleEvent(EventObject sipEvent)
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
This method registers the SipListener object to this SipProvider, once registered the SIP Listener can send events on the SipProvider and recieve events emitted from the SipProvider. As JAIN SIP resticts a unicast Listener special case, that is, that one and only one Listener may be registered on the SipProvider concurrently.

If an attempt is made to re-register the existing SipListener this method returns silently. A previous SipListener must be removed from the SipProvider before another SipListener can be registered to the SipProvider.

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

getListeningPoint

public ListeningPoint getListeningPoint()
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
Returns:
the ListeningPoint of this SipProvider
See Also:
ListeningPoint

getNewCallId

public CallIdHeader getNewCallId()
Returns a unique CallIdHeader for identifying dialogues between two SIP applications.

Specified by:
getNewCallId in interface SipProvider
Returns:
new CallId unique within the SIP Stack.

getNewClientTransaction

public ClientTransaction getNewClientTransaction(Request request)
                                          throws TransactionUnavailableException
Once an application wants to a send a new request it must first request a new client transaction identifier. This method is called by an application to create the client transaction befores it sends the Request via the SipProvider on that transaction. This methods returns a new unique client transaction identifier that can be passed to the stateful sendRequest method on the SipProvider and the sendAck/sendBye methods on the Dialog in order to send a request.

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

getNewServerTransaction

public ServerTransaction getNewServerTransaction(Request request)
                                          throws TransactionAlreadyExistsException,
                                                 TransactionUnavailableException
An application has the responsibility of deciding to respond to a Request that does not match an existing server transaction. The method is called by an application that decides to respond to an unmatched Request statefully. This methods return a new unique server transaction identifier that can be passed to the stateful sendResponse methods in order to respond to the request.

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 transation identifier
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.
Since:
v1.1
See Also:
ServerTransaction

getSipStack

public SipStack getSipStack()
Returns the SipStack that this SipProvider is attached to. A SipProvider can only be attached to a single SipStack object which belongs to the same SIP stack as the SipProvider.

Specified by:
getSipStack in interface SipProvider
Returns:
the attached SipStack.
See Also:
SipStack

removeSipListener

public void removeSipListener(SipListener sipListener)
Removes the SipListener from this SipProvider. This method returns silently if the sipListener argument is not registered with the SipProvider.

Specified by:
removeSipListener in interface SipProvider

sendRequest

public void sendRequest(ClientTransaction clientTransaction,
                        Request request)
                 throws SipException
Sends specified Request on a unique client transaction identifier. This method implies that the application is functioning as either a User Agent Client or a Stateful proxy, hence the underlying SipProvider acts statefully.

JAIN SIP defines a retransmission utility specific to user agent behaviour and the default retransmission behaviour for each method.

When an application wishes to send a message, it creates a Request message passes that Request to this method, this method returns the cleintTransactionId generated by the SipProvider. The Request message gets sent via the ListeningPoint that this SipProvider is attached to.

Specified by:
sendRequest in interface SipProvider
Parameters:
clientTransaction - - the new ClientTransaction object identifying this transaction.
request - - the new Request message to send.
Throws:
SipException - if implementation cannot send request for any reason
See Also:
Request, ClientTransaction

sendResponse

public void sendResponse(ServerTransaction serverTransaction,
                         Response response)
                  throws TransactionDoesNotExistException,
                         SipException
Sends specified Response message to a Request which is identified by the specified server transaction identifier. The semantics for various application behaviour on sending Responses to Requests is outlined at SipListener.processRequest(RequestEvent).

Note that when a UAS core sends a 2xx response to an INVITE, the server transaction is destroyed, by the underlying JAIN SIP implementation. This means that when the ACK sent by the corresponding UAC arrives at the UAS, there will be no matching server transaction for the ACK, and based on this rule, the ACK is passed to the UAS application core, where it is processed. This ensures that the three way handsake of an INVITE that is managed by the UAS application and not JAIN SIP.

Specified by:
sendResponse in interface SipProvider
Parameters:
response - - the Response to send to the Request
serverTransaction - the ServerTransaction of the Request upon which this Response is sent.
Throws:
TransactionDoesNotExistException - if the serverTransactionId does not correspond to any existing server transactions
SipException - if implementation cannot send response for any other reason
See Also:
Response, ServerTransaction

sendStatelessRequest

public void sendStatelessRequest(Request request)
                          throws SipException
Sends specified Request and returns void i.e. no transaction record is associated with this action. This method implies that the application is functioning statelessly specific to this Request, hence the underlying SipProvider acts statelessly.

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 no retranmissions will occur on the Request by the SipProvider, if these semantics are required it is the responsibility of the application not the JAIN SIP Stack.

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

sendStatelessResponse

public void sendStatelessResponse(Response response)
                           throws SipException
Sends specified Response and returns void i.e. no transaction record is associated with this action. This method implies that the application is functioning as either a stateless proxy or a stateless User Agent Server.

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

setListeningPoint

public void setListeningPoint(ListeningPoint listeningPoint)
This method sets the listening point of the SipProvider. A SipProvider can only have a single listening point at any specific time. This method returns silently if the same listeningPoint argument is re-set on the SipProvider.

JAIN SIP supports recieving messages from any port and interface that a server listens on for UDP, on that same port and interface for TCP in case a message may need to be sent using TCP, rather than UDP, if it is too large. In order to satisfy this functionality an application must create two SipProviders and set identical listeningPoints except for transport on each SipProvder.

Multiple SipProviders are prohibited to listen on the same listening point.

Specified by:
setListeningPoint in interface SipProvider
Parameters:
listeningPoint - the ListeningPoint of this SipProvider.
Since:
v1.1
See Also:
ListeningPoint

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.

NIST SIP Parser and Stack (v1.2) API

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