net.java.slee.resource.sip

Interface SleeSipProvider

All Superinterfaces:

SipProvider

public interface SleeSipProvider
extends SipProvider

This interface is the SBB resource adaptor interface for the JSIP 1.2 RA Type. An SBB can bind an object of this type into its JNDI component environment using a resource-adaptor-entity-binding element in the SBB's deployment descriptor.

This interface extends SipProvider, with additional methods for SLEE applications.

Method Summary

Modifier and Type	Method and Description
boolean	acceptCancel(CancelRequestEvent cancelEvent, boolean isProxy) Convenience method for simplifying CANCEL handling.
DialogActivity	forwardForkedResponse(ServerTransaction origServerTransaction, Response response) This method is used when forwarding a forked response, that was received in a DialogForkedEvent.
AddressFactory	getAddressFactory() Convenience method to get the RA implementation's AddressFactory object.
HeaderFactory	getHeaderFactory() Convenience method to get the RA implementation's HeaderFactory object.
SipURI	getLocalSipURI(String transport) Convenience method for obtaining a SIP URI addressed to this SIP RA Entity.
ViaHeader	getLocalVia(String transport, String branch) Convenience method for obtaining a ViaHeader addressed to this SIP RA Entity.
MessageFactory	getMessageFactory() Convenience method to get the RA implementation's MessageFactory object.
DialogActivity	getNewDialog(Address from, Address to) Creates a new client dialog using the given local and remote party addresses.
DialogActivity	getNewDialog(DialogActivity incomingDialog, boolean useSameCallId) Creates a new client dialog based on the parameters of an incoming server dialog, on which a dialog-initiating request has been received.
boolean	isLocalHostname(String host) Convenience method for determining if a hostname matches the host that the SIP RA Entity is running on.
boolean	isLocalSipURI(SipURI uri) Convenience method for determining if a SipURI matches a local address that the SIP RA Entity is using.

Methods inherited from interface javax.sip.SipProvider

addListeningPoint, addSipListener, getListeningPoint, getListeningPoint, getListeningPoints, getNewCallId, getNewClientTransaction, getNewDialog, getNewServerTransaction, getSipStack, removeListeningPoint, removeSipListener, sendRequest, sendResponse, setAutomaticDialogSupportEnabled, setListeningPoint

Method Detail

getAddressFactory

AddressFactory getAddressFactory()

Convenience method to get the RA implementation's AddressFactory object.

Returns:

a AddressFactory object.

getHeaderFactory

HeaderFactory getHeaderFactory()

Convenience method to get the RA implementation's HeaderFactory object.

Returns:

a HeaderFactory object.

getMessageFactory

MessageFactory getMessageFactory()

Convenience method to get the RA implementation's MessageFactory object.

Returns:

a MessageFactory object.

getNewDialog

DialogActivity getNewDialog(Address from,
                            Address to)
                     throws SipException

Creates a new client dialog using the given local and remote party addresses. The RA Entity will generate the Call-ID, local tag and Contact address. After creating the new dialog, the application can then create and send the initial request using Dialog.createRequest(String) and DialogActivity.sendRequest(javax.sip.message.Request). This is a convenience method for client (UAC) applications, so that they can easily create new dialogs.

Parameters:

from - the local party address for the new dialog.

to - the remote party address for the new dialog.

Returns:

a new DialogActivity.

Throws:

SipException - if unable to create the dialog.

getNewDialog

DialogActivity getNewDialog(DialogActivity incomingDialog,
                            boolean useSameCallId)
                     throws SipException

Creates a new client dialog based on the parameters of an incoming server dialog, on which a dialog-initiating request has been received. The new dialog will optionally have the same Call-ID as the original dialog, but will always have a new local tag, generated by the RA Entity, so that the dialog ID is unique.

The local and remote address paraameters are copied from the original dialog. The RA will generate a local Contact address to be used in outgoing requests.

This method provides a simple way to create the outgoing leg of a B2BUA application. An application using this method should then call DialogActivity.createRequest(javax.sip.message.Request) and DialogActivity.sendRequest(javax.sip.message.Request) to copy the dialog-initiating request and forward it out on the new dialog.

Parameters:

incomingDialog - the original server dialog, on which a dialog-initiating request has been received.

useSameCallId - if true, the new dialog will have the same Call-ID as the original dialog. Otherwise a new Call-ID will be generated by the RA Entity.

Returns:

a new DialogActivity.

Throws:

SipException - if unable to create the new dialog.

isLocalSipURI

boolean isLocalSipURI(SipURI uri)

