com.objectxp.msg
Class UcpSmsService

java.lang.Object
  AbstractSmsService
      com.objectxp.msg.UcpSmsService

All Implemented Interfaces:

ManualAck, SmsService, WindowingService

public class UcpSmsService
extends AbstractSmsService
implements SmsService, ManualAck, WindowingService

This class may be used to send (and receive) Short Messages (SMS) to a mobile recipient using UCP (Universal Computer Protocol).

The message will be sent through a SMS Center (SMSC) reachable by either a modem/ISDN connection or TCP/IP.

Receiving Short messages via UCP is only supported for TCP/IP connections. UCP over TCP/IP requires a "large volume account" at the SMSC of your Mobile Network Provider. Contact your local provider for further information.

A special feature of UCP (only Operation 51) is, that message originator may be an alpha numerical String with maximal length of 16 characters.

For more information about the init-Properties supported by UcpSmsService, have a look at this table.

See Also:

UcpMessage

Field Summary

static java.lang.String	CFG_BPS CFG_BPS is the name of the constant holding the value "ucp.port.bps".
static java.lang.String	CFG_CONNECTOR CFG_CONNECTOR is the name of the constant holding the value "ucp.connector".
static java.lang.String	CFG_CONNECTOR_TIMEOUT CFG_CONNECTOR_TIMEOUT is the name of the constant holding the value "ucp.connector.timeout".
static java.lang.String	CFG_DATABITS CFG_DATABITS is the name of the constant holding the value "ucp.port.databits".
static java.lang.String	CFG_FLOWCTRL CFG_FLOWCTRL is the name of the constant holding the value "ucp.port.flowcontrol".
static java.lang.String	CFG_INITSTRING CFG_INITSTRING is the name of the constant holding the value "ucp.initstring".
static java.lang.String	CFG_INTPREFIX CFG_INTPREFIX is the name of the constant holding the value "ucp.intprefix".
static java.lang.String	CFG_LVA CFG_LVA is the name of the constant holding the value "ucp.lva".
static java.lang.String	CFG_OPID CFG_OPID is the name of the constant holding the value "ucp.opid".
static java.lang.String	CFG_PARITY CFG_PARITY is the name of the constant holding the value "ucp.port.parity".
static java.lang.String	CFG_PASSWORD CFG_PASSWORD is the name of the constant holding the value "ucp.password".
static java.lang.String	CFG_PORT CFG_PORT is the name of the constant holding the value "ucp.port.name".
static java.lang.String	CFG_SENDER CFG_SENDER is the name of the constant holding the value "ucp.sender".
static java.lang.String	CFG_SHORTID CFG_SHORTID is the name of the constant holding the value "ucp.shortid".
static java.lang.String	CFG_SMSC CFG_SMSC is the name of the constant holding the value "ucp.smsc.number".
static java.lang.String	CFG_STOPBITS CFG_STOPBITS is the name of the constant holding the value "ucp.port.stopbits".
static java.lang.String	CFG_SUBMIT_OPERATION CFG_SUBMIT_SHORT_MESSAGE_OPERATION is the name of the constant holding the value "ucp.submit.operation".
static java.lang.String	CFG_TCP_LOCALADDR CFG_TCP_LOCALADDR is the name of the constant holding the value "ucp.tcp.localaddr".
static java.lang.String	CFG_TCP_LOCALPORT CFG_TCP_LOCALPORT is the name of the constant holding the value "ucp.tcp.localport".
static java.lang.String	CFG_TCP_RCV_HOST CFG_TCP_RCV_HOST is the name of the constant holding the value "ucp.tcp.receive.host".
static java.lang.String	CFG_TCP_RCV_PORT CFG_TCP_RCV_PORT is the name of the constant holding the value "ucp.tcp.receive.port".
static java.lang.String	CFG_TCP_SEND_HOST CFG_TCP_SEND_HOST is the name of the constant holding the value "ucp.tcp.send.host".
static java.lang.String	CFG_TCP_SEND_PORT CFG_TCP_SEND_PORT is the name of the constant holding the value "ucp.tcp.send.port".
static java.lang.String	CFG_WINDOW_SIZE CFG_WINDOW_SIZE is the name of the constant holding the value "ucp.window.size".
static java.lang.String	CFG_XSER_NODCS CFG_XSER_NODCS is the name of the constant holding the value "ucp.xser.nodcs".
static java.lang.String	CONNECTOR_SERIAL CONNECTOR_SERIAL is the name of the constant holding the value "SERIAL".
static java.lang.String	CONNECTOR_TCP CONNECTOR_TCP is the name of the constant holding the value "TCP".

