peer2me.message
Class Message

java.lang.Object
  extended by peer2me.message.Message

public class Message
extends java.lang.Object

This class is used by the framework to exchange messages between nodes in the network. A message can contain many messageparts, which can be serialized objects, primitive datatypes and files. When adding serialized objects to a message, the object must implement the interface peer2me.util.Serializable. If a message only contains one serialized object or only primitive datatypes, it can be sent as one bytestream over the network. However, if the message contains several serialized objects and/or large files, the message must be sent in several "chunks" over the network. In order for the receiving node to put all these parts together, all chuncks that belongs to the same message must have the same ID, which in this class is the String messageID. Different messages however, must have different unique IDs. All constants in this class must be in the range 300-399

Author:
Kim Saxlund
See Also:
Serializable

Field Summary
static int MESSAGE_DISCONNECT
           
static int MESSAGE_FILE
          Identifies a message that contains a file or a part of a file
static int MESSAGE_NODE_JOIN
          When an application performs a search for new devices, it will automatically after the search has finished, send a message that contains information about all nodes to all the nodes the application has found.
static int MESSAGE_NODE_LEFT
          Identifies a message that contains information about a node that is leaving the network
static int MESSAGE_NODE_MOVE
          Identifies a message that contains information that a node has been moved from one group to another
static int MESSAGE_PRIMITIVES_OR_SERIALIZED_OBJECT
          Identifies a message that contains primitive types or serialized object
 
Constructor Summary
Message()
          Constructor that should be used by the application that creates a new message that is to be sent over the network.
Message(java.lang.String messageID)
          When a node receives a message, the framework needs to create a new message object since the message is really sent as pure bytes over the network.
 
Method Summary
 void addElement(java.lang.String key, boolean value)
          Adds a boolean this message
 void addElement(java.lang.String key, char value)
          Adds a char this message
 void addElement(java.lang.String key, double value)
          Adds a double this message
 void addElement(java.lang.String key, float value)
          Adds a float this message
 void addElement(java.lang.String key, int value)
          Adds an int to this message
 void addElement(java.lang.String key, long value)
          Adds a long this message
 void addElement(java.lang.String key, short value)
          Adds a short this message
 void addElement(java.lang.String key, java.lang.String value)
          Adds a String this message
 void addFile(java.lang.String key, java.lang.String fullPath)
          Adds a file to this message.
 void addFileInfo(java.lang.String key, FileInfo fileInfo)
          Adds information about a received file.
 void addObjectBytes(java.lang.String key, byte[] bytes)
          Adds an array of bytes to this message as a messagePart.
 void addReceivedFile(java.lang.String key, FileObject fileObject)
          When a message containing a file or a part of a file is received, a messapart containing the file must be created.
 boolean addRecipient(Node node)
          Adds a node to the collection of nodes that are to receive the message.
 void addRecipients(Group group)
          Sets an entire group of nodes as recipients of the message
 void addRecipients(Node[] nodes)
          Sets an array of nodes as recipients of this message
 void addSerializedObject(java.lang.String key, java.lang.Object o)
          Adds a serialized object to this message.
 void extractPrimitivesToSeparateParts()
          Extracts all the primitive variables from one MessagePart to several MessageParts.
 MessagePart[] getAllMessageParts()
          Returns all the MessageParts that are attached to this message Should only be used by the framework itself
 boolean getBoolean(java.lang.String key)
          Returns the boolean value that is assosiated with the key
 char getChar(java.lang.String key)
          Returns the char value that is assosiated with the key
 double getDouble(java.lang.String key)
          Returns the double value that is assosiated with the key
 FileInfo getFile(java.lang.String key)
          Returns a FileInfo object that contains information about the received file.
 float getFloat(java.lang.String key)
          Returns the float value that is assosiated with the key
 int getInt(java.lang.String key)
          Returns the int value that is assosiated with the key
 long getLong(java.lang.String key)
          Returns the long value that is assosiated with the key
 java.lang.String getMessageID()
          Gets the ID of this message.
 MessagePart getMessagePart(java.lang.String key)
          Should only be used by the framework itself
 int getMessageType()
          Returns what kind of message this is
 Node[] getRecipients()
          Returns all the recipients of this message
 Node getSender()
          Returns a Node representation of the sender of this message
 java.lang.Object getSerializedObject(java.lang.String key)
          Gets the serialized object that is assosiated with the given key
 short getShort(java.lang.String key)
          Returns the short value that is assosiated with the key
 java.lang.String getString(java.lang.String key)
          Returns the String value that is assosiated with the key
 int numberOfChunksNeeded()
          Calculates the number of chunks that this message must be split into in order to send it over the network
 void setMessageID(java.lang.String messageID)
          Sets the ID of this message.
 void setMessageType(int messageType)
          Sets the type of this message
 void setSender(Node sender)
          Sets the sender of this message.
 void storeAllPrimitivesInOnePart()
          When adding primitive variables to this message, all the variables are stored as separate MessageParts.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MESSAGE_DISCONNECT

