SipSession (EasySIP Resource Adaptor Type 1.5)

```
public interface SipSession
```
The SipSession is the main activity object in the EasySIP API. It roughly corresponds to a SIP dialog but is also used for out-of-dialog requests. This is to reduce the number of activity types that an SBB needs to create and stay attached to, simplifying SBB code. The lifecycle of a SipSession activity depends on how it is used.
UAC (User Agent Client) mode
UAC SipSession activities are created using the SipFactory.createRequest() methods. The OutgoingSipRequest returned by these methods belongs to a new UAC SipSession. The SBB must attach to the SipSession's ActivityContextInterface in order to receive responses. After the request is sent, the SipSession lifecycle proceeds as follows:
If an error response arrives, the SipSession does not end. It may be reused to create another initial request with the same call-id, tag etc. This is to support the case where a redirect response or authentication response is received, so the SBB can easily create a new request with the same parameters and any additional info required, and re-send. If the SBB really does want the SipSession to end at this point, it must call invalidate().
If a successful final response (2xx) arrives, and the initial request was not a dialog-creating request, then the SipSession activity ends automatically. Out of dialog requests are handled in this way, and the SipSession activity represents a single SIP client transaction.
If the initial request was dialog-creating (currently INVITE and SUBSCRIBE), then the SipSession stays alive. The SipSession now represents a "confirmed" SIP dialog between the UAC SBB and the peer UAS, and the SBB may create and send more in-dialog requests using the SipSession, and will also receive in-dialog requests from the peer, as long as the SBB stays attached.
When the SipSession sends or receives a request that ends the dialog (a BYE, or NOTIFY with the "Subsciption-State: terminated" header), the SipSession ends after the response to that request is sent or received. The RA will ensure that activites are ended even if the SBB does not process the request.
UAS (User Agent Server) mode
UAS SipSessions are created automatically by the RA when an incoming initial request is received (a request that does not belong to an existing dialog, ie. no To-tag specified). An IncomingSipRequest event is fired on the SipSession activity.
If the UAS SBB sends an error (3xx-6xx) response, the SipSession activity ends automatically. If the request was not a dialog-creating request, the SipSession also ends when a 2xx response is sent. In this way it behaves like a SIP server transaction. For dialog-creating requests, sending a 2xx response means the SipSession activity stays alive and now represents a "confirmed" SIP dialog between the UAS SBB and the UAC peer. Similarly, sending a 101-199 response will create an "early" dialog, which transitions to "confirmed" when the 2xx response is sent. Now the SBB may create and send more in-dialog requests using the SipSession, and will also receive in-dialog requests from the peer, as long as the SBB stays attached.
When the SipSession sends or receives a request that ends the dialog (a BYE, or NOTIFY with the "Subsciption-State: terminated" header), the SipSession ends after the response to that request is sent or received. The RA will ensure that activites are ended even if the SBB does not process the request.
If the UAS SBB wishes to proxy the request, it must call IncomingSipRequest.getProxy() before generating a response itself. If the SBB generates it's own response, the RA assumes that the SBB is behaving like a UAS (ie. the endpoint of a dialog) and will not allow the request to be proxied. An IllegalStateException will be thrown if the UAS SBB attempts to obtain the proxy after it has already sent a dialog-creating response. If a Proxy is created, the SipSession continues in Proxy mode, explained below.
Proxy mode
A SipSession enters Proxy mode after an SBB calls IncomingSipRequest.getProxy() on the initial request. If the initial request was not a dialog-creating request, the SipSession ends when the final response is forwarded by the proxy. If the initial request was dialog-creating, the SipSession ends if an error response is forwarded by the proxy. If a 2xx response is received for a dialog-creating request, the SipSession represents the confirmed SIP dialog between the 2 SIP endpoints. The proxy SBB will then receive all subsequent in-dialog requests from either endpoint, as long as it is attached to the SipSession activity. In-dialog requests will be forwarded automatically (unless the SBB sends it's own response to an in-dialog request - see the Proxy documentation for details).
A proxy mode SipSession may not be used for initiating in-dialog requests (createRequest(String) will throw an \IllegalStateException), since this is not the role of a proxy. A proxy may only forward requests from the SIP endpoints, but can modify these requests as they pass through, or reject them.
As before, when a dialog-ending request is received from either party, the SipSession ends when the corresponding response is received.
Forcibly ending a SipSession
SipSessions may be ended at any time by calling invalidate(). This just removes the activity state from the SLEE and RA, it does not cause any SIP messages to be sent. If the RA receives subsequent requests for an unknown SipSession, these will be automatically rejected with a "481 (Call or Transaction Does Not Exist)" response.
Retransmit Behaviour
UAS or UAC SipSessions will automatically perform retransmits of the INVITE 2xx responses and ACKs, respectively. The SBB does not need to do anything else after sending the first 2xx or ACK. This also applies to re-INVITEs on an existing SipSession. For Proxy SipSessions, no special retransmit handling is performed since this is the responsibility of the SIP endpoints. All 2xx responses and ACKs will be passed through so that the SIP endpoints can deal with them.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class SipSession.State
Describes the state of a SipSession's underlying SIP dialog.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`SipSession.State` Describes the state of a SipSession's underlying SIP dialog.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`OutgoingSipRequest`	`createForkedNotify(IncomingSipRequest notify)` Creates a new outgoing NOTIFY request and a new `SipSession`, for forwarding forked NOTIFY requests upstream.
`OutgoingSipRequest`	`createRequest(IncomingSipRequest original)` Create a new request on this session, with all headers and content copied from another request.
`OutgoingSipRequest`	`createRequest(String method)`
`Object`	`getAttribute(String name)` Returns the object bound to the specified attribute name in this session
`Iterable<String>`	`getAttributeNames()` Returns all attribute names that have been bound to objects in this session.
`String`	`getCallId()`
`DialogID`	`getDialogID()` Get this session's `DialogID`
`String`	`getId()` Returns a string containing the unique identifier assigned to this session.
`SipRequest`	`getInitialRequest()` Get the incoming or outgoing request that initiated this session.
`Address`	`getLocalParty()`
`IncomingSipRequest`	`getPendingIncomingRequest(long cseq)` Retrieve a pending incoming request received on this session.
`Iterable<IncomingSipRequest>`	`getPendingIncomingRequests()` Retrieve all pending incoming requests on this session.
`OutgoingSipRequest`	`getPendingOutgoingRequest(long cseq)` Retrieve a pending outgoing request sent on this session.
`Iterable<OutgoingSipRequest>`	`getPendingOutgoingRequests()` Retrieve all pending outgoing requests on this session.
`Address`	`getRemoteParty()`
`SipSession.State`	`getSessionState()` Retrieve the current state of the SipSession
`SipFactory`	`getSipFactory()` Get the `SipFactory` that created this SipSession.
`void`	`invalidate()` Ends this SipSession activity.
`boolean`	`isEndImmediately()` Returns the current value of this session's `endImmediately` flag.
`boolean`	`isInviteTerminated()`
`boolean`	`isSubscriptionsTerminated()`
`void`	`removeAttribute(String name)` Removes the named object from this session.
`void`	`sendCancel()` Convenience method to send a CANCEL request for the current outgoing INVITE request on this session.
`void`	`setAttribute(String name, Object value)` Binds an object to an attribute name in this session
`void`	`setEndImmediately(boolean endImmediately)` Specify whether this session activity will end immediately after a dialog-ending message is sent or received (e.g.
`void`	`setLocalContactAddress(Address address)` Enforces the policy where specified local Contact header is used for all outgoing responses and requests.
`void`	`startReplicating()` Instructs the SIS to begin replicating this session's state.

- Method Detail
  - getId
```
String getId()
```
    Returns a string containing the unique identifier assigned to this session. The value is assigned by the RA and is implementation-specific, and does not necessarily to correspond to the dialog ID.
    
    Returns:
    
    a string specifying the unique identifier assigned to this session
  - invalidate
```
void invalidate()
```
    Ends this SipSession activity. Subsequent operations on this session will fail with IllegalStateException.
  - getCallId
```
String getCallId()
```
  - getLocalParty
```
Address getLocalParty()
```
  - getRemoteParty
```
Address getRemoteParty()
```
  - createRequest
```
OutgoingSipRequest createRequest(String method)
```
  - createRequest
```
OutgoingSipRequest createRequest(IncomingSipRequest original)
```
    Create a new request on this session, with all headers and content copied from another request. Headers that are derived from the dialog state (Call-Id, CSeq, Route, From, To and the request-URI) are not copied, they are set from the dialog state as usual. This is a convenience method so that B2BUAs can forward in-dialog requests easily.
    
    Parameters:
    
    original - the original request, will usually have been received on a different SipSession.
    
    Returns:
    
    a new request on this session
    
    Since:
    
    EasySIP 1.0 - no equivalent in SIP Servlet API
  - createForkedNotify
```
OutgoingSipRequest createForkedNotify(IncomingSipRequest notify)
```
    Creates a new outgoing NOTIFY request and a new SipSession, for forwarding forked NOTIFY requests upstream.
    This is a convenience method so that B2BUAs handling several UAC SipSessions created by a downstream element forking an initial SUBSCRIBE can easily create the corresponding UAS SipSessions. The new forked UAS session can be obtained by calling SipMessage.getSession() on the returned OutgoingSipRequest.
    The caller sends the new NOTIFY upstream by calling its OutgoingSipRequest.send() method.
    
    Parameters:
    
    notify - a forked NOTIFY request received on a UAC SipSession
    
    Returns:
    
    a new OutgoingSipRequest copied from the incoming request, but with the relevant headers set from the dialog state of the new SipSession. The Call-Id and remote tag will are copied from the UAS SipSession that was created by the initial SUBSCRIBE, and the local tag will be taken from the from-tag of the incoming NOTIFY.
    
    Throws:
    
    IllegalArgumentException - if the request was not a forked NOTIFY request, see IncomingSipRequest.isForked()
    
    Since:
    
    EasySIP RA Type 1.4
  - getInitialRequest
```
SipRequest getInitialRequest()
```
    Get the incoming or outgoing request that initiated this session.
    
    Since:
    
    EasySIP 1.0 - not in SIP Servlet API
  - getSipFactory
```
SipFactory getSipFactory()
```
    Get the SipFactory that created this SipSession.
    
    Since:
    
    EasySIP 1.0 - no equivalent in SIP Servlet API
  - sendCancel
```
void sendCancel()
         throws SipException
```
    Convenience method to send a CANCEL request for the current outgoing INVITE request on this session. If there is no outgoing INVITE request (client transaction) in progress, this method throws an exception.
    
    Throws:
    
    SipException - if unable to create the cancel request
    
    Since:
    
    EasySIP 1.2
  - setAttribute
```
void setAttribute(String name,
                  Object value)
```
    Binds an object to an attribute name in this session
    
    Parameters:
    
    name - a string specifying the name of the object, may not be null
    
    value - the object to be bound
    
    Throws:
    
    NullPointerException - if name or value are null
  - getAttribute
```
Object getAttribute(String name)
```
    Returns the object bound to the specified attribute name in this session
    
    Parameters:
    
    name - the attribute name, may not be null
    
    Returns:
    
    the object bound to the attribute name, or null if there is no object with that name
    
    Throws:
    
    NullPointerException - if name is null
  - removeAttribute
```
void removeAttribute(String name)
```
    Removes the named object from this session. If no object is bound to the name, this method does nothing.
    
    Parameters:
    
    name - the attribute name, may not be null
    
    Throws:
    
    NullPointerException - if name is null
  - getAttributeNames
```
Iterable<String> getAttributeNames()
```
    Returns all attribute names that have been bound to objects in this session. The order of attribute names is undefined. Note the returned collection is a snapshot of the current attribute names, any changes to the underlying attributes will not propagate to the collection.
    
    Returns:
    
    a read-only collection of strings, empty if there were no attributes stored in the session.
  - setEndImmediately
```
void setEndImmediately(boolean endImmediately)
```
    Specify whether this session activity will end immediately after a dialog-ending message is sent or received (e.g. BYE). The default value is true. If set to false, the application must end the session explicitly using invalidate(). This gives the application a chance to keep using session attributes before the activity is finally ended in the SLEE. If the application does not call invalidate() itself, the session activity will be ended automatically by RA's next query-liveness processing, which occurs when the activity has been idle for some time, typically 5 minutes.
    
    Parameters:
    
    endImmediately - set to false to delay the automatic ending of this activity.
    
    Since:
    
    EasySIP 1.4
  - isEndImmediately
```
boolean isEndImmediately()
```
    Returns the current value of this session's endImmediately flag.
    
    Returns:
    
    the session's endImmediately flag
    
    Since:
    
    EasySIP 1.4
  - setLocalContactAddress
```
void setLocalContactAddress(Address address)
```
    Enforces the policy where specified local Contact header is used for all outgoing responses and requests. This method should only be used by an application in role of UAS or UAC. Once set cannot be changed after a dialog creating response is sent for UAS or initial request is sent for UAC. When a forked outgoing response is created UAS session local Contact header will not be copied into the new session spawned by the forked response. When a forking incoming response creates a new UAC session local Contact header will be copied into the new session spawned by the forking response.
    
    Parameters:
    
    address - local Contact address
    
    Throws:
    
    IllegalStateException - if attempted to be set after dialog creating response is sent
    
    NullPointerException - if address is null
    
    Since:
    
    EasySIP 1.4
  - getSessionState
```
SipSession.State getSessionState()
```
    Retrieve the current state of the SipSession
    
    Returns:
    
    a SipSession.State value
    
    Since:
    
    EasySIP 1.4
  - getPendingIncomingRequest
```
IncomingSipRequest getPendingIncomingRequest(long cseq)
```
    Retrieve a pending incoming request received on this session. A pending incoming request represents an active SIP server transaction on this session, for which no final response has been sent yet. This may include the session's initial request, if it was an incoming request.
    
    Parameters:
    
    cseq - the sequence number of the request.
    
    Returns:
    
    the matching pending IncomingSipRequest, or null if no such request was found.
    
    Since:
    
    EasySIP 1.4
  - getPendingOutgoingRequest
```
OutgoingSipRequest getPendingOutgoingRequest(long cseq)
```
    Retrieve a pending outgoing request sent on this session. A pending outgoing request represents an active SIP client transaction on this session, for which no final response has been received yet. This may include the session's initial request, if it was an outgoing request.
    
    Parameters:
    
    cseq - the sequence number of the request.
    
    Returns:
    
    the matching pending OutgoingSipRequest, or null if no such request was found.
    
    Since:
    
    EasySIP 1.4
  - getPendingIncomingRequests
```
Iterable<IncomingSipRequest> getPendingIncomingRequests()
```
    Retrieve all pending incoming requests on this session. A pending incoming request represents an active SIP server transaction on this session, for which no final response has been sent yet. This may include the session's initial request, if it was an incoming request.
    
    Returns:
    
    a read-only sequence of IncomingSipRequests, empty if there are currently no pending requests.
    
    Since:
    
    EasySIP 1.4
  - getPendingOutgoingRequests
```
Iterable<OutgoingSipRequest> getPendingOutgoingRequests()
```
    Retrieve all pending outgoing requests on this session. A pending outgoing request represents an active SIP client transaction on this session, for which no final response has been received yet. This may include the session's initial request, if it was an outgoing request.
    
    Returns:
    
    a read-only sequence of OutgoingSipRequests, empty if there are currently no pending requests.
    
    Since:
    
    EasySIP 1.4
  - getDialogID
```
DialogID getDialogID()
```
    Get this session's DialogID
  - startReplicating
```
void startReplicating()
```
    Instructs the SIS to begin replicating this session's state.
    If replication is disabled in the SIS, or the session is already replicating, this method does nothing.
    Otherwise if replication is enabled in the SIS, then this method instructs the SIS to begin replicating the session state.
  - isInviteTerminated
```
boolean isInviteTerminated()
```
  - isSubscriptionsTerminated
```
boolean isSubscriptionsTerminated()
```

Interface SipSession

UAC (User Agent Client) mode

UAS (User Agent Server) mode

Proxy mode

Forcibly ending a SipSession

Retransmit Behaviour

Nested Class Summary

Method Summary

Method Detail

getId

invalidate

getCallId

getLocalParty

getRemoteParty

createRequest

createRequest

createForkedNotify

getInitialRequest

getSipFactory

sendCancel

setAttribute

getAttribute

removeAttribute

getAttributeNames

setEndImmediately

isEndImmediately

setLocalContactAddress

getSessionState

getPendingIncomingRequest

getPendingOutgoingRequest

getPendingIncomingRequests

getPendingOutgoingRequests

getDialogID

startReplicating

isInviteTerminated

isSubscriptionsTerminated