Convenience method for determining if a SipURI matches a local address that the SIP RA Entity is using. For example, a Proxy SBB could use this to check incoming Route headers.

Parameters:

uri - a SIP URI.

Returns:

true if the hostname, port and transport in the SIP URI match a local listening point of the SIP RA, otherwise false.

isLocalHostname

boolean isLocalHostname(String host)

Convenience method for determining if a hostname matches the host that the SIP RA Entity is running on.

Parameters:

host - a hostname, or IP address in string form.

Returns:

true if the hostname is a valid hostname for this host, otherwise false.

getLocalSipURI

SipURI getLocalSipURI(String transport)

Convenience method for obtaining a SIP URI addressed to this SIP RA Entity. For example, a Proxy SBB could use this when inserting a Record-Route header.

Parameters:

transport - a case-insensitive transport name, such as "udp", "tcp" or "tls". This will be used as the transport parameter in the resulting SipURI, unless transport is "tls", in which case the RA Entity shall return a secure sips: URI. If transport is null, no transport parameter will be used in the URI.

Returns:

a SipURI addressed to this SIP RA Entity.

getLocalVia

ViaHeader getLocalVia(String transport,
                      String branch)
               throws TransportNotSupportedException

Convenience method for obtaining a ViaHeader addressed to this SIP RA Entity. For example, a Proxy SBB could use this when adding a Via header to a forwarded request.

Parameters:

transport - a case-insensitive transport name, such as "udp", "tcp" or "tls". This will be used as the transport parameter in the resulting ViaHeader.

branch - the branch parameter to use in the new header. If null, the RA will automatically generate a valid branch parameter.

Returns:

a ViaHeader addressed to this SIP RA Entity.

Throws:

TransportNotSupportedException - if the given transport is not supported by the SIP RA entity

forwardForkedResponse

DialogActivity forwardForkedResponse(ServerTransaction origServerTransaction,
                                     Response response)
                              throws SipException

This method is used when forwarding a forked response, that was received in a DialogForkedEvent. A transparent B2BUA application must use this method to forward forked responses upstream. This method sends the response on the supplied ServerTransaction, and creates a new DialogActivity that the SBB should attach to, to receive mid-dialog requests on the new dialog.

Sending a forked response upstream using ServerTransaction.sendResponse(javax.sip.message.Response) will not work correctly, because if the caller sends any mid-dialog requests on the new dialog, the RA Entity will not match them with a dialog activity, and will not fire these request events on the dialog.

If the response is a final response, all other early dialogs will be terminated.

Parameters:

origServerTransaction - the ServerTransaction to send the response on. This would usually be obtained using DialogActivity.getAssociatedServerTransaction(javax.sip.ClientTransaction) when processing the DialogForkedEvent.

response - the Response that was received in a DialogForkedEvent. The implementation of this method must make a copy of this response, and modify it so that it is suitable to send on the server transaction, i.e. Via, CSeq, From and To headers will match the upstream call leg, as per DialogActivity.createResponse(javax.sip.ServerTransaction, javax.sip.message.Response). This modified response will be forwarded upstream on the server transaction. The original response is not modified.

Returns:

the new DialogActivity resulting from this forked response. Applications should attach to the activity to receive any mid-dialog requests.

Throws:

SipException - if unable to create the forked dialog, or send the response.

acceptCancel

boolean acceptCancel(CancelRequestEvent cancelEvent,
                     boolean isProxy)

Convenience method for simplifying CANCEL handling. When a CANCEL arrives, an application can ask the the RA to handle it, by calling this method.

The behaviour of this method depends on whether the CANCEL actually matched an INVITE, and also whether the application is behaving as a proxy or not (determined by the isProxy parameter. This is summarized in the table below.

	isProxy = false	isProxy = true
CANCEL matches INVITE	Send “200 OK” response to CANCEL. Send “487 Request Terminated” response to INVITE.	Send “200 OK” response to CANCEL. Proxy application must cancel outstanding branches and wait for responses (RFC3261 §16.10).
CANCEL does not match INVITE	Send “481 Call or Transaction Does Not Exist” response to CANCEL.	Do nothing. Proxy application must statelessly forward the CANCEL downstream (RFC3261 §16.10).

Applications can choose to implement their own CANCEL handling, this method is provided to simplify the common case where a CANCEL is just accepted immediately.

Parameters:

cancelEvent - the CancelRequestEvent containing the CANCEL request and its ServerTransaction, and the matching INVITE ServerTransaction, if any.

isProxy - if true, the RA will follow standard proxy behaviour as described in the table above.

Returns:

true if the CANCEL did match an INVITE, otherwise false.