public static final int MESSAGE_DISCONNECT
See Also:
Constant Field Values

MESSAGE_FILE

public static final int MESSAGE_FILE
Identifies a message that contains a file or a part of a file

See Also:
Constant Field Values

MESSAGE_NODE_JOIN

public static final int MESSAGE_NODE_JOIN
When an application performs a search for new devices, it will automatically after the search has finished, send a message that contains information about all nodes to all the nodes the application has found. This type of message is identified by this constant.

See Also:
Constant Field Values

MESSAGE_NODE_LEFT

public static final int MESSAGE_NODE_LEFT
Identifies a message that contains information about a node that is leaving the network

See Also:
Constant Field Values

MESSAGE_NODE_MOVE

public static final int MESSAGE_NODE_MOVE
Identifies a message that contains information that a node has been moved from one group to another

See Also:
Constant Field Values

MESSAGE_PRIMITIVES_OR_SERIALIZED_OBJECT

public static final int MESSAGE_PRIMITIVES_OR_SERIALIZED_OBJECT
Identifies a message that contains primitive types or serialized object

See Also:
Constant Field Values
Constructor Detail

Message

public Message()
Constructor that should be used by the application that creates a new message that is to be sent over the network. The message will generate a random messageID by using new Date().getTime() function combined with the method getHexString in class peer2me.util.HexBuilder.


Message

public Message(java.lang.String messageID)
When a node receives a message, the framework needs to create a new message object since the message is really sent as pure bytes over the network. The messageID is already created by the sender of the message and needs to be used by the receiver to identify the message.

Parameters:
messageID - The unique identificator of this message
Method Detail

numberOfChunksNeeded

public int numberOfChunksNeeded()
Calculates the number of chunks that this message must be split into in order to send it over the network

Returns:
The number of chunks needed

addRecipient

public boolean addRecipient(Node node)
Adds a node to the collection of nodes that are to receive the message.

Parameters:
node - The node that should receive the message
Returns:
Returns true if node is added to collection. Returns false if it already existst in the collection

addRecipients

public void addRecipients(Group group)
Sets an entire group of nodes as recipients of the message

Parameters:
group - The group of recipients that will receive the message

addRecipients

public void addRecipients(Node[] nodes)
Sets an array of nodes as recipients of this message

Parameters:
nodes - An array of nodes that should receive this message

addElement

public void addElement(java.lang.String key,
                       int value)
Adds an int to this message

Parameters:
key - The unique key that the int will be assosiated with
value - The int value that will be attached to this message

addElement

public void addElement(java.lang.String key,
                       double value)
Adds a double this message

Parameters:
key - The unique key that the double will be assosiated with
value - The double value that will be attached to this message

addElement

public void addElement(java.lang.String key,
                       char value)
Adds a char this message

