javax.servlet.sip

Interface B2buaHelper

public interface B2buaHelper

Helper class providing support for B2BUA applications. An instance of this class can be retrieved from a SipServletRequest by invoking the method SipServletRequest.getB2buaHelper().

Since:

1.1

Method Summary

Methods

Modifier and Type	Method and Description
SipServletRequest	createCancel(SipSession session) Creates a new CANCEL request to cancel the initial request sent on the other leg.
SipServletRequest	createRequest(SipServletRequest origRequest) Creates a new request object belonging to a new SipSession.
SipServletRequest	createRequest(SipServletRequest origRequest, boolean linked, Map<String,List<String>> headerMap) Creates a new request object belonging to a new SipSession.
SipServletRequest	createRequest(SipSession session, SipServletRequest origRequest, Map<String,List<String>> headerMap) Creates a new subsequent request based on the specified original request.
SipServletResponse	createResponseToOriginalRequest(SipSession session, int status, String reasonPhrase) The request that results in creation of a SipSession is termed as the original request, a response to this original request can be created by the application even if the request was committed and application does not have a reference to this Request.
SipSession	getLinkedSession(SipSession session) Returns the other SipSession that is linked to the specified SipSession, or null if none.
SipServletRequest	getLinkedSipServletRequest(SipServletRequest req) If a new request is created based on an existing one with the link argument true using or using the new request gets implicitly linked with the original request.
List<SipServletMessage>	getPendingMessages(SipSession session, UAMode mode) For the specified SipSession, returns a List of all uncommitted messages in the order of increasing CSeq number for the given mode of the session.
void	linkSipSessions(SipSession session1, SipSession session2) Links the specified sessions, such that there is a 1-1 mapping between them.
void	unlinkSipSessions(SipSession session) If the specified SipSession is linked to another session, then unlinks the two sessions from each other.

Method Detail

createCancel

SipServletRequest createCancel(SipSession session)

Creates a new CANCEL request to cancel the initial request sent on the other leg. The CANCEL is created by the container using the initial request stored in the session corresponding to the other leg.

Parameters:

session - the session whose initial request is to be cancelled.

Returns:

the new CANCEL request to be sent on the other leg

Throws:

NullPointerException - if the session is null

createRequest

SipServletRequest createRequest(SipServletRequest origRequest)

Creates a new request object belonging to a new SipSession. The new request is similar to the specified origRequest in that the method and the majority of header fields are copied from origRequest to the new request. The SipSession created for the new request also shares the same SipApplicationSession associated with the original request. This method satisfies the following rules: * The From header field of the new request has a new tag chosen by the container. * The To header field of the new request has no tag. * The new request (and the corresponding SipSession)is assigned a new Call-ID. * Record-Route and Via header fields are not copied. As usual, the container will add its own Via header field to the request when it's actually sent outside the application server. * For non-REGISTER requests, the Contact header field is not copied but is populated by the container as usual. This method provides a convenient and efficient way of constructing a new "leg" of a B2BUA application. It is used only for the initial request. Subsequent requests in either leg must be created using SipSession.createRequest(java.lang.String) or createRequest(SipSession, SipServletRequest, java.util.Map) as usual.

Parameters:

origRequest - request to be "copied"

Returns:

the "copied" request object

createRequest

SipServletRequest createRequest(SipServletRequest origRequest,
                              boolean linked,
                              Map<String,List<String>> headerMap)
                                throws IllegalArgumentException,
                                       TooManyHopsException

Creates a new request object belonging to a new SipSession. The new request is similar to the specified origRequest in that the method and the majority of header fields are copied from origRequest to the new request. The headerMap parameter can contain From, To, Contact, Route headers and any non system header. The header field map is then used to override the headers in the newly created request. The SipSession created for the new request also shares the same SipApplicationSession associated with the original request. This method satisfies the following rules: Whether the From header is overridden through the headerMap or not the From header field of the new request has a new tag chosen by the container. If the From header is included in the headerMap and has a tag then it is ignored and container chosen tag is inserted instead. The To header field of the new request has no tag. Record-Route and Via header fields are not copied. As usual, the container will add its own Via header field to the request when it's actually sent outside the application server. For non-REGISTER requests, the Contact header field is not copied but is populated by the container as usual but if Contact header is present in the headerMap then relevant portions of Contact header is to be used in the request created, in accordance with section 4.1.3 of the specification. This method provides a convenient and efficient way of constructing the second "leg" of a B2BUA application, giving the additional flexibility of changing the headers including To, From, Contact, Route. This method will also perform loop detection. If the value of the original request's Max-Forwards header field is 0, then TooManyHopsException is thrown and a 483 (Too many hops) response is sent for the original request. Otherwise, the value of the new requests Max-Forwards header is set to that of the original request minus one. It is used only for the initial request. Subsequent requests in either leg must be created using SipSession.createRequest(java.lang.String) or createRequest(SipSession, SipServletRequest, java.util.Map) as usual.

