com.cloudhopper.smpp

Interface SmppSession

All Known Subinterfaces:

SmppServerSession

All Known Implementing Classes:

DefaultSmppSession

public interface SmppSession

Defines a common interface for either a Client (ESME) or Server (SMSC) SMPP session.

Author:

joelauer (twitter: @jjlauer or http://twitter.com/jjlauer)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SmppSession.Type The type of SMPP session.

Field Summary

Fields

Modifier and Type	Field and Description
static int	STATE_BINDING Session is in the process of binding.
static int	STATE_BOUND Session is bound (ready to process requests)
static int	STATE_CLOSED Session is unbound and closed (destroyed)
static int	STATE_INITIAL Session is in an initial state (not connected, but created)
static int	STATE_OPEN Session is connected and a bind is pending
static int	STATE_UNBINDING Session is in the process of un-binding.
static String[]	STATES Descriptions of each state

Method Summary

Methods

Modifier and Type	Method and Description
boolean	areOptionalParametersSupported() Returns whether optional parameters are supported with the remote endpoint.
void	close() Immediately close the session by closing the underlying socket/channel.
void	destroy() Destroy a session by ensuring the socket is closed and all resources are cleaned up.
EnquireLinkResp	enquireLink(EnquireLink request, long timeoutMillis) Synchronously sends an "enquire_link" request to the remote endpoint and waits for up to a specified number of milliseconds for a response.
SmppBindType	getBindType() Gets the type of bind for this session such as "transceiver", "receiver", or "transmitter".
long	getBoundTime() Returns the System.currentTimeMillis() value of when this session reached the "BOUND" state.
SmppSessionConfiguration	getConfiguration() Gets the configuration associated with this session.
SmppSessionCounters	getCounters() Gets the counters this session is tracking.
byte	getInterfaceVersion() Gets the interface version currently in use between local and remote endpoints.
SmppSession.Type	getLocalType() Gets the session type of the local system.
SmppSession.Type	getRemoteType() Gets the session type of the remote system.
com.cloudhopper.commons.util.windowing.Window<Integer,PduRequest,PduResponse>	getRequestWindow() Deprecated.
com.cloudhopper.commons.util.windowing.Window<Integer,PduRequest,PduResponse>	getSendWindow() Gets the underlying request "window" for this session.
String	getStateName() Gets the name of the current state of the session.
boolean	hasCounters() Returns true if and only if this session has counters enabled.
boolean	isBinding() Checks if the session is currently in the "BINDING" state.
boolean	isBound() Checks if the session is currently in the "BOUND" state.
boolean	isClosed() Checks if the session is currently in the "CLOSED" state.
boolean	isOpen() Checks if the session is currently in the "OPEN" state.
boolean	isUnbinding() Checks if the session is currently in the "UNBINDING" state.
com.cloudhopper.commons.util.windowing.WindowFuture<Integer,PduRequest,PduResponse>	sendRequestPdu(PduRequest request, long timeoutMillis, boolean synchronous) Main underlying method for sending a request PDU to the remote endpoint.
void	sendResponsePdu(PduResponse response) Main underlying method for sending a response PDU to the remote endpoint.
SubmitSmResp	submit(SubmitSm request, long timeoutMillis) Synchronously sends a "submit" request to the remote endpoint and waits for up to a specified number of milliseconds for a response.
void	unbind(long timeoutMillis) Attempts to "unbind" the session, waiting up to a specified period of milliseconds for an unbind response from the remote endpoint.

Field Detail

STATE_INITIAL

static final int STATE_INITIAL

Session is in an initial state (not connected, but created)

See Also:

Constant Field Values

STATE_OPEN

static final int STATE_OPEN

Session is connected and a bind is pending

See Also:

Constant Field Values

STATE_BINDING

static final int STATE_BINDING

Session is in the process of binding. If local is ESME, we sent the bind request. If the local is SMSC, then the ESME initiated a bind request, but we have't responded yet.

See Also:

Constant Field Values

STATE_BOUND

static final int STATE_BOUND

Session is bound (ready to process requests)

See Also:

Constant Field Values

STATE_UNBINDING

static final int STATE_UNBINDING

Session is in the process of un-binding. This may have been initiated by us or them.

See Also:

Constant Field Values

STATE_CLOSED

static final int STATE_CLOSED

Session is unbound and closed (destroyed)

See Also:

Constant Field Values

STATES

static final String[] STATES

Descriptions of each state

Method Detail

getBindType

SmppBindType getBindType()

Gets the type of bind for this session such as "transceiver", "receiver", or "transmitter".

Returns:

The type of bind for this session

getLocalType

SmppSession.Type getLocalType()

Gets the session type of the local system. If the local type is ESME, then we are connected to an SMSC. We are permitted to send submit_sm or data_sm requests.

Returns:

The session type of the local system

getRemoteType

SmppSession.Type getRemoteType()

Gets the session type of the remote system. If the remote type is SMSC, then we are the ESME. We are permitted to send submit_sm or data_sm requests.

Returns:

The session type of the remote system

getConfiguration

SmppSessionConfiguration getConfiguration()

Gets the configuration associated with this session.

Returns:

The session configuration

getStateName

String getStateName()

Gets the name of the current state of the session.

Returns:

The current state of the session by name such as "CLOSED"

getInterfaceVersion

byte getInterfaceVersion()

Gets the interface version currently in use between local and remote endpoints. This interface version is negotiated during the bind process to mainly ensure that optional parameters are supported.

Returns:

The interface version currently in use between local and remote endpoints.

areOptionalParametersSupported

boolean areOptionalParametersSupported()

Returns whether optional parameters are supported with the remote endpoint. If the interface version currently in use is >= 3.4, then this method returns true, otherwise will return false.

Returns:

True if optional parameters are supported, otherwise false.

isOpen

boolean isOpen()

Checks if the session is currently in the "OPEN" state. The "OPEN" state means the session is connected and a bind is pending.

Returns:

True if session is currently in the "OPEN" state, otherwise false.

isBinding

boolean isBinding()

Checks if the session is currently in the "BINDING" state. The "BINDING" state means the session is in the process of binding. If local is ESME, we sent the bind request, but have not yet received the bind response. If the local is SMSC, then the ESME initiated a bind request, but we have't responded yet.

Returns:

True if session is currently in the "BINDING" state, otherwise false.

isBound

boolean isBound()

Checks if the session is currently in the "BOUND" state. The "BOUND" state means the session is bound and ready to process requests.

Returns:

True if session is currently in the "BOUND" state, otherwise false.

isUnbinding

boolean isUnbinding()

Checks if the session is currently in the "UNBINDING" state. The "UNBINDING" state means the session is in the process of unbinding. This may have been initiated by us or them.

Returns:

True if session is currently in the "UNBINDING" state, otherwise false.

isClosed

boolean isClosed()

Checks if the session is currently in the "CLOSED" state. The "CLOSED" state means the session is unbound and closed (destroyed).

Returns:

True if session is currently in the "CLOSED" state, otherwise false.

getBoundTime

long getBoundTime()

Returns the System.currentTimeMillis() value of when this session reached the "BOUND" state.

Returns:

The System.currentTimeMillis() value when the session was bound.

getRequestWindow

com.cloudhopper.commons.util.windowing.Window<Integer,PduRequest,PduResponse> getRequestWindow()

Deprecated.

See Also:

getSendWindow()

getSendWindow

com.cloudhopper.commons.util.windowing.Window<Integer,PduRequest,PduResponse> getSendWindow()

Gets the underlying request "window" for this session. A "window" represents a request sent to the remote endpoint, but has not received a response yet. Accessing this property is useful if unacknowledged requests need to be cleared out (most likely for a retry at a later time).

Returns:

The request "window"

hasCounters

boolean hasCounters()

Returns true if and only if this session has counters enabled.

Returns:

True if the session has counters

getCounters

SmppSessionCounters getCounters()

Gets the counters this session is tracking.

Returns:

The session counters or null if counters are disabled.

close

void close()

Immediately close the session by closing the underlying socket/channel. This method will not attempt to "unbind" first, rather just immediately close the channel. Once closed, this session is not usable. It is always recommended an proper unbind is attempted first, rather than just closing the socket.

See Also:

unbind(long)

unbind

void unbind(long timeoutMillis)

Attempts to "unbind" the session, waiting up to a specified period of milliseconds for an unbind response from the remote endpoint. Regardless of whether a proper unbind response was received, the socket/channel is closed.

Parameters:

timeoutMillis - The number of milliseconds to wait until an unbind response is received from the SMSC.

See Also:

close()

destroy

void destroy()

Destroy a session by ensuring the socket is closed and all resources are cleaned up. This method should the last method called before discarding or losing a reference to a session. Since this method cleans up all resources, make sure that any data you need to access is accessed before calling this method. After calling this method it is not guaranteed that any other method will correctly work.

enquireLink

EnquireLinkResp enquireLink(EnquireLink request,
                          long timeoutMillis)
                            throws RecoverablePduException,
                                   UnrecoverablePduException,
                                   SmppTimeoutException,
                                   SmppChannelException,
                                   InterruptedException

Synchronously sends an "enquire_link" request to the remote endpoint and waits for up to a specified number of milliseconds for a response. The timeout value includes both waiting for a "window" slot, the time it takes to transmit the actual bytes on the socket, and for the remote endpoint to send a response back.

Parameters:

request - The request to send to the remote endpoint

timeoutMillis - The number of milliseconds to wait until a valid response is received.

Returns:

A valid response to the request

Throws:

RecoverablePduException - Thrown when a recoverable PDU error occurs. A recoverable PDU error includes the partially decoded PDU in order to generate a negative acknowledgement (NACK) response.

UnrecoverablePduException - Thrown when an unrecoverable PDU error occurs. This indicates a seriours error occurred and usually indicates the session should be immediately terminated.

SmppTimeoutException - A timeout occurred while waiting for a response from the remote endpoint. A timeout can either occur with an unresponse remote endpoint or the bytes were not written in time.

SmppChannelException - Thrown when the underlying socket/channel was unable to write the request.

InterruptedException - The calling thread was interrupted while waiting to acquire a lock or write/read the bytes from the socket/channel.

submit

SubmitSmResp submit(SubmitSm request,
                  long timeoutMillis)
                    throws RecoverablePduException,
                           UnrecoverablePduException,
                           SmppTimeoutException,
                           SmppChannelException,
                           InterruptedException

Synchronously sends a "submit" request to the remote endpoint and waits for up to a specified number of milliseconds for a response. The timeout value includes both waiting for a "window" slot, the time it takes to transmit the actual bytes on the socket, and for the remote endpoint to send a response back.

Parameters:

request - The request to send to the remote endpoint

timeoutMillis - The number of milliseconds to wait until a valid response is received.

Returns:

A valid response to the request

Throws:

RecoverablePduException - Thrown when a recoverable PDU error occurs. A recoverable PDU error includes the partially decoded PDU in order to generate a negative acknowledgement (NACK) response.

UnrecoverablePduException - Thrown when an unrecoverable PDU error occurs. This indicates a seriours error occurred and usually indicates the session should be immediately terminated.

SmppTimeoutException - A timeout occurred while waiting for a response from the remote endpoint. A timeout can either occur with an unresponse remote endpoint or the bytes were not written in time.

SmppChannelException - Thrown when the underlying socket/channel was unable to write the request.

InterruptedException - The calling thread was interrupted while waiting to acquire a lock or write/read the bytes from the socket/channel.

sendRequestPdu

com.cloudhopper.commons.util.windowing.WindowFuture<Integer,PduRequest,PduResponse> sendRequestPdu(PduRequest request,
                                                                                                 long timeoutMillis,
                                                                                                 boolean synchronous)
                                                                                                   throws RecoverablePduException,
                                                                                                          UnrecoverablePduException,
                                                                                                          SmppTimeoutException,
                                                                                                          SmppChannelException,
                                                                                                          InterruptedException

Main underlying method for sending a request PDU to the remote endpoint. If no sequence number was assigned to the PDU, this method will assign one. The PDU will be converted into a sequence of bytes by the underlying transcoder. Also, adds the request to the underlying request "window" by either taking or waiting for an open slot. If "synchronous", the request "window" will be flagged so that the eventual response will be routed back to the "request future" returned from this method vs. routed back to the session handler and "fireUnexpectedPduResponseReceived" would be triggered. If not "synchronous", then the eventual response will be passed to the "fireExpectedPduResponseReceived" method on the session handler. Please note that its possible th response PDU really isn't the correct PDU we were waiting for, so the caller should verify it. For example it is possible that a "Generic_Nack" could be returned by the remote endpoint in response to a PDU.

Parameters:

requestPdu - The request PDU to send

timeoutMillis - If synchronous is true, this represents the time to wait for a slot to open in the underlying window AND the time to wait for a response back from the remote endpoint. If synchronous is false, this only represents the time to wait for a slot to open in the underlying window.

synchronous - True if the calling thread plans on waiting for a response on the returned future. False if the calling thread plans on discarding the returned future and expects the response PDU to be passed to the "fireExpectedPduResponseReceived" method on the session handler.

Returns:

A future object that can be synchronized against when a response is returned.

Throws:

RecoverablePduException - Thrown when a recoverable PDU error occurs. A recoverable PDU error includes the partially decoded PDU in order to generate a negative acknowledgment (NACK) response.

UnrecoverablePduException - Thrown when an unrecoverable PDU error occurs. This indicates a serious error occurred and usually indicates the session should be immediately terminated.

SmppTimeoutException - A timeout occurred while waiting for a response from the remote endpoint. A timeout can either occur with an unresponsive remote endpoint or the bytes were not written in time.

SmppChannelException - Thrown when the underlying socket/channel was unable to write the request.

InterruptedException - The calling thread was interrupted while waiting to acquire a lock or write/read the bytes from the socket/channel.

sendResponsePdu

void sendResponsePdu(PduResponse response)
                     throws RecoverablePduException,
                            UnrecoverablePduException,
                            SmppChannelException,
                            InterruptedException

Main underlying method for sending a response PDU to the remote endpoint. The PDU will be converted into a sequence of bytes by the underlying transcoder. Writes the bytes out to the socket/channel.

Parameters:

response - The response PDU to send

Throws:

RecoverablePduException - Thrown when a recoverable PDU error occurs. A recoverable PDU error includes the partially decoded PDU in order to generate a negative acknowledgment (NACK) response.

UnrecoverablePduException - Thrown when an unrecoverable PDU error occurs. This indicates a serious error occurred and usually indicates the session should be immediately terminated.

SmppChannelException - Thrown when the underlying socket/channel was unable to write the request.

InterruptedException - The calling thread was interrupted while waiting to acquire a lock or write/read the bytes from the socket/channel.