Project JXTA

net.jxta.endpoint
Class Message

java.lang.Object
  extended by net.jxta.util.AbstractSimpleSelectable
      extended by net.jxta.endpoint.Message
All Implemented Interfaces:
Serializable, SimpleSelectable

public class Message
extends AbstractSimpleSelectable
implements Serializable

Messages are containers for protocol messages within JXTA. Services and applications are expected to use Messages as the basis for any protocols implemented within JXTA. Messages are exchanged through the EndpointService or PipeService.

A Message is composed of an ordered list of zero or more MessageElements. Each MessageElement is associated with a namespace at the time it is added to the message. Duplicate MessageElements are permitted.

Messages are not synchronized. All of the iterators returned by this implementation are "fail-fast". Concurrent modification from multiple threads will produce unexpected results.

See Also:
MessageElement, EndpointAddress, EndpointService, InputPipe, OutputPipe, PipeService, Serialized Form

Nested Class Summary
protected static class Message.element
          holds an element and its namespace
 class Message.ElementIterator
          A ListIterator for MessageElements which also provides the ability to determine the namespace of the current message element.
 
Nested classes/interfaces inherited from interface net.jxta.util.SimpleSelectable
SimpleSelectable.IdentityReference
 
Field Summary
protected  long cachedByteLength
          cached aggregate size of all the memeber elements.
protected  int cachedByteLengthModCount
          modcount at the time the message length was last calculated.
protected  String defaultNamespace
          This string identifies the namespace which is assumed when calls are made that don't include a namespace specification.
protected  List elements
          List of the elements.
protected static boolean GLOBAL_TRACKING_ELEMENT
          If true, then a tracking element is added to the message.
protected  List lineage
          A list of Integer which details the lineage (history of cloning) that produced this message.
protected static boolean LOG_MODIFICATIONS
          If true, then modification logging be activated.
protected  int modCount
          Modification count of this message.
protected  List modHistory
          The history of modifications this message.
 boolean modifiable
          Deprecated. You really should not depend on this feature.
protected  Map namespaces
          the namespaces in this message and the elements in each.
protected  Map properties
          Message properties HashMap keys are Object values are Object
 
Fields inherited from class net.jxta.util.AbstractSimpleSelectable
identityReference
 
Constructor Summary
  Message()
          Standard Constructor for messages.
protected Message(String defaultNamespace)
          Standard Constructor for messages.
 
Method Summary
 void addMessageElement(MessageElement add)
          Add a MessageElement into the message.
 void addMessageElement(String namespace, MessageElement add)
          Add a MessageElement into the message using the specified namespace.
 void clear()
          Removes all of the elements in all namespaces from the message.
 Object clone()
          

Duplicates the Message.

 boolean equals(Object target)
          

Compare this Message against another.

 long getByteLength()
          Returns the aggregate size of all the memeber elements.
protected  String getDefaultNamespace()
          Return the default Namespace of this message.
 MessageElement getMessageElement(String name)
          Retrieve a element by name from the message without regard to namespace.
 MessageElement getMessageElement(String namespace, String name)
          Retrieve a element by name in the specified namespace from the message.
 Message.ElementIterator getMessageElements()
          Returns a list iterator of all of the elements contained in this message.
 Message.ElementIterator getMessageElements(MimeMediaType type)
          Returns a list iterator of all of the elements contained in this message whose mime-type matchs the given in the order they were added to the message.
 Message.ElementIterator getMessageElements(String name)
          Returns a list iterator of all of the elements contained in this message who's name matches the specified name.
 Message.ElementIterator getMessageElements(String namespace, MimeMediaType type)
          Returns a list iterator of all of the elements contained in this message whose type matches the given in the order they were added to the message.
 Message.ElementIterator getMessageElements(String namespace, String name)
          Returns a list iterator of all of the elements contained in the specified namespace who's name matches the specified name in the order in which they were added to the Message.
 Message.ElementIterator getMessageElementsOfNamespace(String namespace)
          Returns an list iterator of all of the elements contained in this message which match the specified namespace.
 Iterator getMessageLineage()
          Returns an iterator which describes the lineage of this message.
 int getMessageModCount()
          Returns the modification count of this message.
 String getMessageModHistory()
          Returns a string containing the modification history for this message
 Iterator getMessageNamespaces()
          Returns an iterator of the namespaces present in this message.
 int getMessageNumber()
          Returns the message number of this message.
 Object getMessageProperty(Object key)
          Retrieves a transient property from the set for this message.
