SmppSession (OpenCloud SMPP Resource Adaptor Type API 2.3)

```
public interface SmppSession
```
This interface represents an SBB’s view of an SMPP session.
Sessions may either be “bound” or “service-managed”.
Service-managed sessions are created when a service tells the resource adaptor to connect to another node using SmppProvider.openSession(String, int) or when an incoming connection is received.
Bound sessions are created when the resource adaptor activates, if it has bound sessions configured. Bound sessions can be retrieved from the resource adaptor by using the SmppProvider.getBoundSession(String) method.
Service-managed Sessions
The session represents a point-to-point connection between 2 SMPP nodes. One node is always behaving as an ESME (External Short Message Entity) and the other is a MC (Message Center, a.k.a. SMSC). The type of node that the service is behaving as is determined by how the session is initiated.
For example, if the service opens a connection and then attempts to send a BIND_TRANSMITTER request, then the session type is set to ESME as this is ESME behaviour. Similarly if the service opens a connection and then sends an OUTBIND, it will be treated as a MC node.
The state of the session changes automatically as messages are processed by the implementation. The session type (ESME or MC) and state determine what SMPP operations are permitted.
There are methods to close the session, create outgoing request activities for responses to be fired on, send requests whose responses will be fired on this activity.
Bound Sessions
A bound session is persistent. The resource adaptor manages session setup and tear-down, a service can only send and receive certain types of requests and responses. Incoming connections cannot be bound sessions.
If the session is closed by the remote node, the resource adaptor will automatically attempt to reconnect at regular intervals. If a service attempts to send a message while the RA is in this state, an IllegalStateException will be thrown. SBBs should use the isBound() method to determine if the SMPP session is connection and bound.
A resource adaptor entity can be configured with multiple bound sessions, but there is no automatic failover between them. SBBs can use multiple sessions, and the isBound() method to implement failover.
Synchronous vs Asynchronous Requests
The SMPP protocol is inherently asynchronous, and as such this implementation uses an asynchronous model as well. Responses to requests are received as SLEE events.
For convenience, a blocking sendSyncRequest(com.opencloud.slee.resources.smpp.pdu.Request) method has been provided for simpler services that do not need to be asynchronous.
Note: The synchronous API should only be used for simple test services that are not expected to run at high loads. Services that use the synchronous model also do not scale well.
Examples
An ESME connecting and binding to a Message Center
```
    BindTransmitter bindRequest = new BindTransmitter();
    bindRequest.setInterfaceVersion((byte)0x34);  // SMPP V3.4
    bindRequest.setSystemID("esme");
    bindRequest.setPassword("secret");
    session.sendRequest(bindRequest); // asynchronous send ...

    // ... response received by a "handleResponse" event handler method:
    void onBindTransmitterResponseEvent(SmppResponseEvent event, ActivityContextInterface aci) {
        Response r = event.getResponse();
        if ((r.getCommandID == CommandID.BIND_TRANSMITTER_RESP) &&
            (r.getCommandStatus == CommandStatus.ESME_ROK)) {
            // MC successfully authenticated bind, session
            // is now in BOUND_TX state.
        }
    }
```

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`STATE_ALL` bitwise OR of all valid session states
`static int`	`STATE_BOUND` bitwise OR of all bound session states
`static int`	`STATE_BOUND_RX` The ESME has performed a successful BIND_RECEIVER operation with the MC, session is bound.
`static int`	`STATE_BOUND_TRX` The ESME has performed a successful BIND_TRANSCEIVER operation with the MC, session is bound.
`static int`	`STATE_BOUND_TX` The ESME has performed a successful BIND_TRANSMITTER operation with the MC, session is bound.
`static int`	`STATE_INVALID` session has been closed, no actions permitted
`static int`	`STATE_OPEN` session is open, ESME has connected to MC but not yet bound.
`static int`	`STATE_OUTBOUND` session is outbound, MC has sent an outbind request to ESME.
`static int`	`STATE_UNBOUND` Either the MC or ESME has processed an UNBIND operation.
`static int`	`TYPE_ESME` This node is acting as an ESME (External Short Message Entity) in this session.
`static int`	`TYPE_MC` This node is acting as a MC (Message Center aka SMSC) in this session.
`static int`	`TYPE_NONE` The type of this node has not yet been derived - see State Machine above.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`closeSession()` Closes this session.
`OutgoingSmppRequestActivity`	`createRequestActivity()` Create a new OutgoingSmppRequestActivity that can be used to send requests.
`java.net.InetSocketAddress`	`getPeerAddress()` Get the remote address of the TCP connection for this session.
`int`	`getSequenceNumber()` Get the current PDU sequence number for this session.
`int`	`getState()` Get state of this session
`int`	`getType()` Get session type
`boolean`	`isBound()` Tests if the underlying SMPP session is connected to a peer and in one of the bound states (BOUND_TX, BOUND_RX or BOUND_TRX).
`int`	`sendRequest(Request request)` Send an SMPP request on this session.
`void`	`sendResponse(Response response)` Send an SMPP response on this session.
`<T extends Response> ResponseFuture<T>`	`sendSyncRequest(Request request)` Send an SMPP request on this session, and return a future that the response can be retrieved from when the caller is ready.
`Response`	`sendSyncRequestAndWait(Request request)` Deprecated. Use sendSyncRequest(request).get() instead.

