JXTA

net.jxta.endpoint
Class MessageElement

java.lang.Object
  extended by net.jxta.endpoint.MessageElement
All Implemented Interfaces:
Document, DocumentStreamIO
Direct Known Subclasses:
ByteArrayMessageElement, InputStreamMessageElement, TextMessageElement

public abstract class MessageElement
extends Object
implements Document

JXTA Message Elements are used to add data to a JXTA Message. Message Elements are immutable objects. A Message Element may be shared amongst as many messages as is desired.

Several Message Element sub-classes are provided for handling various types of data. All Message Elements are internally converted to raw bytes when sent as part of a Message. The various Message Element flavors are provided for convenience and efficiency. They enable the simplest creation and most efficient conversion from the individual data types to the appropriate binary data. Because Message Elements are merely a convenient representation for binary data the object type of Message Element received by a peer may not be the same as was sent by the sending peer. Even though the Message Element container may change during transmission the data contained in the Message Element is faithfully preserved.

A Message Element is composed of four components:

The data contained within a MessageElement is accessible in four ways:

See Also:
Message

Field Summary
protected  long cachedGetByteLength
          cached result of getByteLength() operation.
protected  SoftReference<byte[]> cachedGetBytes
          cached result of getBytes(boolean) operation.
protected  SoftReference<String> cachedToString
          cached result of toString() operation.
protected  String name
          The name of this element.
protected  MessageElement sig
          The optional element which digitally signs or digests this element.
protected  MimeMediaType type
          The type of this element.
 
Constructor Summary
protected MessageElement(String name, MimeMediaType type, MessageElement sig)
          Internal constructor for initializing everything but the data.
 
Method Summary
 MessageElement clone()
          Deprecated. Since Message Elements are immutable this method does nothing useful.
protected static void copyInputStreamToOutputStream(InputStream source, OutputStream sink)
          Copies an input stream to an output stream with buffering.
 boolean equals(Object target)
          

Elements are considered equal if they have the same name, type and signatures.

 long getByteLength()
          Returns the size of the element data in bytes.
 byte[] getBytes(boolean copy)
          Returns a byte array which contains the element data.
 String getElementName()
          Returns the name of the MessageElement.
 Object getElementProperty(Object key)
          Retrieves a transient property from the set for this element.
 String getFileExtension()
          Returns the file extension type used by this Document.
 MimeMediaType getMimeType()
          Returns the MIME Media type of this Document per IETF RFC 2046 MIME : Media Types.
static String getSequentialName()
          Returns a string containing a pseudo-random unique string.
 MessageElement getSignature()
          Returns the element containing the digest/digital signature for this element
static String getUniqueName()
          Returns a pseudo-random unique string which can be used as an element name.
 int hashCode()
          
 void sendToStream(OutputStream sendTo)
          Send the contents of this Document to the specified stream.
 Object setElementProperty(Object key, Object value)
          Associate a transient property with this element.
 String toString()
          

Returns a String representation of the element data.

 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface net.jxta.document.DocumentStreamIO
getStream
 

Field Detail

name

protected final String name
The name of this element. May be the empty string ("") if the element is unnamed.


type

protected final MimeMediaType type
The type of this element.


sig

protected final MessageElement sig
The optional element which digitally signs or digests this element. If null then the element is has no signature element.


cachedGetByteLength

protected transient long cachedGetByteLength
cached result of getByteLength() operation.


cachedGetBytes

protected transient SoftReference<byte[]> cachedGetBytes
cached result of getBytes(boolean) operation.


cachedToString

protected transient SoftReference<String> cachedToString
cached result of toString() operation.

Constructor Detail

MessageElement

protected MessageElement(String name,
                         MimeMediaType type,
                         MessageElement sig)
Internal constructor for initializing everything but the data.

Parameters:
name - Name of the Element. May be the empty string ("") if the Element is not named.
type - Type of the Element. null is equivalent to specifying the type "Application/Octet-stream"
sig - optional message digest/digital signature element. If no signature is to be specified, pass null.
Method Detail

getUniqueName