protected static int getNextMessageNumber()
          Returns the next message number in sequence.
 int hashCode()
          
protected  int incMessageModCount()
          Returns the modification count of this message.
 void itemChanged(SimpleSelectable o)
          This method is invoked when the given selectable object has changed.
 boolean removeMessageElement(MessageElement remove)
          Remove an the first occurance of the provided MessageElement from the message.
 boolean removeMessageElement(String namespace, MessageElement remove)
          Remove the first occurance of the provided MessageElement within the specified namespace from the message.
 MessageElement replaceMessageElement(MessageElement replacement)
          Replace a MessageElement in the message.
 MessageElement replaceMessageElement(String namespace, MessageElement replacement)
          Replace a MessageElement in the message using the specified namespace.
 Object setMessageProperty(Object key, Object value)
          Associate a transient property with this message. if there was a previous value for the key provided then it is returned.
 String toString()
          

Displays the lineage of the message including its own message number.

 
Methods inherited from class net.jxta.util.AbstractSimpleSelectable
getIdentityReference, haveListeners, notifyChange, register, registerListener, unregister, unregisterListener
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

LOG_MODIFICATIONS

protected static final boolean LOG_MODIFICATIONS
If true, then modification logging be activated. This is a very expensive option as it causes a stack crawl to be captured for every message modification.

To enable modification tracking, set to true and recompile.

See Also:
Constant Field Values

GLOBAL_TRACKING_ELEMENT

protected static final boolean GLOBAL_TRACKING_ELEMENT
If true, then a tracking element is added to the message. This provides the ability to follow messages throughout the network. If a message has a tracking element then it will be used in the toString representation.

To enable addition of a tracking element, set to true and recompile.

See Also:
Constant Field Values

defaultNamespace

protected final String defaultNamespace
This string identifies the namespace which is assumed when calls are made that don't include a namespace specification.


namespaces

protected transient Map namespaces
the namespaces in this message and the elements in each.


elements

protected transient List elements
List of the elements.


properties

protected transient Map properties
Message properties HashMap


lineage

protected transient List lineage
A list of Integer which details the lineage (history of cloning) that produced this message. This message's number is index 0, all of the ancestors are in order at higher indexes.


modCount

protected transient volatile int modCount
Modification count of this message. Can be used to detect message being modified when message is shared.


cachedByteLength

protected transient long cachedByteLength
cached aggregate size of all the memeber elements. Used by getByteLength()


cachedByteLengthModCount

protected transient int cachedByteLengthModCount
modcount at the time the message length was last calculated. Used by getByteLength()


modifiable

public boolean modifiable
Deprecated. You really should not depend on this feature.
If true then the message is modifiable. This is primarily intended as a diagnostic tool for detecting concurrent modification.


modHistory

protected transient List modHistory
The history of modifications this message.

Constructor Detail

Message

public Message()
Standard Constructor for messages. The default namespace will be the empty string ("")


Message

protected Message(String defaultNamespace)
Standard Constructor for messages.

Parameters:
defaultNamespace - the namespace which is assumed when calls are made that don't include a namespace specification.
Method Detail

getNextMessageNumber

protected static int getNextMessageNumber()
Returns the next message number in sequence.

Returns:
the next message number in sequence.

clone

public Object clone()

Duplicates the Message. The returned duplicate is a real copy. It may be freely modified without causing change to the originally cloned message.

Overrides:
clone in class Object
Returns:
Message a Message that is a copy of the original message

equals

public boolean equals(Object target)

Compare this Message against another. Returns true if all of the elements are identical and in the same order. Message properties (setProperty/getProperty) are not considered in the calculation.

Overrides:
equals in class Object
Parameters:
target - The to compare against.
Returns:
boolean true if the elements are identical.

hashCode

public int hashCode()

Overrides:
hashCode in class Object

toString

public String toString()

Displays the lineage of the message including its own message number. This is useful primarily for debugging purposes.

Overrides:
toString in class Object

getDefaultNamespace

protected String getDefaultNamespace()
Return the default Namespace of this message.

Returns:
The default namespace for this message.

addMessageElement

public void addMessageElement(MessageElement add)
Add a MessageElement into the message. The MessageElement is stored in the default namespace.

Parameters:
add - the Element to add to the message.

addMessageElement

