spread
Class SpreadMessage

java.lang.Object
  |
  +--spread.SpreadMessage

public class SpreadMessage

extends java.lang.Object

A SpreadMessage object represents either an incoming or outgoing spread message. An outgoing message is one being sent with SpreadConnection.multicast(SpreadMessage). An incoming message is one received with SpreadConnection.receive(). To send a message on a spread connection, first create a message object:

 SpreadMessage message = new SpreadMessage();
 

Then set the data with either setData(byte[]), setObject(Serializable), or digest(Serializable):

 message.setData(data);
 

Select which group(s) to send the message to with addGroup(SpreadGroup):

 message.setGroup(group);
 

When the message is read to be sent, send it with SpreadConnection.multicast(SpreadMessage):

 connection.multicast(message);
 

Constructor Summary

SpreadMessage()
Initializes a new outgoing SpreadMessage object.

Method Summary

void	addGroup(SpreadGroup group) Adds this group to the list this message will be sent to.
void	addGroup(java.lang.String group) Adds this group to the list this message will be sent to.
void	addGroups(SpreadGroup[] groups) Adds these groups to the list this message will be sent to.
void	addGroups(java.lang.String[] groups) Adds these groups to the list this message will be sent to.
java.lang.Object	clone() Creates a copy of this message.
void	digest(java.io.Serializable object) Adds this message to the digest.
byte[]	getData() Gets the message data as an array of bytes.
java.util.Vector	getDigest() Gets the message data as a digest.
boolean	getEndianMismatch() Checks for an endian mismatch.
SpreadGroup[]	getGroups() Gets an array containing the SpreadGroup's to which this message was sent.
MembershipInfo	getMembershipInfo() Get the membership info for this message.
java.lang.Object	getObject() Gets the message data as a java object.
SpreadGroup	getSender() Gets the message sender's private group.
int	getServiceType() Get the message's service type.
short	getType() Gets the message type.
boolean	isAgreed() Checks if this is an agreed message.
boolean	isCausal() Checks if this is a causal message.
boolean	isFifo() Checks if this is a fifo message.
boolean	isIncoming() Check if this is an incoming message.
boolean	isMembership() Checks if this is a membership message.
boolean	isOutgoing() Check if this is an outgoing message.
boolean	isRegular() Checks if this is a regular message.
boolean	isReliable() Checks if this is a reliable message.
boolean	isSafe() Checks if this is a safe message.
boolean	isSelfDiscard() Checks if this is a self-discard message.
boolean	isUnreliable() Checks if this is an unreliable message.
void	setAgreed() Sets the message to be agreed.
void	setCausal() Sets the message to be causal.
void	setData(byte[] data) Sets the message's data to this array of bytes.
void	setFifo() Sets the message to be fifo.
void	setObject(java.io.Serializable object) Sets the message's data to this object, in serialized form.
void	setReliable() Sets the message to be reliable.
void	setSafe() Sets the message to be safe.
void	setSelfDiscard(boolean selfDiscard) If selfDiscard is true, sets the self discard flag for the message, otherwise clears the flag.
void	setServiceType(int serviceType) Sets the service type.
void	setType(short type) Set's the message type.
void	setUnreliable() Sets the message to be unreliable.

Methods inherited from class java.lang.Object

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

Constructor Detail

SpreadMessage

public SpreadMessage()

Initializes a new outgoing SpreadMessage object. By default the message is reliable.

Method Detail

isIncoming

public boolean isIncoming()

Check if this is an incoming message. This is true if it has been received with SpreadConnection.receive().

Returns:

true if this in an incoming message

isOutgoing

public boolean isOutgoing()

Check if this is an outgoing message. This is true if this is a message being sent with SpreadConnection.multicast(SpreadMessage).

Returns:

true if this is an outgoing message

getServiceType

public int getServiceType()

Get the message's service type. The service type is a bitfield representing the type of message.

Returns:

the service-type

isRegular

public boolean isRegular()

Checks if this is a regular message. If true, the get*() functions can be used to obtain more information about the message.

Returns:

true if this is a regular message

See Also:

getGroups(), getSender(), getData(), getObject(), getDigest(), getType(), getEndianMismatch()

isMembership

public boolean isMembership()

Checks if this is a membership message. If true, getMembershipInfo() can be used to get more information on the membership change.

Returns:

true if this is a membership message

See Also:

getMembershipInfo()

isUnreliable

public boolean isUnreliable()

Checks if this is an unreliable message.

Returns:

true if this is an unreliable message

isReliable

public boolean isReliable()

Checks if this is a reliable message.

Returns:

true if this is a reliable message

isFifo

public boolean isFifo()

Checks if this is a fifo message.

Returns:

true if this is a fifo message

isCausal

public boolean isCausal()

Checks if this is a causal message.

Returns:

true if this is a causal message

isAgreed

public boolean isAgreed()

Checks if this is an agreed message.

Returns:

true if this is an agreed message

isSafe

public boolean isSafe()

Checks if this is a safe message.