Throws:

IllegalArgumentException

TooManyHopsException

createRequest

SipServletRequest createRequest(SipSession session,
                              SipServletRequest origRequest,
                              Map<String,List<String>> headerMap)
                                throws IllegalArgumentException

Creates a new subsequent request based on the specified original request. This results in automatically linking the two SipSessions (if they are not already linked) and the two SipServletRequests. This method, though similar to the factory method of creating the request for a B2BUA for initial requests, is to be used for subsequent requests. The semantics are similar to SipSession.createRequest(String) except that here it copies non system headers from the original request onto the new request, the system headers are created based on the session that this request is created on. Further the Route headers are set as based on the session route set. The method of the new request is same as that of the origRequest. IIf Contact header is present in the headerMap then relevant portions of the Contact header are to be used in the request created, in accordance with section 4.1.3 of the specification. If From and To headers are present in the headerMap then all parts of those headers except the tag parameter are to be used in the request created, in accordance with section 4.1.2 of the specification.

Throws:

IllegalArgumentException - if the header map contains a system header other than Contact (see section 4.1.3 of specification document) or other header which does not makes sense in the context, or in case when the session does not belong to the same SipApplicationSession as the origRequest, or the original request or session is already linked with some other request/session, or if the origRequest is not initial

IllegalArgumentException - if the header map contains a system header other than Contact, From or To (see sections 4.1.2 and 4.1.3 of specification document) or other header which does not makes sense in the context, or in case when the session does not belong to the same SipApplicationSession as the origRequest, or the original request or session is already linked with some other request/session, or if the origRequest is not initial

NullPointerException - - if the original request or the session is null

createResponseToOriginalRequest

SipServletResponse createResponseToOriginalRequest(SipSession session,
                                                 int status,
                                                 String reasonPhrase)

The request that results in creation of a SipSession is termed as the original request, a response to this original request can be created by the application even if the request was committed and application does not have a reference to this Request. This is required because the B2BUA application may require to send more than one successful response to a request. For example when a downstream proxy forked and more than one success responses are to be forwarded upstream. This can only be required on initial requests, as only original requests shall need such multiple responses. The response thus generated must have a different “To�? tag from the other responses generated to the Request and must result in a different SipSession. In this (and similar) cases the container clones the original SipSession for the second and subsequentdialogs, as detailed above. The cloned session object will contain the same application data but its createRequest method will create requests belonging to that second or subsequent dialog, that is, with a “To�? tag specific to that dialog.

getLinkedSession

SipSession getLinkedSession(SipSession session)

Returns the other SipSession that is linked to the specified SipSession, or null if none. The sessions get linked by either explicit call to or

getLinkedSipServletRequest

SipServletRequest getLinkedSipServletRequest(SipServletRequest req)

If a new request is created based on an existing one with the link argument true using or using the new request gets implicitly linked with the original request. This method is to be used to retrieve the linked request. There is no explicit linking/unlinking like that of the session for requests. However unlinking of sessions also result in unlinking of linked requests.

getPendingMessages

List<SipServletMessage> getPendingMessages(SipSession session,
                                         UAMode mode)

For the specified SipSession, returns a List of all uncommitted messages in the order of increasing CSeq number for the given mode of the session.

linkSipSessions

void linkSipSessions(SipSession session1,
                   SipSession session2)

Links the specified sessions, such that there is a 1-1 mapping between them. Each session can retrieved from the other by calling . One SipSession at any given time can be linked to only one other SipSession belonging to the same SipApplicationSession. Calling linkSessions() with already linked sessions to each other is a no-op and is to be silently ignored, while calling linkSessions() with any of the session linked with sessions result in java.lang.IllegalArgumentException

unlinkSipSessions

void unlinkSipSessions(SipSession session)

If the specified SipSession is linked to another session, then unlinks the two sessions from each other. This also implicitly unlinks the linkage at the request level.