public void addMessageElement(String namespace,
                              MessageElement add)
Add a MessageElement into the message using the specified namespace.

Parameters:
namespace - contains the namespace of the element to add. You can specify null as a shorthand for the default namespace.
add - the MessageElement to add to the message.

replaceMessageElement

public MessageElement replaceMessageElement(MessageElement replacement)
Replace a MessageElement in the message. This method will remove all MessageElement instances in the default namespace which match the specified name (if any) and then insert the replacement element. The existing version of the element is returned, if more than one matching element was removed, a random matching element is returned.

For greatest control over element replacement, use the ListIterator.set(java.lang.Object) method as returned by getMessageElements(), getMessageElements(java.lang.String) or getMessageElementsOfNamespace(java.lang.String)

Parameters:
replacement - the Element to be inserted into to the message.
Returns:
One of the elements which was replaced or null if no existing matching item was located.

replaceMessageElement

public MessageElement replaceMessageElement(String namespace,
                                            MessageElement replacement)
Replace a MessageElement in the message using the specified namespace. This method will remove all MessageElement instances which match the specified name (if any) and then insert the replacement element. The existing version of the element is returned, if more than one matching element was removed, a random matching element is returned.

For greatest control over element replacement, use the ListIterator.set(java.lang.Object) method as returned by getMessageElements(), getMessageElements(java.lang.String) or getMessageElementsOfNamespace(java.lang.String)

Parameters:
namespace - contains the namespace of the element to be replaced. You can specify null as a shorthand for the default namespace.
replacement - the Element to be inserted into to the message.
Returns:
One of the elements which was replaced or null if no existing matching item was located.

getMessageNamespaces

public Iterator getMessageNamespaces()
Returns an iterator of the namespaces present in this message. All of the elements will be Strings.

Returns:
iterator of strings of the namespaces of this message.

getMessageElement

public MessageElement getMessageElement(String name)
Retrieve a element by name from the message without regard to namespace. If there is more than one element with this name, a random element will be returned.

Parameters:
name - The name of the element to attept to retrieve.
Returns:
Element the element or null if no matching element could be found.

getMessageElement

public MessageElement getMessageElement(String namespace,
                                        String name)
Retrieve a element by name in the specified namespace from the message. If there is more than one element with this name, a random element will be returned.

Parameters:
namespace - contains the namespace of the element to get. You can specify null as a shorthand for the default namespace.
name - contains the name of the element to get
Returns:
Element the element.

getMessageElements

public Message.ElementIterator getMessageElements()
Returns a list iterator of all of the elements contained in this message. Elements from all namespaces are returned.

The iterator returned is not synchronized with the message and will throw ConcurrentModificationException if the message is modified.

Returns:
Enumeration of Elements.

getMessageElements

public Message.ElementIterator getMessageElements(String name)
Returns a list iterator of all of the elements contained in this message who's name matches the specified name. Elements from all namespaces are returned. Message Elements are iterated in the order in which they were added to the Message.

The iterator returned is not synchronized with the message and will throw ConcurrentModificationException if the message is modified.

Parameters:
name - the name of the elements to match against
Returns:
iterator of the elements matching the specified name, if any.

getMessageElementsOfNamespace

public Message.ElementIterator getMessageElementsOfNamespace(String namespace)
Returns an list iterator of all of the elements contained in this message which match the specified namespace. Message Elements are iterated in the order in which they were added to the Message.

This ListIterator returned is not synchronized with the message. If you modify the state of the Message, the iterator will throw ConcurrentModificationException when next() or previous() is called.

The iterator returned is not synchronized with the message and will throw ConcurrentModificationException if the message is modified.

Parameters:
namespace - contains the namespace which must be matched in the elements returned. You can specify null as a shorthand for the default namespace.
Returns:
Enumeration of Elements.

getMessageElements

public Message.ElementIterator getMessageElements(String namespace,
                                                  String name)
Returns a list iterator of all of the elements contained in the specified namespace who's name matches the specified name in the order in which they were added to the Message.

The iterator returned is not synchronized with the message and will throw ConcurrentModificationException if the message is modified.

Parameters:
namespace - contains the namespace which must be matched in the elements returned. You can specify null as a shorthand for the default namespace.
name - contains the name of the elements to get
Returns:
Enumeration of Elements.

getMessageElements