Parameters:
key - The unique key that the char will be assosiated with
value - The char value that will be attached to this message

addElement

public void addElement(java.lang.String key,
                       boolean value)
Adds a boolean this message

Parameters:
key - The unique key that the boolean will be assosiated with
value - The boolean value that will be attached to this message

addElement

public void addElement(java.lang.String key,
                       java.lang.String value)
Adds a String this message

Parameters:
key - The unique key that the String will be assosiated with
value - The String value that will be attached to this message

addElement

public void addElement(java.lang.String key,
                       long value)
Adds a long this message

Parameters:
key - The unique key that the long will be assosiated with
value - The long value that will be attached to this message

addElement

public void addElement(java.lang.String key,
                       float value)
Adds a float this message

Parameters:
key - The unique key that the float will be assosiated with
value - The float value that will be attached to this message

addElement

public void addElement(java.lang.String key,
                       short value)
Adds a short this message

Parameters:
key - The unique key that the short will be assosiated with
value - The short value that will be attached to this message

extractPrimitivesToSeparateParts

public void extractPrimitivesToSeparateParts()
Extracts all the primitive variables from one MessagePart to several MessageParts. This method is invoked by the BluetoothListener class when a message is received.


storeAllPrimitivesInOnePart

public void storeAllPrimitivesInOnePart()
When adding primitive variables to this message, all the variables are stored as separate MessageParts. These parts are stored in a HashMap in this class. When this method is called, all the stored primitive variables are converted into one MessagePart which is assigned the key: primitives. This enables the framework to send all the primitive variables in one chunk. When the message is received on the receiving node, the parts are extracted back to the original structure by invoking the method extractPrimitvesToSeparateParts This method should only be used by classes inside the peer2me package.


addFile

public void addFile(java.lang.String key,
                    java.lang.String fullPath)
Adds a file to this message. This method only adds the path to the file and not the filecontents. The content of the file is not read before the message is actually sent. When the framework is instructed to send the message, the file is read and sent in chunks of sizes specified in the SendFileObject class.

Parameters:
key - The unique key that the file will be assosiated with
fullPath - The full path to the directory of which the file is located. An example of such a path is: file:///SDCard/images/animal.jpg

addReceivedFile

public void addReceivedFile(java.lang.String key,
                            FileObject fileObject)
When a message containing a file or a part of a file is received, a messapart containing the file must be created. This method adds a such a messagepart This method should only be used by classes inside the peer2me package.

Parameters:
key - The unique key that the file will be assosiated with
fileObject - The fileObject that will be attached to this message

getMessagePart

public MessagePart getMessagePart(java.lang.String key)
Should only be used by the framework itself

Parameters:
key - A unique key that is assosiated with a messagePart
Returns:
The messagPart that is assosiated with the key

getInt

public int getInt(java.lang.String key)
Returns the int value that is assosiated with the key

Parameters:
key - A unique key that is assosiated with an int value
Returns:
The int that is assosiated with the key

getDouble

public double getDouble(java.lang.String key)
Returns the double value that is assosiated with the key

Parameters:
key - A unique key that is assosiated with an double value
Returns:
The double that is assosiated with the key

getString

public java.lang.String getString(java.lang.String key)
Returns the String value that is assosiated with the key

Parameters:
key - A unique key that is assosiated with an String value
Returns:
The String that is assosiated with the key

getBoolean

public boolean getBoolean(java.lang.String key)
Returns the boolean value that is assosiated with the key

Parameters:
key - A unique key that is assosiated with an boolean value
Returns:
The boolean that is assosiated with the key

getLong

public long getLong(java.lang.String key)
Returns the long value that is assosiated with the key

Parameters:
key - A unique key that is assosiated with an long value
Returns:
The long that is assosiated with the key

getFloat

public float getFloat(java.lang.String key)
Returns the float value that is assosiated with the key

Parameters:
key - A unique key that is assosiated with an float value
Returns:
The float that is assosiated with the key

