net.jxta.endpoint
Interface Message

public interface Message

Message defines the interface of messages sent or received to or from an endpoint and pipes. Applications are expected to use this interface in order to exchange messages.

A Message is an object that can be sent or received using the EndpointService API or the PipeService API.

A message contains a set MessageElements.

See Also:

MessageElement, EndpointAddress, EndpointService, InputPipe, OutputPipe, PipeService

Method Summary

void	addElement(MessageElement add) Add a MessageElement into the message.
java.lang.Object	clone() Deep copy of message.
boolean	equals(java.lang.Object o) Check if two message are equals
byte[]	getBytes(java.lang.String qname) get the named element from the message and return the element's byte array.
EndpointAddress	getDestinationAddress() Get the desitnation address from the message.
MessageElement	getElement(java.lang.String name) Retrieve a element by name from the message
MessageElementEnumeration	getElements() Returns an enumeration of all of the elements contained in this message.
StringEnumeration	getNames() Return a StringEnumeration for all the message element names in this message.
java.util.Enumeration	getNamespaces() Return an Enumeration of all namespace names used in this message.
long	getRawSize() Return the raw size of the message.
EndpointAddress	getSourceAddress() Get the source address from the message.
java.lang.String	getString(java.lang.String elementName) Get the element from the message as a string.
boolean	hasElement(java.lang.String nsname) Chck for a message element with the given name.
MessageElement	newMessageElement(java.lang.String name, MimeMediaType type, byte[] b) Create a new Element, but dont add it to the message.
MessageElement	newMessageElement(java.lang.String name, MimeMediaType type, byte[] b, int offset, int len) Create a new Element, but dont add it to the message.
MessageElement	newMessageElement(java.lang.String name, MimeMediaType type, java.io.InputStream in) Create a new MessageElement, but dont add it to the message.
MessageElement	newMessageElement(java.lang.String name, MimeMediaType type, java.io.InputStream in, int len) Create a new Element, but dont add it to the message.
boolean	removeElement(MessageElement remove) Remove an element from a message.
MessageElement	removeElement(java.lang.String name) Remove an element from a message by its name.
void	setBytes(java.lang.String name, byte[] bytes) Create or replace a MessageElement using the given namespace and name.
void	setBytes(java.lang.String name, byte[] bytes, int offset, int len) Create or replace an element and add it to the message.
void	setDestinationAddress(EndpointAddress dstAddress) Set the destination address on to the message.
void	setSourceAddress(EndpointAddress srcAddress) Set the source address on to the message.
void	setString(java.lang.String elementName, java.lang.String s) Set the string on to the message.

Method Detail

newMessageElement

public MessageElement newMessageElement(java.lang.String name,
                                        MimeMediaType type,
                                        java.io.InputStream in)
                                 throws java.io.IOException

Create a new MessageElement, but dont add it to the message.

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"

in - the stream containing the body of the Element. The stream will be closed by the Element.

Returns:

MessageElement new Message Element.

Throws:

NullPointerException - if name or InputStream are null.

newMessageElement

public MessageElement newMessageElement(java.lang.String name,
                                        MimeMediaType type,
                                        java.io.InputStream in,
                                        int len)
                                 throws java.io.IOException

Create a new Element, but dont add it to the message.

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"

in - the stream containing the body of the Element. If the stream does not support the "mark" operation then a copy of the stream contents is made immediately. The stream will NOT be closed by the Element.

len - The size of the Element will be limited to len bytes from the stream. If you are using the stream interface and know the size of the stream, specifying it here improves performance and space effciency a lot.

Returns:

MessageElement new Message Element.

Throws:

NullPointerException - if name or InputStream are null.

Since:

JXTA 1.0

newMessageElement

public MessageElement newMessageElement(java.lang.String name,
                                        MimeMediaType type,
                                        byte[] b,
                                        int offset,
                                        int len)

Create a new Element, but dont add it to the message. The contents of the byte array are not copied.

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"

b - A byte array containing the contents of this element.

offset - all bytes before this location in b will be ignored.

Returns:

MessageElement new Message Element.

Throws:

NullPointerException - if name or b are null.

IndexOutOfBoundsException - if offset is negative or greater than or equal to the length of b

Since:

JXTA 1.0

newMessageElement

public MessageElement newMessageElement(java.lang.String name,
                                        MimeMediaType type,
                                        byte[] b)

Create a new Element, but dont add it to the message. The contents of the byte array are not copied.

Parameters:

name - Name of the Element. May be null if the Element is not named.

type - Type of the Element. null is equivalent to specifying the type "Application/Octet-stream"

b - A byte array containing the contents of this element.

offset - all bytes before this location in b will be ignored.

Returns:

MessageElement new Message Element.

Throws:

NullPointerException - if name or b are null.