- Field Detail
  - STATE_INVALID
```
static final int STATE_INVALID
```
    session has been closed, no actions permitted
    
    See Also:
    Constant Field Values
  - STATE_OPEN
```
static final int STATE_OPEN
```
    session is open, ESME has connected to MC but not yet bound.
    
    See Also:
    Constant Field Values
  - STATE_OUTBOUND
```
static final int STATE_OUTBOUND
```
    session is outbound, MC has sent an outbind request to ESME.
    
    See Also:
    Constant Field Values
  - STATE_BOUND_TX
```
static final int STATE_BOUND_TX
```
    The ESME has performed a successful BIND_TRANSMITTER operation with the MC, session is bound.
    
    See Also:
    Constant Field Values
  - STATE_BOUND_RX
```
static final int STATE_BOUND_RX
```
    The ESME has performed a successful BIND_RECEIVER operation with the MC, session is bound.
    
    See Also:
    Constant Field Values
  - STATE_BOUND_TRX
```
static final int STATE_BOUND_TRX
```
    The ESME has performed a successful BIND_TRANSCEIVER operation with the MC, session is bound.
    
    See Also:
    Constant Field Values
  - STATE_UNBOUND
```
static final int STATE_UNBOUND
```
    Either the MC or ESME has processed an UNBIND operation.
    
    See Also:
    Constant Field Values
  - STATE_ALL
```
static final int STATE_ALL
```
    bitwise OR of all valid session states
    
    See Also:
    Constant Field Values
  - STATE_BOUND
```
static final int STATE_BOUND
```
    bitwise OR of all bound session states
    
    See Also:
    Constant Field Values
  - TYPE_NONE
```
static final int TYPE_NONE
```
    The type of this node has not yet been derived - see State Machine above.
    
    See Also:
    Constant Field Values
  - TYPE_MC
```
static final int TYPE_MC
```
    This node is acting as a MC (Message Center aka SMSC) in this session.
    
    See Also:
    Constant Field Values
  - TYPE_ESME
```
static final int TYPE_ESME
```
    This node is acting as an ESME (External Short Message Entity) in this session.
    
    See Also:
    Constant Field Values
- Method Detail
  - createRequestActivity
```
OutgoingSmppRequestActivity createRequestActivity()
                                                  throws SmppException,
                                                         java.lang.IllegalStateException
```
    Create a new OutgoingSmppRequestActivity that can be used to send requests.
    SBBs must attach to this activity in order to receive the response event.
    
    Returns:
    the new activity
    
    Throws:
    
    SmppException - if there was a problem creating the activity (e.g. the SLEE refused to do so)
    
    java.lang.IllegalStateException - if the session is not in the appropriate state
  - sendRequest
```
int sendRequest(Request request)
                throws SmppSendException,
                       java.lang.IllegalStateException,
                       java.lang.IllegalArgumentException
```
    Send an SMPP request on this session. The sequence number in the PDU is automatically set to the next available sequence number for the session. This method returns the sequence number used.
    For requests not related to session management, you must use createRequestActivity() and OutgoingSmppRequestActivity.sendRequest(com.opencloud.slee.resources.smpp.pdu.Request) to send requests.
    Session management requests are:
    - BIND_TRANSMITTER
    - BIND_RECEIVER
    - BIND_TRANSCEIVER
    - OUTBIND
    - UNBIND
    - ENQUIRE_LINK
    Parameters:
    request - the SMPP request PDU to send.
    
    Returns:
    the sequence number assigned by the stack to this request.
    
    Throws:
    
    SmppSendException - if an error occurs, and the request cannot be sent.
    
    java.lang.IllegalStateException - if the session is not in the appropriate state to send this message (eg. not bound).
    
    java.lang.IllegalArgumentException - if this is a bound session, or when Request is not a session management request and this is a service-managed session
  - sendSyncRequest
