com.objectxp.msg
Interface SmsService

All Known Subinterfaces:

WindowingService

All Known Implementing Classes:

Cimd2SmsService, GsmSmsService, SmppSmsService, TapSmsService, UcpSmsService

public interface SmsService

This interface defines the methods to send and receive GSM Short Messages (SMS).

Field Summary

static java.lang.String

VERSION Constant containing the module version.

Method Summary

void	addMessageEventListener(MessageEventListener listener) Register a Message Event listener with this Service.
void	cancel(Message msg) Cancel a previously submitted message.
void	connect() Connect to the GSM device or SMS gateway.
void	destroy() Release allocated resources and destroy this service.
void	disconnect() Disconnect from the GSM device or SMS gateway.
int	getKeepAliveInterval() Get the currently set keepalive interval.
long	getLastIsAliveTime() Returns the time of the last successful isAlive() invocation.
java.util.Properties	getProperties() Get the properties passed to the service.
java.lang.String	getServiceName() Returns the name of the service.
boolean	hasCapability(Capability capability) Determine if a SMS Service has a specific capability.
void	init() Initialize this service.
void	init(java.io.File file) Initialize this Service with properties defined in the given file.
void	init(java.util.Properties props) Initialize this service.
boolean	isAlive() Returns true if the connection to the GSM device or SMSC is alive, false otherwise.
boolean	isConnected() Returns true if the Service is currently connected to the GSM device or SMS gateway, false otherwise.
boolean	isInitialized() Returns true if the Service has been sucessfuly initalized, false otherwise.
boolean	isKeepAliveActive() Returns true, if jSMS is keeping the connection to the GSM device or SMSC alive, false otherwise.
boolean	isReceiving() Returns true if the Service is currently receiving incoming short messages, false otherwise.
void	query(Message msg) Query the status of a previously submitted message.
void	removeMessageEventListener(MessageEventListener listener) Remove a Listener from the List of Message Event listeners.
void	replace(Message oldMessage, Message newMessage) Replace a previously submitted message.
void	sendMessage(Message message) Send a message to a GSM recipient.
void	setKeepAliveInterval(int interval) Set the keep-alive interval of this Service.
void	startReceiving() Start receiving Messages.
void	stopReceiving() Stop receiving Messages.
boolean	supportDeleteMessage() Deprecated. since jSMS 2.1.8.
boolean	supportReadMessage() Deprecated. since jSMS 2.1.8, use hasCapability(Capability.RECEIVE) instead.

Field Detail

VERSION

static final java.lang.String VERSION

Constant containing the module version.

See Also:

Constant Field Values

Method Detail

addMessageEventListener

void addMessageEventListener(MessageEventListener listener)

Register a Message Event listener with this Service. Registered MessageEventListener's will receive events broadcasted by the service.

Parameters:

listener - an Object implementing the MessageEventListener interface.

See Also:

MessageEvent, MessageEventListener

removeMessageEventListener

void removeMessageEventListener(MessageEventListener listener)

Remove a Listener from the List of Message Event listeners. If you remove the last listener and the service is currently receiving messages, this method will automatically stop receiving (by calling stopReceiving()).

Parameters:

listener - the listener to remove

sendMessage

void sendMessage(Message message)
                 throws MessageException

Send a message to a GSM recipient. The recipient must be a valid GSM phone number. The message will be truncated to 160 characters.

If the message to send is not a binary or unicode message, the service will convert the message to the default GSM character set using GsmHelper.iso2gsm().

This method will broadcast a MessageEvent to all registered MessageEventListener's. In case of success a MessageEvent of type MESSAGE_SENT is broadcasted. Otherwise, the MessageEvent is of type MESSAGE_NOT_SENT.

Parameters:

message - the message to send.

Throws:

MessageException - if the message could not be sent.

supportReadMessage

boolean supportReadMessage()

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

This method returns true if the Service is able to receive messages from the SMS device or gateway, false otherwise.

supportDeleteMessage

boolean supportDeleteMessage()

Deprecated. since jSMS 2.1.8.

This method returns true if the Service allows messages to be deleted from the device or gateway, false otherwise.

connect

void connect()
             throws MessageException

Connect to the GSM device or SMS gateway. Before sending and receiving messages, this method must be called. When the connection is established, the Service broadcasts a MessageEvent.DEVICE_READY event to all registered MessageEventListeners.