Constructor Summary

UcpSmsService()

Method Summary

void	acknowledge(Message msg) Accept a incoming message.
void	acknowledge(Message msg, java.lang.Object status) Accept/reject a incoming message.
void	cancel(Message msg) Cancel a previously submitted message.
void	cancelMessage(Message message) Cancels (deletes) the buffered message with corresponding recipient address, sender address and message ID.
void	cancelMessages(Message[] messages) Cancels (deletes) the buffered messages with corresponding recipient address, sender address and message ID.
void	connect() Connects the UCP SMS Service to the SMSC
void	delete(Message msg)
void	destroy() Destroys the UCP SMS Service
void	disableManualAck() Disable manual acknowledgement.
void	disconnect() Disconnects the UCP SMS Service from the SMSC
void	enableManualAck() Enable manual acknowledgement.
int	getNumberOfPendingMessages() Returns the number of pending (unprocessed messages).
java.lang.String	getServiceName() Returns the name of the service.
int	getWindowSize() Returns the current window size or 1 if windowing is disabled.
boolean	hasCapability(Capability capability) Determine if a SMS Service has a specific capability.
void	init(java.util.Properties props) Initialize the UCP service.
void	inquiryMessage(Message message) Inquiry about the state of a buffered Message.
boolean	isManualAckEnabled() Check if manual acknowledgement is enabled/disabled.
void	modifyMessage(Message message) Deprecated. since jSMS 2.1.8, use replace(Message, Message) instead.
void	query(Message msg) Query the status of a previously submitted message.
void	replace(Message oldMessage, Message newMessage) Replace a previously submitted message.
void	sendMessage(Message message) Send a message to a GSM recipient using a UCP gateway.
void	setWindowSize(int windowSize) Set the window size for this service.
void	startReceiving() Start receiving Messages.
void	stopReceiving() Stop receiving Messages.
boolean	supportReadMessage() Deprecated. since jSMS 2.1.8, use hasCapability(Capability.RECEIVE) instead.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.objectxp.msg.SmsService

addMessageEventListener, getKeepAliveInterval, getLastIsAliveTime, getProperties, init, init, isAlive, isConnected, isInitialized, isKeepAliveActive, isReceiving, removeMessageEventListener, setKeepAliveInterval, supportDeleteMessage

Field Detail

CFG_SMSC

public static final java.lang.String CFG_SMSC

CFG_SMSC is the name of the constant holding the value "ucp.smsc.number".

See Also:

Constant Field Values

CFG_PORT

public static final java.lang.String CFG_PORT

CFG_PORT is the name of the constant holding the value "ucp.port.name".

See Also:

Constant Field Values

CFG_BPS

public static final java.lang.String CFG_BPS

CFG_BPS is the name of the constant holding the value "ucp.port.bps".

See Also:

Constant Field Values

CFG_DATABITS

public static final java.lang.String CFG_DATABITS

CFG_DATABITS is the name of the constant holding the value "ucp.port.databits".

See Also:

Constant Field Values

CFG_PARITY

public static final java.lang.String CFG_PARITY

CFG_PARITY is the name of the constant holding the value "ucp.port.parity".

See Also:

Constant Field Values

CFG_STOPBITS

public static final java.lang.String CFG_STOPBITS

CFG_STOPBITS is the name of the constant holding the value "ucp.port.stopbits".

See Also:

Constant Field Values

CFG_FLOWCTRL

public static final java.lang.String CFG_FLOWCTRL

CFG_FLOWCTRL is the name of the constant holding the value "ucp.port.flowcontrol".

See Also:

Constant Field Values

CFG_SENDER

public static final java.lang.String CFG_SENDER

CFG_SENDER is the name of the constant holding the value "ucp.sender".

See Also:

Constant Field Values

CFG_INTPREFIX

public static final java.lang.String CFG_INTPREFIX

