ie.ncl.sms.ucp
Class UCPConnection

java.lang.Object
  ie.ncl.msg.impl.SimpleConnection
      ie.ncl.sms.ucp.UCPConnection

All Implemented Interfaces:

Connection, Receiver, Sender

public class UCPConnection
extends ie.ncl.msg.impl.SimpleConnection
implements Sender, Receiver

This class is used to connect with a UCP compliant Short Message Service Centre or SMSC. A typical UCP compliant SMSC would be one manufactured by CMG.

The UCPConnection class implements Sender and Receiver interface meaning that it can be dynamically loaded using the message Factory class.

IMPORTANT: Unless you are performing some UCP specific operations it is best to use the ie.ncl.msg.Factory class to create instances of the UCPConnection. This allows you to dynamically create transport independent software applications.

The properties used to setup the UCPConnection class are:-

NAME	VALUE	DEFAULT
class	The name of the implementing class - ie.ncl.sms.ucp.UCPConnection	mandatory
host	Host name of the SMSC (string)	mandatory
port	IP port number of the UCP Server (number)	mandatory
sourcePort	IP port number to use for the client side of the socket (number)	optional - defaults to -1, meaning system-assigned
unackedQueueSize	The maximum number of outstanding requests sent to the SMSC without have receive a response for any (number)	optional - defaults to 1 request
reconnectOnDisconnect	Reconnect to the SMSC if the connection is dropped (true or false).	optional - defaults to true
reconnectRetryAttempts	The number of re-connection retry attempts to be performed if a connection is lost (number).	optional - defaults to 60 retries
reconnectTimerSeconds	The number of seconds between re-connection attempts (number of seconds)	optional -defaults to 60 seconds
defaultToGsmAlphabet	The default alphabet encoding is GSM (true/false)	optional - defaults to true
sessionLogin,sessionPassword	Authentication for session management packet. Session management packet is not sent if this is not configured	optional - .
sessionTon,sessionNpi	The is TON, NPI sent in a session management packet.	optional - defaults to 6,5
queryLinkEverySeconds	Query the link every so often to ensure it is up and running (number of seconds)	optional - defaults to 30 seconds
linkAliveIfAnyDataReceived	The link is alive if any data is received within the response timeout of sending a query link operation to the SMSC. If this is false, the query link response must be received within the timeout (true or false)	optional - defaults to true
useThisInternationalPrefix	If this is set to a value then any '+' detected in the destination address will be replaced by this international prefix value and vice versa.	optional - no replacement performed
smscResponseTimeoutSeconds	The response timeout for which a response must be received from the SMSC upon sending a request (number of seconds).	optional - defaults to 60 seconds.
throttleUseconds	A configurable pause between transmitting messages (micro seconds).	optional - defaults to 0 micro seconds.
binary7BitEncoding	When sending messages which have a user-data-header (UDH), and are in the default alphabet (7-bit), do the 7-bit encoding for the SMSC.	defaults to false
notificationAddress	Set the NAdC or notification address of the UCP message.	defaults to not set
notificationPid	Set the default notification PID of a submitted UCP message.	defaults to not set
notificationType	Set the default notification type of a submitted UCP message.	defaults to not set

See Also:

Factory

Field Summary

static java.lang.String	MESSAGE_CLASS_ATTRIBUTE_NAME Used to specify the 'message class' (MCLs) attribute for a message.
static java.lang.String	NOTIFICATION_ADDRESS_NAME Used to specify the 'notification address' (NAdC) attribute for a message.
static java.lang.String	NOTIFICATION_PID_ATTRIBUTE_NAME Used to specify the 'notification PID' (NPID) attribute for a message.
static java.lang.String	NOTIFICATION_TYPE_ATTRIBUTE_NAME Used to specify the 'notification type' (NT) attribute for a message.

Fields inherited from interface ie.ncl.msg.Connection