Throws:

MessageException

See Also:

MessageEvent, MessageEventListener

disconnect

void disconnect()
                throws MessageException

Disconnect from the GSM device or SMS gateway. Call this method after sending/receiving messages. After the connection has been disconnected, jSMS broadcasts a MessageEvent.DEVICE_NOT_READY even to all registered MessageEventListeners.

Throws:

MessageException

See Also:

MessageEvent, MessageEventListener

isConnected

boolean isConnected()

Returns true if the Service is currently connected to the GSM device or SMS gateway, false otherwise.

isReceiving

boolean isReceiving()

Returns true if the Service is currently receiving incoming short messages, false otherwise.

See Also:

startReceiving(), stopReceiving()

isInitialized

boolean isInitialized()

Returns true if the Service has been sucessfuly initalized, false otherwise. Before using the Service, it must be initialized!

See Also:

init(), init(Properties), init(File)

isAlive

boolean isAlive()

Returns true if the connection to the GSM device or SMSC is alive, false otherwise. If the SmsService is not connected to the GSM device or SMSC, this method immediately returns false. If connected, isAlive() verifies that the connection is still alive by sending a Service specific command to the GSM device / SMSC and examining the response (if any).

setKeepAliveInterval

void setKeepAliveInterval(int interval)

Set the keep-alive interval of this Service. If the interval is > 0, jSMS tries to keep the connection to the GSM device or SMSC alive by repeatedly calling isAlive(). If the connection is down, the service broadcasts a MessageEvent of type DEVICE_NOT_RESPONDING to all registered MessageEvent listeners. The user of the SmsService may then decide to reconnect to the SMSC by calling disconnect() followed by connect().

Parameters:

interval - the keepalive interval in seconds

See Also:

MessageEvent, addMessageEventListener(MessageEventListener)

isKeepAliveActive

boolean isKeepAliveActive()

Returns true, if jSMS is keeping the connection to the GSM device or SMSC alive, false otherwise. If the SmsService is not connect()ed to the SMSC this method always returns false.

See Also:

connect(), setKeepAliveInterval(int)

getKeepAliveInterval

int getKeepAliveInterval()

Get the currently set keepalive interval. The interval can be specified in your jSMS initialization properties (sms.keepalive.interval). At runtime, the interval can be changed by calling setKeepAliveInterval(int).

Returns:

the keepalive interval in seconds

getLastIsAliveTime

long getLastIsAliveTime()

Returns the time of the last successful isAlive() invocation.

Returns:

the difference, measured in milliseconds, between the last successful isAlive() call and midnight, January 1, 1970 UTC. If isAlive() has never been called or successful, this method returns 0.

init

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

Initialize this service. One of the init() methods has to be called before the SmsService may be used.

Throws:

MessageException

See Also:

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

init

void init()
          throws MessageException

Initialize this service. One of the init() methods has to be called before the SmsService may be used.

Throws:

MessageException

See Also:

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

init

void init(java.io.File file)
          throws java.io.IOException,
                 MessageException

Initialize this Service with properties defined in the given file. One of the init() methods has to be called before the SmsService may be used.

Parameters:

file - the file containing jSMS init properties

Throws:

java.io.IOException - if the passed file could not be loaded

MessageException - if the Service could not be initialized properly

See Also:

init(), init(Properties)

destroy

void destroy()

Release allocated resources and destroy this service. The service may not be re-used after calling destroy(). This method has to be invoked when the SMS Service will not be used anymore.

startReceiving

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

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.

Throws:

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

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

See Also:

addMessageEventListener(MessageEventListener)

stopReceiving

void stopReceiving()

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.

getProperties

java.util.Properties getProperties()

Get the properties passed to the service.

See Also:

init(Properties)

getServiceName

java.lang.String getServiceName()

Returns the name of the service.

hasCapability

boolean hasCapability(Capability capability)

Determine if a SMS Service has a specific capability.

Parameters:

capability - one of the Constants in the Capability class.

Returns:

true if the service provides the capability.

cancel

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

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.

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.

Since:

jSMS 2.1.8

replace

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

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

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.

Since:

jSMS 2.1.8

query

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

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

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.

Since:

jSMS 2.1.8