public Message.ElementIterator getMessageElements(MimeMediaType type)
Returns a list iterator of all of the elements contained in this message whose mime-type matchs the given in the order they were added to the message. Elements from all namespaces are returned.

The iterator returned is not synchronized with the message and will throw ConcurrentModificationException if the message is modified.

Parameters:
type - contains the type of the elements to get
Returns:
Enumeration of Elements.

getMessageElements

public Message.ElementIterator getMessageElements(String namespace,
                                                  MimeMediaType type)
Returns a list iterator of all of the elements contained in this message whose type matches the given in the order they were added to the message.

The iterator returned is not synchronized with the message and will throw ConcurrentModificationException if the message is modified.

Parameters:
namespace - contains the namespace which must be matched in the elements returned. You can specify null as a shorthand for the default namespace.
type - contains the type of the elements to get
Returns:
Enumeration of Elements.

removeMessageElement

public boolean removeMessageElement(MessageElement remove)
Remove an the first occurance of the provided MessageElement from the message.

Parameters:
remove - the Element to remove from the message.
Returns:
boolean returns true if the element was removed, otherwise false.

removeMessageElement

public boolean removeMessageElement(String namespace,
                                    MessageElement remove)
Remove the first occurance of the provided MessageElement within the specified namespace from the message. You can specify null as a shorthand for the default namespace.

Parameters:
namespace - the namespace from which the element is to be removed.
remove - the Element to remove from the message.
Returns:
boolean returns true if the element was removed, otherwise false.

clear

public void clear()
Removes all of the elements in all namespaces from the message. Also clears any properties set for this message.


getByteLength

public long getByteLength()
Returns the aggregate size of all the memeber elements.

Returns:
the sum of all element sizes in bytes.

getMessageModCount

public int getMessageModCount()
Returns the modification count of this message. This ever ascending number can be used to determine if the message has been modified by another thread or for use in caching of parts of the message structure.

Returns:
the modification count of this message.

incMessageModCount

protected int incMessageModCount()
Returns the modification count of this message. This ever ascending number can be used to determine if the message has been modified by another thread or for use in caching of parts of the message structure.

Returns:
the modification count of this message.

getMessageModHistory

public String getMessageModHistory()
Returns a string containing the modification history for this message

Returns:
a string containing the

getMessageNumber

public int getMessageNumber()
Returns the message number of this message. Message Numbers are intended to assist with debugging and the management of message cloning.

Each message is assigned a unique number upon creation. Message Numbers are monotonically increasing for each message created.

Message Numbers are transient, ie. if the message object is serialized then the message number after deserialization will be probably be a different value. Message numbers should not be used to record permanent relationships between messages.

Returns:
int this message's message number.

getMessageLineage

public Iterator getMessageLineage()
Returns an iterator which describes the lineage of this message. Each entry is an Integer Message Number. The first entry is this message's number, following entries are the ancestors of this message.

Returns:
an Iterator of Integer. Each entry is a message number.

setMessageProperty

public Object setMessageProperty(Object key,
                                 Object value)
Associate a transient property with this message. if there was a previous value for the key provided then it is returned. This feature is useful for managing the state of messages during processing and for caching. Message Properties are not transmitted as part of the Message when the message is serialized!

The setting of particular keys may be controlled by a Java Security Manager. Keys of type 'java.lang.Class' are checked against the caller of this method. Only callers which are instances of the key class may modify the property. This check is not possible through reflection. All other types of keys are unchecked.

Parameters:
key - the property key
value - the value for the property
Returns:
previous value for the property or null if no previous

getMessageProperty

public Object getMessageProperty(Object key)
Retrieves a transient property from the set for this message.

Parameters:
key - the property key.
Returns:
value for the property or null if no property for this key.

itemChanged

public void itemChanged(SimpleSelectable o)
This method is invoked when the given selectable object has changed. This permits to cascade selectable objects, so that one reports a change when the other changes, without having to select it. This Also permits to implement this interface by delegating its implementation to a utility class.

An implementation may do what it wants about it. For example, a SimpleSelector will report the change to SimpleSelector.select() and invoke AbstractSimpleSelectable.notifyChange() thereby reporting its own change to cascaded selectors. Other implementations may only invoke AbstractSimpleSelectable.notifyChange() or may perform more complex tasks

.

Specified by:
itemChanged in interface SimpleSelectable
Parameters:
o - the object that has changed.
See Also:
AbstractSimpleSelectable

JXTA J2SE