CONNECTED, NOT_CONNECTED, NOT_USED, RECONNECTING

Constructor Summary

UCPConnection()

Method Summary

void	acknowledge(Message m, boolean success) Acknowledge a received messages.
void	addRequest(ie.ncl.sms.ucp.Request request)
void	addRequest(ie.ncl.sms.ucp.Request request, boolean expedite)
void	close() Connection Interface method.
void	connect() Connect with the service.
void	expediteRequest(ie.ncl.sms.ucp.Request request)
java.lang.String	getHost()
boolean	getLinkAliveIfAnyDataReceived()
java.lang.String	getNotificationAddress()
java.lang.String	getNotificationPid()
java.lang.String	getNotificationType()
int	getPort()
int	getQueryLinkTimer()
boolean	getReconnectOnDisconnect() Reconnect if there is a disconnection.
int	getReconnectRetryAttempts() This is used to specify the maximum number of reconnection retry attempts when a link has gone down or stops responding.
java.lang.String	getSessionLogin()
int	getSessionNpi()
java.lang.String	getSessionPassword()
int	getSessionTon()
int	getSmscResponseTimeout()
int	getSourcePort() The port number used for the client side of the TCP socket.
int	getThrottling()
int	getUnackedQueueSize()
java.lang.String	getUseThisInternationalPrefix()
void	init(java.util.Properties properties) Initialise the object with settings specified in the properties.
boolean	isBinary7BitEncoding() Set for SMSCs which expect binary messages with default (7-bit) alphabet to be 7-bit encoded on the client.
static void	main(java.lang.String[] args) Print version information.
void	receive(ReceiverListener listener) Receive messages asynchronously.
void	send(Message message, SenderListener listener) Send a message asynchronously.
void	setBinary7BitEncoding(boolean binary7BitEncoding) Set for SMSCs which expect binary messages with default (7-bit) alphabet to be 7-bit encoded on the client.
void	setHost(java.lang.String host)
void	setHostPort(java.lang.String host, int port)
void	setLinkAliveIfAnyDataReceived(boolean linkAliveIfAnyDataReceived)
void	setNotificationAddress(java.lang.String notificationAddress)
void	setNotificationPid(java.lang.String notificationPid)
void	setNotificationType(java.lang.String notificationType)
void	setPort(int port)
void	setQueryLinkTimer(int queryLinkTimer)
void	setReceiverListener(ReceiverListener listener) Registers listener with the underlying transport.
void	setReconnectOnDisconnect(boolean yesOrNo) Reconnect if there is a disconnection.
void	setReconnectRetryAttempts(int numberOfTimes) This is used to specify the maximum number of reconnection retry attempts when a link has gone down or stops responding.
void	setSessionLogin(java.lang.String sessionLogin)
void	setSessionNpi(int sessionNpi)
void	setSessionPassword(java.lang.String sessionPassword)
void	setSessionTon(int sessionTon)
void	setSmscResponseTimeout(int usec)
void	setSourcePort(int sourcePort)
void	setThrottling(int throttleUseconds)
void	setUnackedQueueSize(int unackedQueueSize)
void	setUseThisInternationalPrefix(java.lang.String useThisInternationalPrefix)
void	shutdown() Shutdown the connection.

Methods inherited from class ie.ncl.msg.impl.SimpleConnection

connected, getConnectionStatus, getErrorListener, getName, getTypeDefaults, init, mergeDefaultAttributes, putTypeDefaults, setErrorListener, setName

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface ie.ncl.msg.Connection

connected, getConnectionStatus, getTypeDefaults, init, putTypeDefaults, setErrorListener

Field Detail

MESSAGE_CLASS_ATTRIBUTE_NAME

public static final java.lang.String MESSAGE_CLASS_ATTRIBUTE_NAME

Used to specify the 'message class' (MCLs) attribute for a message. This is UCP specific, and the value should be an integer, set using Attributes.put(java.lang.String, int)

