org.safs.android.messenger

Class MultipleParcelsHandler

java.lang.Object

android.os.Handler

org.safs.android.messenger.MultipleParcelsHandler

Direct Known Subclasses:

MessengerHandler, MessengerHandler

public abstract class MultipleParcelsHandler
extends android.os.Handler

This class contains methods to handle message of big size.
At the message-sender side, the message will be divided to multiples parcels. These multiples
parcels contain an ID to indicate to which message they belong; They contains an index to
indicate their order; They also contains a filed to indicate if it is the last parcel.
At the message-receiver side, the multiple parcels will be assembled to one message.

Message-Sender:
MessengerService
MessengerRunner

Message-Receiver:
MessengerHandler
MessengerHandler

Since:

APR 25, 2013

Author:

Lei Wang, SAS Institute, Inc

See Also:

MessengerService, MessengerRunner, MessengerHandler, MessengerHandler

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	MultipleParcelsHandler.ParcelBuffer
protected class	MultipleParcelsHandler.SmallParcel This class is used to wrap a small parcel of a whole message.

Nested classes/interfaces inherited from class android.os.Handler

android.os.Handler.Callback

Field Summary

Fields

Modifier and Type	Field and Description
static int	INITIAL_MESSAGE_CACHE_SIZE
static int	INITIAL_PARCEL_CACHE_SIZE
java.lang.String	TAG
static int	TIMEOUT_WAIT_FOR_PARCEL_ACKNOWLEDGMENT time to wait for acknowledgment of parcel in milliseconds

Constructor Summary

Constructors

Constructor and Description
MultipleParcelsHandler(android.os.Looper looper, MultipleParcelListener multipleParcelListener)
MultipleParcelsHandler(MultipleParcelListener multipleParcelListener)

Method Summary

Modifier and Type	Method and Description
boolean	assembleSmallParcels(android.os.Message msg) This method will accumulate small parcels of one message, store them into a cache for future assembly. Message.obj will hold the final result of message: If the message is not divided into parcels, this method will do no thing. If the message is divided into parcels, this method will store them into a cache messageReceivedCache and assemble them and assign it to parameter msg.obj when the last parcel arrives.
protected void	clearParcelMessage(java.lang.String messageID) Clear the cache messageSendedCache
protected void	clearParcelMessage(java.lang.String messageID, int index) Clear one parcel of a message from the cache messageSendedCache
protected boolean	containMessageWithoutAck(java.lang.String messageID) It is used to test if the cache messageSendedCache still contains a certain message indicated by parameter messageID.
protected void	debug(java.lang.String message)
protected java.util.List<android.os.Message>	divideMessageIntoSmallPieces(android.os.Message msg, char[] buffer) Divide message's content into small parcels if the message content size is too large. If the content size is bigger than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will be divided into small parcels, wrapped to a Message object and put into a List to return. If the content size is smaller than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will be set to the original Message object and put into a List to return.
protected java.util.List<android.os.Message>	divideMessageIntoSmallPieces(android.os.Message msg, java.util.Properties props) Divide message's content into small parcels if the message content size is too large. If the content size is bigger than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will be divided into small parcels, wrapped to a Message object and put into a List to return. If the content size is smaller than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will be set to the original Message object and put into a List to return.
protected java.util.List<android.os.Message>	divideMessageIntoSmallPieces(android.os.Message msg, java.lang.String message) Divide message's content into small parcels if the message content size is too large. If the content size is bigger than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will be divided into small parcels, wrapped to a Message object and put into a List to return. If the content size is smaller than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will be set to the original Message object and put into a List to return.
protected android.os.Message[]	getParcelMessage(java.lang.String messageID) According to messageId to get a set of parcels of a whole messagefrom the cache messageSendedCache.
protected android.os.Message	getParcelMessage(java.lang.String messageID, int index) According to messageId and index to get one parcel of a whole message from the cache messageSendedCache.
protected int	getTotalNumberOfParcels(int dataLength, int parcelLength) Calculate the total number of parcels the message will be divided.
protected java.lang.String	getUniqueKey() Routine is used to create a unique ID String key that can be used by "message-sender" to identify different small parcels of the same message. This method is thread-safe: it guarantees that multiple threads can get unique ID.
void	handleMessage(android.os.Message msg) Override method from Handler We will handle the small parcels of a whole message.
protected abstract void	handleWholeMessage(android.os.Message msg) The subclass of this class must implement this method to handle message.
protected void	sendAcknowledgment(java.lang.String messageID)
protected void	sendAcknowledgment(java.lang.String messageID, int index)
boolean	sendMessageAsMultipleParcels(android.os.Messenger mService, android.os.Message msg, java.lang.Object object) If the messag's size is bigger than MessageUtil.MAX_TRANSFER_BYTE_SIZE, Send the message as multiple parcels and wait for acknowledgment of the each parcel, if no acknowledgment arrive within timeout 5000, all the parcels in cache messageSendedCache of a message will be re-sent out. At the message-receiver side, the parcels will be assembled by method assembleSmallParcels(Message)
boolean	sendMessageOfLostParcel(android.os.Messenger mService, java.lang.String messageID) According to the messageID, we will get the message from cache messageSendedCache and send it out. We should set the field MessageUtil.BUNDLE_SMALL_RESENT_PARCEL to true, so that 'message-receiver' will know it is a message being resent by 'sender'
boolean	sendMessageOfLostParcel(android.os.Messenger mService, java.lang.String messageID, int index) According to the messageID and index, we will get the message from cache messageSendedCache and send it out. We should set the field MessageUtil.BUNDLE_SMALL_RESENT_PARCEL to true, so that 'message-receiver' will know it is a message being resent by 'sender'
protected java.lang.String	storeParcelMessage(android.os.Message parcel) Store parcel (part of a message) into a cache according to the message ID. If the parcel is not a part of a whole message, it will not be stored in the cache We use MessageUtil.isSmallParcelOfWholeMessage(Bundle) to test if this parcel is a part of message.