public static String getUniqueName()
Returns a pseudo-random unique string which can be used as an element name.

Returns:
String containing a pseudo-random value

getSequentialName

public static String getSequentialName()
Returns a string containing a pseudo-random unique string. The result of String.compare() will be consistent with the order in which results were returned from this function.

Security Consideration : Be aware that the pseudo random portion of the names generated by this string are shared amongst all peer groups running in the same classloader. You may be at a risk for loss of anonymity if you use the element names produced in more than one peer group.

Returns:
String containing a pseudo-random value. The result of String.compare() will be consistent with the order in which results were returned from this function.

clone

@Deprecated
public final MessageElement clone()
Deprecated. Since Message Elements are immutable this method does nothing useful.

Overrides:
clone in class Object

equals

public boolean equals(Object target)

Elements are considered equal if they have the same name, type and signatures. Element data is not considered by this implementation as it is mostly intended for subclass use.

Overrides:
equals in class Object

hashCode

public int hashCode()

Overrides:
hashCode in class Object

toString

public String toString()

Returns a String representation of the element data. The 'charset' parameter of the message element's mimetype, if any, is used to determine encoding. If the charset specified is unsupported then the default encoding will be used.

synchronized for caching purposes.

Overrides:
toString in class Object

getElementName

public String getElementName()
Returns the name of the MessageElement. Unnamed elements will return the empty string ("");

Returns:
String containing the name of the MessageElement.

getMimeType

public MimeMediaType getMimeType()
Returns the MIME Media type of this Document per IETF RFC 2046 MIME : Media Types.

JXTA does not currently support the 'Multipart' or 'Message' media types.

Will return "Application/Octet-Stream" if no type was originally specified.

Specified by:
getMimeType in interface Document
Returns:
The MIME Media Type for this Document.

getFileExtension

public String getFileExtension()
Returns the file extension type used by this Document. This value is usually chosen based upon the MIME Media Type.

We use the "unknown" extension and leave it to sub-classes to extend this. If we had a mailcap facility we could do better classification based on mimetype.

Specified by:
getFileExtension in interface Document
Returns:
An appropriate file extension for this Document.

getByteLength

public long getByteLength()
Returns the size of the element data in bytes.

Returns:
long containing the size of the element data.

getBytes

public byte[] getBytes(boolean copy)
Returns a byte array which contains the element data. The byte array returned may be shared amongst all copies of the element, do not modify it. The copy parameter allows you to request a private, modifiable copy of the element data.

This implementation builds the byte array from the stream.

Parameters:
copy - If true then the result can be modified without damaging the state of this MessageElement. If false, then the result may be a shared copy of the data and should be considered read-only.
Returns:
byte[] Contents of message element.

sendToStream

public void sendToStream(OutputStream sendTo)
                  throws IOException
Send the contents of this Document to the specified stream.

This version probably has sub-optimal performance. Sub-classes should override this implementation.

Specified by:
sendToStream in interface DocumentStreamIO
Parameters:
sendTo - The OutputStream to which the Document will be written.
Throws:
IOException - For errors while writing the Document.

getSignature

public MessageElement getSignature()
Returns the element containing the digest/digital signature for this element

Returns:
Element containing the digital signature.

setElementProperty

public Object setElementProperty(Object key,
                                 Object value)
Associate a transient property with this element. If there was a previous value for the key provided then it is returned.

Element properties are useful for managing the state of element during processing. Element properties are not transmitted with the message element when the message element is sent as part of a message.

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

getElementProperty

public Object getElementProperty(Object key)
Retrieves a transient property from the set for this element.

Element properties are useful for managing the state of element during processing. Element properties are not transmitted with the message element when the message element is sent as part of a message.

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

copyInputStreamToOutputStream

protected static void copyInputStreamToOutputStream(InputStream source,
                                                    OutputStream sink)
                                             throws IOException
Copies an input stream to an output stream with buffering.

Parameters:
source - The stream to copy from.
sink - The stream to send the data to.
Throws:
IOException - if there is a problem copying the data

JXSE