CFG_INTPREFIX is the name of the constant holding the value "ucp.intprefix".

See Also:

Constant Field Values

CFG_CONNECTOR

public static final java.lang.String CFG_CONNECTOR

CFG_CONNECTOR is the name of the constant holding the value "ucp.connector".

See Also:

Constant Field Values

CFG_CONNECTOR_TIMEOUT

public static final java.lang.String CFG_CONNECTOR_TIMEOUT

CFG_CONNECTOR_TIMEOUT is the name of the constant holding the value "ucp.connector.timeout".

See Also:

Constant Field Values

CONNECTOR_TCP

public static final java.lang.String CONNECTOR_TCP

CONNECTOR_TCP is the name of the constant holding the value "TCP".

See Also:

Constant Field Values

CONNECTOR_SERIAL

public static final java.lang.String CONNECTOR_SERIAL

CONNECTOR_SERIAL is the name of the constant holding the value "SERIAL".

See Also:

Constant Field Values

CFG_TCP_SEND_HOST

public static final java.lang.String CFG_TCP_SEND_HOST

CFG_TCP_SEND_HOST is the name of the constant holding the value "ucp.tcp.send.host".

See Also:

Constant Field Values

CFG_TCP_SEND_PORT

public static final java.lang.String CFG_TCP_SEND_PORT

CFG_TCP_SEND_PORT is the name of the constant holding the value "ucp.tcp.send.port".

See Also:

Constant Field Values

CFG_TCP_RCV_HOST

public static final java.lang.String CFG_TCP_RCV_HOST

CFG_TCP_RCV_HOST is the name of the constant holding the value "ucp.tcp.receive.host".

See Also:

Constant Field Values

CFG_TCP_RCV_PORT

public static final java.lang.String CFG_TCP_RCV_PORT

CFG_TCP_RCV_PORT is the name of the constant holding the value "ucp.tcp.receive.port".

See Also:

Constant Field Values

CFG_PASSWORD

public static final java.lang.String CFG_PASSWORD

CFG_PASSWORD is the name of the constant holding the value "ucp.password".

See Also:

Constant Field Values

CFG_SHORTID

public static final java.lang.String CFG_SHORTID

CFG_SHORTID is the name of the constant holding the value "ucp.shortid".

See Also:

Constant Field Values

CFG_OPID

public static final java.lang.String CFG_OPID

CFG_OPID is the name of the constant holding the value "ucp.opid".

See Also:

Constant Field Values

CFG_TCP_LOCALADDR

public static final java.lang.String CFG_TCP_LOCALADDR

CFG_TCP_LOCALADDR is the name of the constant holding the value "ucp.tcp.localaddr".

See Also:

Constant Field Values

CFG_TCP_LOCALPORT

public static final java.lang.String CFG_TCP_LOCALPORT

CFG_TCP_LOCALPORT is the name of the constant holding the value "ucp.tcp.localport".

See Also:

Constant Field Values

CFG_LVA

public static final java.lang.String CFG_LVA

CFG_LVA is the name of the constant holding the value "ucp.lva".

See Also:

Constant Field Values

CFG_WINDOW_SIZE

public static final java.lang.String CFG_WINDOW_SIZE

CFG_WINDOW_SIZE is the name of the constant holding the value "ucp.window.size".

See Also:

Constant Field Values

CFG_SUBMIT_OPERATION

public static final java.lang.String CFG_SUBMIT_OPERATION

CFG_SUBMIT_SHORT_MESSAGE_OPERATION is the name of the constant holding the value "ucp.submit.operation".

See Also:

Constant Field Values

CFG_INITSTRING

public static final java.lang.String CFG_INITSTRING

CFG_INITSTRING is the name of the constant holding the value "ucp.initstring".

See Also:

Constant Field Values

CFG_XSER_NODCS

public static final java.lang.String CFG_XSER_NODCS

CFG_XSER_NODCS is the name of the constant holding the value "ucp.xser.nodcs".

See Also:

Constant Field Values

Constructor Detail

UcpSmsService

public UcpSmsService()

Method Detail

sendMessage

public void sendMessage(Message message)
                 throws MessageException