Methods inherited from class android.os.Handler

dispatchMessage, dump, getLooper, getMessageName, hasMessages, hasMessages, obtainMessage, obtainMessage, obtainMessage, obtainMessage, obtainMessage, post, postAtFrontOfQueue, postAtTime, postAtTime, postDelayed, removeCallbacks, removeCallbacks, removeCallbacksAndMessages, removeMessages, removeMessages, sendEmptyMessage, sendEmptyMessageAtTime, sendEmptyMessageDelayed, sendMessage, sendMessageAtFrontOfQueue, sendMessageAtTime, sendMessageDelayed, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TAG

public java.lang.String TAG

INITIAL_MESSAGE_CACHE_SIZE

public static final int INITIAL_MESSAGE_CACHE_SIZE

See Also:

Constant Field Values

INITIAL_PARCEL_CACHE_SIZE

public static final int INITIAL_PARCEL_CACHE_SIZE

See Also:

Constant Field Values

TIMEOUT_WAIT_FOR_PARCEL_ACKNOWLEDGMENT

public static final int TIMEOUT_WAIT_FOR_PARCEL_ACKNOWLEDGMENT

time to wait for acknowledgment of parcel in milliseconds

See Also:

Constant Field Values

Constructor Detail

MultipleParcelsHandler

public MultipleParcelsHandler(android.os.Looper looper,
                              MultipleParcelListener multipleParcelListener)

MultipleParcelsHandler

public MultipleParcelsHandler(MultipleParcelListener multipleParcelListener)

Method Detail

debug

protected void debug(java.lang.String message)

assembleSmallParcels

public boolean assembleSmallParcels(android.os.Message msg)
                             throws java.lang.Exception

This method will accumulate small parcels of one message, store them into
a cache for future assembly.
Message.obj will hold the final result of message:
If the message is not divided into parcels, this method will do no thing.
If the message is divided into parcels, this method will store them into
a cache messageReceivedCache and assemble them and assign it to
parameter msg.obj when the last parcel arrives. Each time a parcel arrives
and be stored in the cache messageReceivedCache, an acknowledgment
will be sent back to the message-sender.
The message is sent out by method sendMessageAsMultipleParcels(Messenger, Message, Object)
at the message-sender side.

Parameters:

msg - Message

Returns:

Boolean, if we have finished handling all the parcels of a whole message.

Throws:

java.lang.Exception

See Also:

sendMessageAsMultipleParcels(Messenger, Message, Object)

sendAcknowledgment

protected void sendAcknowledgment(java.lang.String messageID)

sendAcknowledgment

protected void sendAcknowledgment(java.lang.String messageID,
                                  int index)

handleWholeMessage

protected abstract void handleWholeMessage(android.os.Message msg)

The subclass of this class must implement this method to handle message.

getUniqueKey

protected java.lang.String getUniqueKey()

Routine is used to create a unique ID String key that can be used by "message-sender" to identify different small parcels of the same message.
This method is thread-safe: it guarantees that multiple threads can get unique ID.

Returns:

unique String suitable to be the key for the item.

storeParcelMessage

protected java.lang.String storeParcelMessage(android.os.Message parcel)

Store parcel (part of a message) into a cache according to the message ID.
If the parcel is not a part of a whole message, it will not be stored in the cache
We use MessageUtil.isSmallParcelOfWholeMessage(Bundle) to test if this
parcel is a part of message.

Parameters:

parcel, - Message, one parcel of a whole message, it should contain a data(ID,index,totalNumber)

Returns:

String, the messageID of the parcel stored.

clearParcelMessage

protected void clearParcelMessage(java.lang.String messageID)

Clear the cache messageSendedCache

clearParcelMessage

protected void clearParcelMessage(java.lang.String messageID,
                                  int index)

Clear one parcel of a message from the cache messageSendedCache

getParcelMessage

protected android.os.Message[] getParcelMessage(java.lang.String messageID)

According to messageId to get a set of parcels of a whole messagefrom
the cache messageSendedCache.