IndexOutOfBoundsException - if offset is negative or greater than or equal to the length of b

Since:

JXTA 1.0

getRawSize

public long getRawSize()

Return the raw size of the message. That is roughly the size of the data that came in from the network, disregarding elements that may have been added or replaced after that. The result is meaningfull only before elements are manipulated in such a way.

Returns:

long the size

Since:

JXTA 1.0

addElement

public void addElement(MessageElement add)

Add a MessageElement into the message.

Parameters:

add - the Element to add to the message.

Since:

JXTA 1.0

hasElement

public boolean hasElement(java.lang.String nsname)

Chck for a message element with the given name.

Parameters:

nsname - name of the message element to search for.

Returns:

boolean true if the element is present, flase otherwise.

getElement

public MessageElement getElement(java.lang.String name)

Retrieve a element by name from the message

Parameters:

nsname - name of the message element to search for.

Returns:

MessageElement the element.

Since:

JXTA 1.0

getElements

public MessageElementEnumeration getElements()

Returns an enumeration of all of the elements contained in this message. Elements from all namespaces are returned.

The Enumeration returned is not synchronized with the message. If you modify the state of the Message, the enumeration will not reflect your changes.

Same as getElementsInLifoOrder().

Returns:

Enumeration of Elements.

Since:

JXTA 1.0

getNames

public StringEnumeration getNames()

Return a StringEnumeration for all the message element names in this message.

Returns:

StringEnumeration StringEnumeration of the names of the Message Element contained the message.

removeElement

public boolean removeElement(MessageElement remove)

Remove an element from a message.

Parameters:

remove - the Element to remove from the message.

Returns:

boolean returns true if the element was removed, otherwise false.

Since:

JXTA 1.0

removeElement

public MessageElement removeElement(java.lang.String name)

Remove an element from a message by its name.

Parameters:

name - name of the Element to remove from the message.

Returns:

MessageElement removed Message Element, or null if there was no MessageElement to removed.

Since:

JXTA 1.0

setBytes

public void setBytes(java.lang.String name,
                     byte[] bytes)

Create or replace a MessageElement using the given namespace and name. The contents of the element is given by the byte array passed in.

setBytes

public void setBytes(java.lang.String name,
                     byte[] bytes,
                     int offset,
                     int len)

Create or replace an element and add it to the message. The namespace and name of the element are as defined by the arguments of the same name. The value of the element is set form the InputStream.

Parameters:

name - Name of the new element.

bytes - byte array which defines the value of the element.

offset - Start location in byte array.

len - Length of byte array segment startin at offset.

getBytes

public byte[] getBytes(java.lang.String qname)

get the named element from the message and return the element's byte array.

Note that the element is not removed from the message post: offset == 0. len == bytes.length.

Parameters:

qname - name of the element to get.

Returns:

byte[] the element byte array.

getNamespaces

public java.util.Enumeration getNamespaces()

Return an Enumeration of all namespace names used in this message.

Returns:

Enumeration of all namespaces used in this message.

clone

public java.lang.Object clone()

Deep copy of message.

Overrides:

clone in class java.lang.Object

Returns:

Object a Message that is a copy of the original message

Since:

JXTA 1.0

equals

public boolean equals(java.lang.Object o)

Check if two message are equals

Overrides:

equals in class java.lang.Object

Parameters:

o - is a Message object to compare with.

Returns:

boolean returns true if both messages are equal, otherwise returns false.

getSourceAddress

public EndpointAddress getSourceAddress()

Get the source address from the message. The element is named "jxta:EndpointSourceAddress". If the element is not present return null.

Convenience method.

Returns:

EndpointAddress esource address, or null if not present.

getDestinationAddress

public EndpointAddress getDestinationAddress()

Get the desitnation address from the message. The element is named "jxta:EndpointDestinationAddress". If the element is not present return null.

Convenience method.

Returns:

EndpointAddress destination address, or null if not present.

setSourceAddress

public void setSourceAddress(EndpointAddress srcAddress)

Set the source address on to the message. The element is named ""jxta:EndpointSourceAddress".

Convenience method.

Parameters:

srcAddress - EndpointAddress of the source of the message.

setDestinationAddress

public void setDestinationAddress(EndpointAddress dstAddress)

Set the destination address on to the message. The element is named "jxta:EndpointDestinationAddress".

Convenience method.

Parameters:

dstAddress - EndpointAddress of the destination of the message.

setString

public void setString(java.lang.String elementName,
                      java.lang.String s)

Set the string on to the message.

Convenience method.

Parameters:

elementName - name of the element that will contain the String

s - content of the Message Element.

getString

public java.lang.String getString(java.lang.String elementName)

Get the element from the message as a string.

Returns:

the string, or null if the element is not present.

Convenience method.