```
<T extends Response> ResponseFuture<T> sendSyncRequest(Request request)
                                                   throws SmppSendException,
                                                          java.lang.IllegalStateException
```
    Send an SMPP request on this session, and return a future that the response can be retrieved from when the caller is ready.
    The sequence number in the PDU is automatically set to the next available sequence number in the session. Note: Because the future returned by this method blocks the calling thread until a response is received or some error occurs (eg. timeout), this method should not be used in services that need to perform and scale well.
    This method is provided for convenience to developers writing simple test services.
    
    Parameters:
    request - the SMPP request PDU to send.
    
    Returns:
    a future to retrieve the response from
    
    Throws:
    
    java.lang.IllegalStateException - if the session is not in the appropriate state to send this message (eg. not bound).
    
    SmppSendException - if an error occurs, and the request cannot be sent.
  - sendSyncRequestAndWait
```
@Deprecated
Response sendSyncRequestAndWait(Request request)
                                throws SmppSendException,
                                       java.lang.IllegalStateException
```
    Deprecated. Use sendSyncRequest(request).get() instead.
    
    Send an SMPP request on this session, and block until the response is received.
    The sequence number in the PDU is automatically set to the next available sequence number in the session. Note: Because this method blocks the calling thread until a response is received or some error occurs (eg. timeout), this method should not be used in services that need to perform and scale well.
    This method is provided for convenience to developers writing simple test services.
    
    Parameters:
    request - the SMPP request PDU to send.
    
    Returns:
    a future to retrieve the response from
    
    Throws:
    
    java.lang.IllegalStateException - if the session is not in the appropriate state to send this message (eg. not bound).
    
    SmppSendException - if an error occurs, and the request cannot be sent.
  - sendResponse
```
void sendResponse(Response response)
                  throws SmppSendException,
                         java.lang.IllegalStateException
```
    Send an SMPP response on this session. The response object should be created by calling the createResponse method on the corresponding Request object. This will automatically set the response sequence number to that of the request.
    This method must not be used for requests that arrive on IncomingSmppRequestActivity activities. Responses must be sent on the incoming request activity, or the activity will not end.
    
    Parameters:
    response - the SMPP response PDU to send.
    
    Throws:
    
    java.lang.IllegalStateException - if the session is not in the appropriate state to send this message (eg. not bound).
    
    SmppSendException - if an error occurs, and the response cannot be sent.
  - closeSession
```
void closeSession()
```
    Closes this session. The session will no longer be usable after this method is called.
  - getState
```
int getState()
```
    Get state of this session
  - getType
```
int getType()
```
    Get session type
  - getSequenceNumber
```
int getSequenceNumber()
```
    Get the current PDU sequence number for this session. This sequence number will be used on the next outgoing request, and incremented automatically by the implementation.
  - isBound
```
boolean isBound()
```
    Tests if the underlying SMPP session is connected to a peer and in one of the bound states (BOUND_TX, BOUND_RX or BOUND_TRX).
    
    Returns:
    true if SMPP session is connected and bound, otherwise false
  - getPeerAddress
```
java.net.InetSocketAddress getPeerAddress()
```
    Get the remote address of the TCP connection for this session.
    
    Returns:
    the remote address for this session

Interface SmppSession

Service-managed Sessions

Bound Sessions

Synchronous vs Asynchronous Requests

Examples

An ESME connecting and binding to a Message Center

Field Summary

Method Summary

Field Detail

STATE_INVALID

STATE_OPEN

STATE_OUTBOUND

STATE_BOUND_TX

STATE_BOUND_RX

STATE_BOUND_TRX

STATE_UNBOUND

STATE_ALL

STATE_BOUND

TYPE_NONE

TYPE_MC

TYPE_ESME

Method Detail

createRequestActivity

sendRequest

sendSyncRequest

sendSyncRequestAndWait

sendResponse

closeSession

getState

getType

getSequenceNumber

isBound

getPeerAddress