gov.nist.javax.sip
Class SipProviderImpl

java.lang.Object
  gov.nist.javax.sip.SipProviderImpl

All Implemented Interfaces:

EventListener, Runnable, SipProvider, SIPTransactionEventListener

public final class SipProviderImpl

extends Object

implements Runnable, SipProvider, SIPTransactionEventListener

Implementation of the JAIN-SIP provider interface.

Version:

JAIN-SIP-1.1

Author:

M. Ranganathan
This code is in the public domain.

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, 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.
void	removeSipListener(SipListener sipListener) Removes the SipListener from this SipProvider.
void	run()
void	sendRequest(Request request) Sends specified Request and returns void i.e.
void	sendResponse(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

Method Detail

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)

run

public void run()

Specified by:

run in interface Runnable

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 ClientTransaction.

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(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.

• Stateless Proxy - 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.

Specified by:

sendRequest 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

sendResponse

public void sendResponse(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.

• Stateless proxy - A stateless proxy simply forwards every response it receives upstream and discards information about the response message once the message has been forwarded. A stateless proxy does not have any notion of a transaction.
• Stateless User Agent Server - A stateless UAS does not maintain transaction state. It replies to requests normally, but discards any state that would ordinarily be retained by a UAS after a response has been sent. If a stateless UAS receives a retransmission of a request, it regenerates the response and resends it, just as if it were replying to the first instance of the request. A UAS cannot be stateless unless the request processing for that method would always result in the same response if the requests are identical. Stateless UASs do not use a transaction layer; they receive requests directly from the transport layer and send responses directly to the transport layer.

Specified by:

sendResponse 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.