B2buaHelper (SIP Servlet API 2.0 API)

```
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 `createRequest(SipServletRequest, boolean, java.util.Map)` or using `createRequest(SipSession, SipServletRequest, java.util.Map)` 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
  - 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:
    
    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:
    
    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)
    
    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:
    
    IllegalArgumentException - if the session is not currently linked to another session or it has been terminated
  - 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.
    
    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:
    
    IllegalArgumentException - if the session is invalid
  - 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.
    
    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:
    
    IllegalStateException - if a subsequent response is inconsistent with an already sent response. For example, a 400 response following a 200 OK response.
    
    IllegalArgumentException - if the session is invalid
  - 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. If an empty list is supplied for a particular header in the headerMap, then that header will be removed. 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:
    
    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
    
    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,
                              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. 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. If an empty list is supplied for a particular header in the headerMap, then that header will be removed.
    
    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:
    
    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
  - 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

Interface B2buaHelper

Method Summary

Method Detail

getLinkedSession

getLinkedSipServletRequest

linkSipSessions

unlinkSipSessions

getPendingMessages

createResponseToOriginalRequest

createRequest

createRequest

createRequest

createCancel