Send a message to a GSM recipient using a UCP gateway. The recipient must be a valid GSM phone number. The message will be truncated to 160 characters. Make sure that connect() has been invoked before calling this method.

Specified by:

sendMessage in interface SmsService

Parameters:

message - the message to send.

Throws:

MessageException - if the message could not be sent.

See Also:

UcpMessage

cancelMessage

public void cancelMessage(Message message)
                   throws MessageException

Cancels (deletes) the buffered message with corresponding recipient address, sender address and message ID. As result a StatusReportMessage should be received.

Parameters:

message - the message to cancel

Throws:

MessageException - on failure

cancelMessages

public void cancelMessages(Message[] messages)
                    throws MessageException

Cancels (deletes) the buffered messages with corresponding recipient address, sender address and message ID. In UCP all messages to cancel must have the same recipient and sender address. As result a StatusReportMessage should be received.

Parameters:

messages - to cancel

Throws:

MessageException - on failure

inquiryMessage

public void inquiryMessage(Message message)
                    throws MessageException

Inquiry about the state of a buffered Message. As result a StatusReportMessage should be received.

Parameters:

message - to inquiry

Throws:

MessageException - on failure

modifyMessage

public void modifyMessage(Message message)
                   throws MessageException

Deprecated. since jSMS 2.1.8, use replace(Message, Message) instead.

Modifies a buffered Message.

Parameters:

message - to modify

Throws:

MessageException - on failure

getNumberOfPendingMessages

public int getNumberOfPendingMessages()

Description copied from interface: WindowingService

Returns the number of pending (unprocessed messages). You may use this method to check if all outgoing messages have been acknowledged by the SMSC prior to calling disconnect() on the SmsService.

Specified by:

getNumberOfPendingMessages in interface WindowingService

getWindowSize

public int getWindowSize()

Description copied from interface: WindowingService

Returns the current window size or 1 if windowing is disabled.

Specified by:

getWindowSize in interface WindowingService

setWindowSize

public void setWindowSize(int windowSize)

Description copied from interface: WindowingService

Set the window size for this service. To disable windowing, set the window size to 1. The window size can only be changed if the SmsService is not currently connected to the SMSC.

Specified by:

setWindowSize in interface WindowingService

Parameters:

windowSize - the window size

init

public void init(java.util.Properties props)
          throws MessageException

Initialize the UCP service. This method has to be called before the UcpSmsService may be used. The Properties object passed to this method may contain the following configuration values:

key	Allowed values
ucp.connector	Type of SMSC connection ("SERIAL","TCP")
ucp.connector.timeout	Timeout (in millis) for a request to the SMSC. (2000, 5000)
ucp.sender	Default sender address (GSM phone number)
ucp.intprefix	Prefix for international numbers. Defaults to 00. If a recipient number contains a leading '+' character (e.g. "+41..."), the '+' character will be replaced by the international number prefix (e.g. "+41..." becomes "0041...").
ucp.submit.operation	UCP operation for submitting a message - 51: UCP51 (default) - 30: UCP30, when UCP51 is not supported by SMSC - 01: UCP01, when UCP30 is not supported by SMSC
ucp.license.user	License key user name
ucp.license.company	License key company name
ucp.license.version	jSMS version
ucp.license.sig	The license key itself
ucp.smsc.number	Phone number of the UCP gateway
ucp.port.name	Name of the serial port to use (e.g. "COM1")
ucp.port.bps	Port speed (e.g. 9600, 19200)
ucp.port.databits	Number of data bits ("7" or "8")
ucp.port.parity	Parity ("ODD","EVEN","NONE")
ucp.port.stopbits	Number of stop bits ("1","2","1.5")
ucp.port.ucp.port.flowcontrol	Flow control ("RTSCTS", "XONXOFF","NONE")
ucp.initstring	Init String for serial connections. Defaults to "ATZ\nATE0Q0V1\n"
ucp.tcp.localaddr	Local address (interface) to bind. Example: "192.168.1.1"
ucp.tcp.localport	Local port to bind
ucp.tcp.send.host	IP address of the SMSC for sending messages
ucp.tcp.send.port	IP port number of the SMSC for sending messages
ucp.tcp.receive.host	IP address of the SMSC for receiving messages. ONLY when it is different from the sending host.
ucp.tcp.receive.port	IP port number of the SMSC for receiving messages
ucp.shortid	Login (Short ID)
ucp.password	Password
ucp.lva	Large Volume Account available ("true", "false")
ucp.window.size	Windowing size to use. (Defaults to 1 (Windowing disabled))
ucp.xser.nodcs	If "true", jSMS will not encode the Data Coding Scheme (DCS) as a XSer field for outgoing short messages (Defaults to false

• Optional keys are printed in italics
• Default values are printed bold
• Keys used for SERIAL connections are printed in blue
• Keys used for TCP connections are printed in green

Specified by:

init in interface SmsService

Throws:

MessageException

See Also:

SmsService.init(), SmsService.init(java.io.File)

destroy

public void destroy()

Destroys the UCP SMS Service

Specified by:

destroy in interface SmsService

connect

public void connect()
             throws MessageException

Connects the UCP SMS Service to the SMSC

Specified by:

connect in interface SmsService

Throws:

MessageException

See Also:

MessageEvent, MessageEventListener

disconnect

public void disconnect()
                throws MessageException

Disconnects the UCP SMS Service from the SMSC

Specified by:

disconnect in interface SmsService

Throws:

MessageException

See Also:

MessageEvent, MessageEventListener

startReceiving

public void startReceiving()
                    throws java.lang.IllegalStateException,
                           java.io.IOException

Description copied from interface: SmsService

Start receiving Messages. The Service has to be initialized and must be connected to the SMS gateway/device. Furthermore, you have to register at least one MessageEventListener with the Service. After receiving has started, the service will broadcast a MessageEvent of type MessageEvent.RECEIVING_STARTED to all registered MessageEvent listeners.

Specified by:

startReceiving in interface SmsService

Throws:

java.lang.IllegalStateException - if the service isn't initialized and in connected state or there are no registered Message Event Listeners.

java.io.IOException - if the communication with the SMS gateway/device fails

See Also:

SmsService.addMessageEventListener(MessageEventListener)

stopReceiving

public void stopReceiving()

Description copied from interface: SmsService

Stop receiving Messages. If the service isn't currently receiving messages, this method will return immediately. After receiving has stopped, the service will broadcast a MessageEvent of type MessageEvent.RECEIVING_STOPPED to all registered MessageEvent listeners.

Specified by:

stopReceiving in interface SmsService

supportReadMessage

public boolean supportReadMessage()

Deprecated. since jSMS 2.1.8, use hasCapability(Capability.RECEIVE) instead.

Check if the service supports receiving messages. For UCP large accounts, this method returns true, otherwise false.

Specified by:

supportReadMessage in interface SmsService

getServiceName

public final java.lang.String getServiceName()

Description copied from interface: SmsService

Returns the name of the service.

Specified by:

getServiceName in interface SmsService

acknowledge

public void acknowledge(Message msg)
                 throws java.lang.IllegalArgumentException,
                        java.lang.IllegalStateException,
                        java.io.IOException

Description copied from interface: ManualAck

Accept a incoming message. The SmsService acknowledges the reception of the message to the Short Message Center (SMSC).

Specified by:

acknowledge in interface ManualAck

Parameters:

msg - the Message to accept

Throws:

java.lang.IllegalArgumentException - if the Message is null or not a incoming message, or if the message has been received by another SmsService.

java.lang.IllegalStateException - if the Service is not initialized or not connected to the SMSC.

IOException - if the communication with the SMSC fails.

acknowledge

public void acknowledge(Message msg,
                        java.lang.Object status)
                 throws java.lang.IllegalArgumentException,
                        java.lang.IllegalStateException,
                        java.io.IOException

Accept/reject a incoming message. The status parameter can be used to pass a java.lang.Boolean object signaling sucess (Boolean.TRUE) or failure (Boolean.FALSE).

Specified by:

acknowledge in interface ManualAck

Parameters:

msg - the Message to acknowledge

status - a Boolean or null to accept the message.

Throws:

java.lang.IllegalArgumentException - if the Message is null or not a incoming message, or if the message has been received by another SmsService.

java.lang.IllegalArgumentException - if the status parameter is not an instance of java.lang.Boolean

java.lang.IllegalStateException - if the Service is not initialized or not connected to the SMSC.

java.io.IOException - if the communication with the SMSC fails.

Since:

jSMS 1.8.4

enableManualAck

public void enableManualAck()

Description copied from interface: ManualAck

Enable manual acknowledgement. Incoming messages have to be acknowledged by calling ManualAck.acknowledge(Message).

Specified by:

enableManualAck in interface ManualAck

disableManualAck

public void disableManualAck()

Description copied from interface: ManualAck

Disable manual acknowledgement. Incoming messages will automatically be acknowledged by the SmsService upon reception of the message.

Specified by:

disableManualAck in interface ManualAck

isManualAckEnabled

public boolean isManualAckEnabled()

Description copied from interface: ManualAck

Check if manual acknowledgement is enabled/disabled.

Specified by:

isManualAckEnabled in interface ManualAck

hasCapability

public boolean hasCapability(Capability capability)

Determine if a SMS Service has a specific capability.
The supported capabilities are

• Capability.SEND
• Capability.RECEIVE - only for UCP large accounts
• Capability.CANCEL - only for UCP-SMSCs that support operation 56, what should be the case when submitting operation is 51 (see init(Properties) with ucp.submit.operation = 51)
• Capability.QUERY - only for UCP-SMSCs that support operation 55, what should be the case when submitting operation is 51 (see init(Properties) with ucp.submit.operation = 51)

Specified by:

hasCapability in interface SmsService

Parameters:

capability - one of the Constants in the Capability class.

Returns:

true if the service provides the capability.

cancel

public void cancel(Message msg)
            throws java.lang.UnsupportedOperationException,
                   java.lang.IllegalStateException,
                   java.lang.IllegalArgumentException,
                   MessageException

Description copied from interface: SmsService

Cancel a previously submitted message. The message can only be cancelled if it has not yet been delivered to the recipient. For messages requesting a status report, a MessageEvent of type STATUS_RECEIVED will be generated upon cancellation of the message.

Specified by:

cancel in interface SmsService

Parameters:

msg - The previously sent message

Throws:

java.lang.UnsupportedOperationException - if the service does not support canceling messages.

java.lang.IllegalStateException - if the service is not initialized or not connected to the SMSC.

java.lang.IllegalArgumentException - if the message is null or doesn't contain the information required for cancelling the message (e.g. missing message ID).

MessageException - if cancellation failed.

delete

public void delete(Message msg)
            throws java.lang.UnsupportedOperationException,
                   java.lang.IllegalStateException,
                   java.lang.IllegalArgumentException,
                   MessageException

Throws:

java.lang.UnsupportedOperationException

java.lang.IllegalStateException

java.lang.IllegalArgumentException

MessageException

query

public void query(Message msg)
           throws java.lang.UnsupportedOperationException,
                  java.lang.IllegalStateException,
                  java.lang.IllegalArgumentException,
                  MessageException

Description copied from interface: SmsService

Query the status of a previously submitted message. The status of the message will be delivered asynchronously using a MessageEvent of type STATUS_RECEIVED.

Specified by:

query in interface SmsService

Parameters:

msg - the previously submitted message.

Throws:

java.lang.UnsupportedOperationException - if the service does not support canceling messages.

java.lang.IllegalStateException - if the service is not initialized or not connected to the SMSC.

java.lang.IllegalArgumentException - if the message is null or doesn't contain the information required for querying the message status (e.g. missing message ID).

MessageException - if querying the status failed.

replace

public void replace(Message oldMessage,
                    Message newMessage)
             throws java.lang.UnsupportedOperationException,
                    java.lang.IllegalStateException,
                    java.lang.IllegalArgumentException,
                    MessageException

Description copied from interface: SmsService

Replace a previously submitted message. The message can only be replaced if it has not yet been delivered to the recipient.

Specified by:

replace in interface SmsService

Parameters:

oldMessage - the previously sent message to replace.

newMessage - the replacement message.

Throws:

java.lang.UnsupportedOperationException - if the service does not support canceling messages.

java.lang.IllegalStateException - if the service is not initialized or not connected to the SMSC.

java.lang.IllegalArgumentException - if the message is null or doesn't contain the information required for replacing the message (e.g. missing message ID).

MessageException - if replacement failed.