See Also:

Constant Field Values

NOTIFICATION_TYPE_ATTRIBUTE_NAME

public static final java.lang.String NOTIFICATION_TYPE_ATTRIBUTE_NAME

Used to specify the 'notification type' (NT) attribute for a message. This is UCP specific, and the value should be an integer, set using Attributes.put(java.lang.String, int)

See Also:

Constant Field Values

NOTIFICATION_PID_ATTRIBUTE_NAME

public static final java.lang.String NOTIFICATION_PID_ATTRIBUTE_NAME

Used to specify the 'notification PID' (NPID) attribute for a message. This is UCP specific, and the value should be a string, set using Attributes.put(java.lang.String, java.lang.String)

See Also:

Constant Field Values

NOTIFICATION_ADDRESS_NAME

public static final java.lang.String NOTIFICATION_ADDRESS_NAME

Used to specify the 'notification address' (NAdC) attribute for a message. This is UCP specific, and the value should be a string, set using Attributes.put(java.lang.String, java.lang.String)

See Also:

Constant Field Values

Constructor Detail

UCPConnection

public UCPConnection()

Method Detail

getNotificationAddress

public java.lang.String getNotificationAddress()

setNotificationAddress

public void setNotificationAddress(java.lang.String notificationAddress)

getNotificationPid

public java.lang.String getNotificationPid()

setNotificationPid

public void setNotificationPid(java.lang.String notificationPid)

getNotificationType

public java.lang.String getNotificationType()

setNotificationType

public void setNotificationType(java.lang.String notificationType)

main

public static void main(java.lang.String[] args)

Print version information.

close

public void close()

Description copied from class: ie.ncl.msg.impl.SimpleConnection

Connection Interface method.

Specified by:

close in interface Connection

Specified by:

close in class ie.ncl.msg.impl.SimpleConnection

shutdown

public void shutdown()

Description copied from interface: Connection

Shutdown the connection. This is used to shutdown a connection ungracefully.

Specified by:

shutdown in interface Connection

acknowledge

public void acknowledge(Message m,
                        boolean success)
                 throws MessageException,
                        ConnectionException

Description copied from interface: Receiver

Acknowledge a received messages. Messages that already have been acknowledged or that require no acknowledgement should be ignored. By default a (receiver) connection will acknowledge messages automatically unless otherwise specified so calls to acknowledge may be unnecessary.

Specified by:

acknowledge in interface Receiver

Throws:

MessageException

ConnectionException

receive

public void receive(ReceiverListener listener)
             throws ConnectionException

Description copied from interface: Receiver

Receive messages asynchronously. The underlying transport should not receive messages until this is setup. Also, the underlying transport should not acknowledge messages until the ReceiverListener returns true or acknowledge is called.

Specified by:

receive in interface Receiver

Throws:

ConnectionException

See Also:

Message

setReceiverListener

public void setReceiverListener(ReceiverListener listener)
                         throws ConnectionException

Description copied from interface: Receiver

Registers listener with the underlying transport. The underlying transport should not receive messages until this is setup. Also, the underlying transport should not acknowledge messages until the ReceiverListener returns true or acknowledge is called.

Specified by:

setReceiverListener in interface Receiver

Throws:

ConnectionException

See Also:

Message

connect

public void connect()
             throws ConnectionException

Description copied from interface: Connection

Connect with the service. Until connect is called, no messages can be sent/received.

Specified by:

connect in interface Connection

Throws:

ConnectionException

addRequest

public void addRequest(ie.ncl.sms.ucp.Request request,
                       boolean expedite)

addRequest

public void addRequest(ie.ncl.sms.ucp.Request request)

expediteRequest

public void expediteRequest(ie.ncl.sms.ucp.Request request)

send

public void send(Message message,
                 SenderListener listener)
          throws MessageException,
                 ConnectionException

Description copied from interface: Sender

