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

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, java.util.Map<java.lang.String,java.util.List<java.lang.String>> headerMap) Creates a new request object belonging to a new SipSession.
SipServletRequest	createRequest(SipSession session, SipServletRequest origRequest, java.util.Map<java.lang.String,java.util.List<java.lang.String>> headerMap) Creates a new subsequent request based on the specified original request.
SipServletResponse	createResponseToOriginalRequest(SipSession session, int status, java.lang.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 createRequest(SipServletRequest, boolean, java.util.Map) or using createRequest(SipSession, SipServletRequest, java.util.Map) the new request gets implicitly linked with the original request.
java.util.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

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 linkSipSessions(SipSession, SipSession) or createRequest(SipServletRequest, boolean, java.util.Map)

Parameters:

session - the SipSession from which to obtain the linked session

Returns:

the linked SipSession, or null if none

Throws:

java.lang.IllegalArgumentException - if the session is invalid

getLinkedSipServletRequest

SipServletRequest getLinkedSipServletRequest(SipServletRequest req)

If a new request is created based on an existing one with the link argument true using createRequest(SipServletRequest, boolean, java.util.Map) or using createRequest(SipSession, SipServletRequest, java.util.Map) 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.

Parameters:

req - other request

Returns:

the linked request

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 getLinkedSession(javax.servlet.sip.SipSession). 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 other sessions result in java.lang.IllegalArgumentException

Parameters:

session1 - the first SipSession to link

session2 - the other SipSession to link

Throws:

java.lang.IllegalArgumentException - if either of the specified sessions has been terminated or the sessions do not belong to the same application session or one or both the sessions are already linked with some other session(s)

java.lang.NullPointerException - if any of the arguments is null

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.

Parameters:

session - the session to be unlinked

Throws:

java.lang.IllegalArgumentException - if the session is not currently linked to another session or it has been terminated

getPendingMessages

java.util.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.

Parameters:

session - the SipSession to check for pending messages

mode - the mode for which the pending messages are required, one of UAC or UAS

Returns:

the list of SipServletMessage objects representing pending messages for the session, or the empty list if none

Throws:

java.lang.IllegalArgumentException - if the session is invalid

createResponseToOriginalRequest

SipServletResponse createResponseToOriginalRequest(SipSession session,
                                                   int status,
                                                   java.lang.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.

Parameters:

session - the SipSession for the original request

status - the status code for the response

reasonPhrase - the reason phrase for the response, or null to use a default reason phrase

Returns:

the resulting SipServletResponse

Throws:

java.lang.IllegalStateException - if a subsequent response is inconsistent with an already sent response. For example, a 400 response following a 200 OK response.

java.lang.IllegalArgumentException - if the session is invalid

createRequest

SipServletRequest createRequest(SipServletRequest origRequest,
                                boolean linked,
                                java.util.Map<java.lang.String,java.util.List<java.lang.String>> headerMap)
                                throws java.lang.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 From, To, Contact and 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.

Parameters:

origRequest - request to be "copied"

linked - indicating if the resulting session should be linked with original or not

headerMap - a simple map containing header names and their values to be overridden in the new request. The values can be a specified in a java.util.List to accomodate for multi-valued headers

Returns:

the "copied" request object

Throws:

java.lang.IllegalArgumentException - if the headerMap contains a system header other than From, To, Contact and Route (see section 4.1.3 to see what part of Contact header is to be used) or some other header not relevant for the context, or the origRequest and its session is linked to some other request/session and the linked flag is true, or if the origRequest is not initial

java.lang.NullPointerException - if the original request is null

TooManyHopsException - if the original request's Max-Forwards header value is 0

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(SipSession session,
                                SipServletRequest origRequest,
                                java.util.Map<java.lang.String,java.util.List<java.lang.String>> headerMap)
                                throws java.lang.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. If 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.

Parameters:

session - the session on which this request is to be created

origRequest - the original request

headerMap - the header map used to override the headers in the new subsequent request created. Also see createRequest(SipServletRequest, boolean, java.util.Map)

Returns:

the new subsequent request

Throws:

java.lang.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

java.lang.NullPointerException - if the original request or the session is null

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:

java.lang.NullPointerException - if the session is null