Parameters:

messageID, - String, represent a message

Returns:

Message[], an array of parcels of a message.

getParcelMessage

protected android.os.Message getParcelMessage(java.lang.String messageID,
                                              int index)

According to messageId and index to get one parcel of a whole message from
the cache messageSendedCache.

Parameters:

messageID, - String, represent a message.

index, - int, the index of the parcel.

Returns:

Message, one parcel of a message.

containMessageWithoutAck

protected boolean containMessageWithoutAck(java.lang.String messageID)

It is used to test if the cache messageSendedCache still contains a
certain message indicated by parameter messageID.

See Also:

clearParcelMessage(String), clearParcelMessage(String, int)

getTotalNumberOfParcels

protected int getTotalNumberOfParcels(int dataLength,
                                      int parcelLength)

Calculate the total number of parcels the message will be divided.

divideMessageIntoSmallPieces

protected java.util.List<android.os.Message> divideMessageIntoSmallPieces(android.os.Message msg,
                                                                          java.util.Properties props)
                                                                   throws java.lang.Exception

Divide message's content into small parcels if the message content size is too large.
If the content size is bigger than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will
be divided into small parcels, wrapped to a Message object and put into a List to return.
If the content size is smaller than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will
be set to the original Message object and put into a List to return.

Parameters:

msg - Message, the original message to send. It contains 'what' and 'replyTo'.

props - Properties, the real content to send through Message.

Returns:

List of Message, to send. Never null and contain at the least one Message.

Throws:

java.lang.Exception

See Also:

MessageUtil

divideMessageIntoSmallPieces

protected java.util.List<android.os.Message> divideMessageIntoSmallPieces(android.os.Message msg,
                                                                          char[] buffer)
                                                                   throws java.lang.Exception

Divide message's content into small parcels if the message content size is too large.
If the content size is bigger than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will
be divided into small parcels, wrapped to a Message object and put into a List to return.
If the content size is smaller than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will
be set to the original Message object and put into a List to return.

Parameters:

msg - Message, the original message to send. It contains 'what' and 'replyTo'.

buffer - char[], the real content to send through Message.

Returns:

List of Message, to send. Never null and contain at the least one Message.

Throws:

java.lang.Exception

See Also:

MessageUtil

divideMessageIntoSmallPieces

protected java.util.List<android.os.Message> divideMessageIntoSmallPieces(android.os.Message msg,
                                                                          java.lang.String message)
                                                                   throws java.lang.Exception

Divide message's content into small parcels if the message content size is too large.
If the content size is bigger than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will
be divided into small parcels, wrapped to a Message object and put into a List to return.
If the content size is smaller than MessageUtil.MAX_TRANSFER_BYTE_SIZE, it will
be set to the original Message object and put into a List to return.

Parameters:

msg - Message, the original message to send. It contains 'what' and 'replyTo'.

message - String, the real content to send through Message.

Returns:

List of Message, to send. Never null and contain at the least one Message.

Throws:

java.lang.Exception

See Also:

MessageUtil

sendMessageAsMultipleParcels

public boolean sendMessageAsMultipleParcels(android.os.Messenger mService,
                                            android.os.Message msg,
                                            java.lang.Object object)

If the messag's size is bigger than MessageUtil.MAX_TRANSFER_BYTE_SIZE,
Send the message as multiple parcels
and wait for acknowledgment of the each parcel, if no acknowledgment arrive within
timeout 5000, all the parcels in cache
messageSendedCache of a message will be re-sent out.
At the message-receiver side, the parcels will be assembled by method assembleSmallParcels(Message)

Parameters:

msg, - Message, a wrapper for the object.

message, - Object, the object to send

Returns:

boolean, true if the message is sent out.

See Also:

#sendServiceResult(Properties), #sendServiceResult(MessageResult), assembleSmallParcels(Message)

sendMessageOfLostParcel

public boolean sendMessageOfLostParcel(android.os.Messenger mService,
                                       java.lang.String messageID)

According to the messageID, we will get the message from cache messageSendedCache
and send it out.
We should set the field MessageUtil.BUNDLE_SMALL_RESENT_PARCEL to true,
so that 'message-receiver' will know it is a message being resent by 'sender'

See Also:

getParcelMessage(String, int), MessageUtil.addParcelableResentParcelFromSmallParcel(Parcelable, boolean)

sendMessageOfLostParcel

public boolean sendMessageOfLostParcel(android.os.Messenger mService,
                                       java.lang.String messageID,
                                       int index)

According to the messageID and index, we will get the message from cache messageSendedCache
and send it out.
We should set the field MessageUtil.BUNDLE_SMALL_RESENT_PARCEL to true,
so that 'message-receiver' will know it is a message being resent by 'sender'

See Also:

getParcelMessage(String, int)

handleMessage

public void handleMessage(android.os.Message msg)

Override method from Handler We will handle the small parcels of a whole message. Make sure no parcels are lost and assemble them in order.

Overrides:

handleMessage in class android.os.Handler