getShort

public short getShort(java.lang.String key)
Returns the short value that is assosiated with the key

Parameters:
key - A unique key that is assosiated with an short value
Returns:
The short that is assosiated with the key

getChar

public char getChar(java.lang.String key)
Returns the char value that is assosiated with the key

Parameters:
key - A unique key that is assosiated with an char value
Returns:
The char that is assosiated with the key

addFileInfo

public void addFileInfo(java.lang.String key,
                        FileInfo fileInfo)
Adds information about a received file. Must not be used to add a file to this Message. If you want to add a file to this Message, then you must use the method addFile(String, String) This method should only be used by the framework itself

Parameters:
key - A unique key that is assosiated with the file
fileInfo - The FileInfo object

getFile

public FileInfo getFile(java.lang.String key)
Returns a FileInfo object that contains information about the received file.

Parameters:
key - A unique key that is assosiated with the file
Returns:
The FileInfo object

getAllMessageParts

public MessagePart[] getAllMessageParts()
Returns all the MessageParts that are attached to this message Should only be used by the framework itself

Returns:
An array of all the MessageParts that are attached to this message

getRecipients

public Node[] getRecipients()
Returns all the recipients of this message

Returns:
An array of Nodes that are the recipients of this message

getMessageType

public int getMessageType()
Returns what kind of message this is

Returns:
An int value that can be either of the following: MESSAGE_DISCONNECT, MESSAGE_FILE, MESSAGE_NODE_JOIN, MESSAGE_NODE_LEFT or MESSAGE_PRIMITIVES_OR_SERIALIZED_OBJECT

getSender

public Node getSender()
Returns a Node representation of the sender of this message

Returns:
The sender of this message
See Also:
Node

setSender

public void setSender(Node sender)
Sets the sender of this message. Should only be used by the framework itself.

Parameters:
sender - The sender of this message

getMessageID

public java.lang.String getMessageID()
Gets the ID of this message. A message may be split in several chunks in order to send it over the network. In such cases, all the chunks will have the same ID.

Returns:
The ID of this message

setMessageID

public void setMessageID(java.lang.String messageID)
Sets the ID of this message. Should only be used internally in the framework

Parameters:
messageID - The ID that this message will be assosiated with

addSerializedObject

public void addSerializedObject(java.lang.String key,
                                java.lang.Object o)
                         throws InvalidKeyException
Adds a serialized object to this message.

Parameters:
key - The unique key that will be assosiated with the serialized object
o - A serialized object. The object MUST implement the interface Serializable.
Throws:
InvalidKeyException - Will be thrown if the key given is of lenght = 0 or null.

getSerializedObject

public java.lang.Object getSerializedObject(java.lang.String key)
                                     throws UnknownKeyException
Gets the serialized object that is assosiated with the given key

Parameters:
key - The unique key that is assosiated with the object
Returns:
A serialized object which MUST be cast to the correct serialized object when returned
Throws:
UnknownKeyException - If the serialized object is not found

addObjectBytes

public void addObjectBytes(java.lang.String key,
                           byte[] bytes)
Adds an array of bytes to this message as a messagePart. The array can only contain the bytes of a serialized object or primitive variables stored by the method storeAllPrimitivesInOnePart

Parameters:
key - The key can only be assosiated to a serialized object or primitive variables stored in an array of bytes. The latter will always be assosiated with the key primitives.
bytes - The array of bytes that will be stored in this message as a MessagePart.
See Also:
storeAllPrimitivesInOnePart(), addSerializedObject(String, Object)

setMessageType

public void setMessageType(int messageType)
Sets the type of this message

Parameters:
messageType - Must be one of the following: MESSAGE_DISCONNECT, MESSAGE_FILE, MESSAGE_NODE_JOIN, MESSAGE_NODE_LEFT, or MESSAGE_PRIMITIVES_OR_SERIALIZED_OBJECT