gov.nist.javax.sip

Class SipProviderImpl

java.lang.Object

gov.nist.javax.sip.SipProviderImpl

All Implemented Interfaces:

SipProviderExt, SIPDialogEventListener, SIPTransactionEventListener, EventListener, SipProvider

public class SipProviderImpl
extends Object
implements SipProvider, SipProviderExt, SIPTransactionEventListener, SIPDialogEventListener

Implementation of the JAIN-SIP provider interface.

Version:

1.2 $Revision: 1.89 $ $Date: 2010-12-02 22:04:19 $

Author:

M. Ranganathan

Field Summary

Fields

Modifier and Type	Field and Description
protected EventScanner	eventScanner
protected SipStackImpl	sipStack

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SipProviderImpl(SipStackImpl sipStack) Creates a new instance of SipProviderImpl

Method Summary

Methods

Modifier and Type	Method and Description
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.
protected Object	clone()
protected SIPClientTransaction	createClientTransaction(Request request, Hop hop)
void	dialogErrorEvent(SIPDialogErrorEvent dialogErrorEvent) Invoked when an error has ocurred with a dialog.
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.
SipListener	getSipListener()
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()
boolean	isDialogErrorsAutomaticallyHandled()
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	setDialogErrorsAutomaticallyHandled() Sets a flag that indicates that automatic error handling is enabled for this dialog (the default when automatic dialog support is enabled).
void	setListeningPoint(ListeningPoint listeningPoint) This method sets the ListeningPoint of the SipProvider.
protected void	stop() Stop processing messages for this provider.
void	transactionErrorEvent(SIPTransactionErrorEvent transactionErrorEvent) Invoked when an error has ocurred with a transaction.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

sipStack

protected SipStackImpl sipStack

eventScanner

protected EventScanner eventScanner

Constructor Detail

SipProviderImpl

protected SipProviderImpl(SipStackImpl sipStack)

Creates a new instance of SipProviderImpl

Method Detail

stop

protected void stop()

Stop processing messages for this provider. Post an empty message to our message processing queue that signals us to quit.

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.

clone

protected Object clone()
                throws CloneNotSupportedException

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

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.

createClientTransaction

protected SIPClientTransaction createClientTransaction(Request request,
                                           Hop hop)
                                                throws TransactionUnavailableException

Parameters:

request -

hop -

Returns:

Throws:

TransactionUnavailableException

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.

• 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 UAS - 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 UAS's 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 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.

dialogErrorEvent

public void dialogErrorEvent(SIPDialogErrorEvent dialogErrorEvent)

Description copied from interface: SIPDialogEventListener

Invoked when an error has ocurred with a dialog.

Specified by:

dialogErrorEvent in interface SIPDialogEventListener

Parameters:

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

setDialogErrorsAutomaticallyHandled

public void setDialogErrorsAutomaticallyHandled()

Description copied from interface: SipProviderExt

Sets a flag that indicates that automatic error handling is enabled for this dialog (the default when automatic dialog support is enabled). This flag is set by default to TRUE when the Dialog is automatically created by the provider ( automatic dialog support is true) and set to FALSE by default when the Dialog is created under program control ( automatic dialog support is false). When this flag is set to true, the stack will automatically send the following errors :

• 500 Request Out of Order for in-dialog requests that arrive out of order.
• 482 Loop Detected When a loop is detected for merged INVITE requests.
• 400 Bad request when a REFER is sent without a matching refer-to dialog.

If this flag is set to false, the stack will not drop out of sequence ACKs but will pass these up to the application for handling. This flag is automatically set to true if any of the the following conditions is true:

• The Back To Back User Agent flag is enabled for the Dialog.
• The Automatic Dialog Support flag is enabled for the Dialog

This flag should only be set at the time of Dialog creation ( before the Dialog has seen its first request or response). If set subsequently, the behavior of the flag is undefined.

Specified by:

setDialogErrorsAutomaticallyHandled in interface SipProviderExt

isDialogErrorsAutomaticallyHandled

public boolean isDialogErrorsAutomaticallyHandled()

getSipListener

public SipListener getSipListener()

Returns:

the sipListener