com.objectxp.msg
Class MultiPartReceiver

java.lang.Object
  com.objectxp.msg.MultiPartReceiver

All Implemented Interfaces:

java.util.EventListener, MessageEventListener

public class MultiPartReceiver

extends java.lang.Object

implements MessageEventListener

This class can be used to receive concatenated SMS (SMS that carry more than 140 octets / 160 characters and therefore are fragmented in multiple short messages). The MultiPartReceiver will assemble the parts that form a concatenated message into a single SmsMessage.

Additionally, the MultiPartReceiver analyzes incoming SMSes and transforms them into the corresponding SmsMessage subclass, e.g. an incoming Nokia Ringtone will be converted to a jSMS Ringtone.

The MultiPartReceiver can be used as a proxy for an existing MessageEventListener. Instead of directly registering your Event Listener to a SmsService, register this listener to the MultiPartReceiver and then register the MultiPartReceiver itself to the SmsService.

Example:

 SmsService myService = new GsmSmsService();
 myService.init(myProperties);
 MessageEventListener myListener = new MessageEventListener()  {
   public void handleMessageEvent(MessageEvent evt) {
     switch( evt.getType() ) {
       case MESSAGE_RECEIVED:
         Message msg = evt.getMessage();
         if( msg instanceof EMSMessage ) {
           // EMS
         } else if( msg instanceof SmartMessage ) {
           // Smart Message (Nokia)
         }
         break;
       case MESSAGE_SENT:
          ...
      }
    });

 MultiPartReceiver mpReceiver = new MultiPartReceiver(CACHE_TIMEOUT, CACHE_SIZE, myListener);
 myService.addMessageEventListener(mpReceiver);
 

The MultiPartReceiver will only handle events of type MESSAGE_RECEIVED, all other events are directly passed to the event listener registered with the MultiPartReceiver.

Incoming SMS that are part of a concatenated (multipart) SMS will be cached in memory until all parts of the multipart SMS have been received or a timeout occurs. A timeout occurs if not all parts forming a multipart message arrive whithin a certain time.

In case of a timeout, the MultiPartReceiver signals this to its registered event listeners by broadcasting a MULTIPART_FAILURE event. The Message associated to this event can be safely cast to a MultiPartMessage holding the incomplete multipart message. It is then up to the application to decide how to handle the incomplete message.

Constructor Summary

MultiPartReceiver(long timeout, int size, MessageEventListener listener)
Construct a new MultiPartReceiver.

Method Summary

void	addMessageEventListener(MessageEventListener listener) Add a Message Event listener this this MultiPartReceiver.
static SmsMessage	buildMessage(SmsMessage[] messages) Assemble one or multiple message fragments.
void	destroy() Shutdown the MultiPartReceiver.
void	handleMessageEvent(MessageEvent event) Invoked when an event is dispatched from a Message Service
void	removeMessageEventListener(MessageEventListener listener) Remove a Listener from the list of MessageEvent listeners.

Methods inherited from class java.lang.Object

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

Constructor Detail

MultiPartReceiver

public MultiPartReceiver(long timeout,
                         int size,
                         MessageEventListener listener)

Construct a new MultiPartReceiver.

Parameters:

timeout - the maximum time in milliseconds to wait for all parts of a multipart message to arrive.

size - the maximum number of entries in the message cache.

listener - a listener receiving events.

Throws:

java.lang.IllegalArgumentException - if timeout is lower 1000 or or size is lower than than 10.

Method Detail

destroy

public void destroy()

Shutdown the MultiPartReceiver. This method must be called when the MultiPartReceiver will no longer be used.

Make sure that you first de-register the MultiPartReceiver with the SmsService in use.

handleMessageEvent

public void handleMessageEvent(MessageEvent event)

Description copied from interface: MessageEventListener

Invoked when an event is dispatched from a Message Service

Specified by:

handleMessageEvent in interface MessageEventListener

addMessageEventListener

public void addMessageEventListener(MessageEventListener listener)

Add a Message Event listener this this MultiPartReceiver.

Parameters:

listener - an Object implementing the MessageEventListener interface.

See Also:

MessageEvent, MessageEventListener

removeMessageEventListener

public void removeMessageEventListener(MessageEventListener listener)

Remove a Listener from the list of MessageEvent listeners.

Parameters:

listener - the listener to remove

buildMessage

public static SmsMessage buildMessage(SmsMessage[] messages)
                               throws MessageException

Assemble one or multiple message fragments. Depending on the characteristics of the passed message(s), this method returns a SmartMessage, EMSMessage, or SmsMessage.

Parameters:

messages - an array of messages

Returns:

the assembled message or null if the messages aray passed is null.

Throws:

MessageException - if assembling the message fails.

Since:

jSMS 2.0.2