Returns:

true if this is a safe message

isSelfDiscard

public boolean isSelfDiscard()

Checks if this is a self-discard message.

Returns:

true if this is a self-discard message

setServiceType

public void setServiceType(int serviceType)

Sets the service type. The service type is a bitfield representing the type of message.

Parameters:

serviceType - the new service type

setUnreliable

public void setUnreliable()

Sets the message to be unreliable.

setReliable

public void setReliable()

Sets the message to be reliable. This is the default type for a new outgoing message.

setFifo

public void setFifo()

Sets the message to be fifo.

setCausal

public void setCausal()

Sets the message to be causal.

setAgreed

public void setAgreed()

Sets the message to be agreed.

setSafe

public void setSafe()

Sets the message to be safe.

setSelfDiscard

public void setSelfDiscard(boolean selfDiscard)

If selfDiscard is true, sets the self discard flag for the message, otherwise clears the flag. If the self discard flag is set, the message will not be received at the connection it is multicast on.

Parameters:

selfDiscard - if true, set the self discard flag, if false, clear the self discard flag

getGroups

public SpreadGroup[] getGroups()

Gets an array containing the SpreadGroup's to which this message was sent.

Returns:

the groups to which this message was sent

getSender

public SpreadGroup getSender()

Gets the message sender's private group. This can be used to uniquely identify the sender on the connection this message was received from or to send a reply to the sender.

getData

public byte[] getData()

Gets the message data as an array of bytes. This can be used no matter how the message was sent, but is usually used when the message was sent using setData(byte[]) or from an application using the C library.

Returns:

the message data

See Also:

setData(byte[])

getObject

public java.lang.Object getObject()
                           throws SpreadException

Gets the message data as a java object. The message data should have been set using setObject(Serializable). Regardless of the type of object passed to setObject(Serializable), this method returns an object of type Object, so it must be cast to the correct type.

Returns:

the message data as an object

Throws:

SpreadException - if there is an error reading the object

See Also:

setObject(Serializable)

getDigest

public java.util.Vector getDigest()
                           throws SpreadException

Gets the message data as a digest. The message data should have been set using digest(Serializable). This method returns a Vector containing all of the objects passed to digest(Serializable), in the order they were passed.

Returns:

the message data as a list of objects

Throws:

SpreadException - if there is an error reading the objects

See Also:

digest(Serializable)

getType

public short getType()

Gets the message type. The message type is set with setType(short).

Returns:

the message type

See Also:

setType(short)

getEndianMismatch

public boolean getEndianMismatch()

Checks for an endian mismatch. If there is an endian mismatch between the machine that sent the message and the local machine, this is true. This is a signal to the application so that it can handle endian flips in its message data. Aside from the message data, spread handles all other endian mismatches itself (for example, the message type).

Returns:

true if there is an endian mismatch

addGroup

public void addGroup(SpreadGroup group)

Adds this group to the list this message will be sent to. When the message is multicast, all members of this group will receive it.

Parameters:

group - a group to send this message to

addGroups

public void addGroups(SpreadGroup[] groups)

Adds these groups to the list this message will be sent to. When the message is multicast, all members of these groups will receive it.

Parameters:

groups - a list of groups to send this message to

addGroup

public void addGroup(java.lang.String group)

Adds this group to the list this message will be sent to. When the message is multicast, all members of this group will receive it.

Parameters:

group - a group to send this message to

addGroups

public void addGroups(java.lang.String[] groups)

Adds these groups to the list this message will be sent to. When the message is multicast, all members of these groups will receive it.

Parameters:

groups - a list of groups to send this message to

setData

public void setData(byte[] data)

Sets the message's data to this array of bytes. This cancels any previous calls to setData(byte[]), setObject(Serializable), digest(Serializable).

Parameters:

data - the new message data

See Also:

getData()

setObject

public void setObject(java.io.Serializable object)
               throws SpreadException

Sets the message's data to this object, in serialized form. The object must support the Serializable interface to use this method. This cancels any previous calls to setData(byte[]), setObject(Serializable), digest(Serializable). This should not be used if an application using the C library needs to read this message.

Parameters:

object - the object to set the data to

See Also:

getObject()

digest

public void digest(java.io.Serializable object)
            throws SpreadException

Adds this message to the digest. The object must support the Serializable interface to use this method. This cancels any previous calls to setData(byte[]) or setObject(Serializable). This should not be used if an application using the C library needs to read this message. When the message is sent, all of the objects that have been passed to this method get sent as the message data.

Parameters:

object - the object to add to the digets

See Also:

getDigest()

setType

public void setType(short type)

Set's the message type. This is a 16-bit integer that can be used by the application to identify the message.

Parameters:

type - the message type

See Also:

getType()

getMembershipInfo

public MembershipInfo getMembershipInfo()

Get the membership info for this message. This should only be called if this is a membership message (isMembership() is true).

Returns:

the membership info for this message

clone

public java.lang.Object clone()

Creates a copy of this message.

Returns:

a copy of this message