Send a message asynchronously. Once the message is processed (successfully sent or not) the listener will be called to notify the application of the outcome. See SenderListener for more detail.

Specified by:

send in interface Sender

Throws:

MessageException

ConnectionException

See Also:

SenderListener, Message

init

public void init(java.util.Properties properties)
          throws ConnectionException

Description copied from interface: Connection

Initialise the object with settings specified in the properties. The properties will be implementation specific.

Specified by:

init in interface Connection

Throws:

ConnectionException

isBinary7BitEncoding

public boolean isBinary7BitEncoding()

Set for SMSCs which expect binary messages with default (7-bit) alphabet to be 7-bit encoded on the client. true by default.

setBinary7BitEncoding

public void setBinary7BitEncoding(boolean binary7BitEncoding)

Set for SMSCs which expect binary messages with default (7-bit) alphabet to be 7-bit encoded on the client. true by default.

setReconnectRetryAttempts

public void setReconnectRetryAttempts(int numberOfTimes)

This is used to specify the maximum number of reconnection retry attempts when a link has gone down or stops responding. This is only relevant if reconnectOnDisconnect is turned on.

See Also:

setReconnectOnDisconnect(boolean), getReconnectOnDisconnect()

getReconnectRetryAttempts

public int getReconnectRetryAttempts()

This is used to specify the maximum number of reconnection retry attempts when a link has gone down or stops responding. This is only relevant if reconnectOnDisconnect is turned on.

See Also:

setReconnectOnDisconnect(boolean), getReconnectOnDisconnect()

getReconnectOnDisconnect

public boolean getReconnectOnDisconnect()

Reconnect if there is a disconnection.

See Also:

setReconnectRetryAttempts(int), getReconnectRetryAttempts()

setReconnectOnDisconnect

public void setReconnectOnDisconnect(boolean yesOrNo)

Reconnect if there is a disconnection.

See Also:

setReconnectRetryAttempts(int), getReconnectRetryAttempts()

setSmscResponseTimeout

public void setSmscResponseTimeout(int usec)

getSmscResponseTimeout

public int getSmscResponseTimeout()

getLinkAliveIfAnyDataReceived

public boolean getLinkAliveIfAnyDataReceived()

setLinkAliveIfAnyDataReceived

public void setLinkAliveIfAnyDataReceived(boolean linkAliveIfAnyDataReceived)

getQueryLinkTimer

public int getQueryLinkTimer()

setQueryLinkTimer

public void setQueryLinkTimer(int queryLinkTimer)

getSessionLogin

public java.lang.String getSessionLogin()

setSessionLogin

public void setSessionLogin(java.lang.String sessionLogin)

getHost

public java.lang.String getHost()

setHost

public void setHost(java.lang.String host)

getPort

public int getPort()

setPort

public void setPort(int port)

getUnackedQueueSize

public int getUnackedQueueSize()

setUnackedQueueSize

public void setUnackedQueueSize(int unackedQueueSize)

setHostPort

public void setHostPort(java.lang.String host,
                        int port)

getSourcePort

public int getSourcePort()

The port number used for the client side of the TCP socket.

Returns:

A value of -1 indicates that the port number is system assigned

setSourcePort

public void setSourcePort(int sourcePort)

getSessionPassword

public java.lang.String getSessionPassword()

setSessionPassword

public void setSessionPassword(java.lang.String sessionPassword)

getSessionTon

public int getSessionTon()

setSessionTon

public void setSessionTon(int sessionTon)

getSessionNpi

public int getSessionNpi()

setSessionNpi

public void setSessionNpi(int sessionNpi)

getUseThisInternationalPrefix

public java.lang.String getUseThisInternationalPrefix()

setUseThisInternationalPrefix

public void setUseThisInternationalPrefix(java.lang.String useThisInternationalPrefix)

getThrottling

public int getThrottling()

setThrottling

public void setThrottling(int throttleUseconds)