ie.ncl.msg
Class Message

java.lang.Object
  ie.ncl.msg.Message

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

BinaryMessage, MMSMessage, TextMessage

public abstract class Message
extends java.lang.Object
implements java.io.Serializable

The Message class is the base class used for all messages in the Generic API. This class is almost concrete except for the methods to get and set the body (content) of the message.

The body object must be defined by the extending class - such as text, bytes or a URL .

It contains the following:-

• attributes - string name and value pairs. Attributes vary from messaging application. Settings for SMS are discussed in the section SMS Attributes.
• type - used to associate a string with a set of attributes
• an ID - used to uniquely identify a message
• source - the source address of the message
• destination - the destination address of the message
• correlation ID - used by applications to associate application specific data (external to the API) with a message.

See Also:

Serialized Form

Constructor Summary

Message()
Create a blank message with an empty attribute set.

Message(Address destination)
Create a new message with a destination address and an empty attribute set.

Message(Message m)
Create a new message from an existing one.

Method Summary

java.lang.Object	getAttribute(java.lang.String name) Convenience routing for retrieving an attribute from the Message's Attributes set.
Attributes	getAttributes() Get the attributes of this message.
abstract java.lang.Object	getBody() Get the message body.
java.lang.Object	getCorrelationID() Get the correlation object.
Address	getDestination() Get the destination address of the message.
java.lang.String	getID() Get a reference number/text for the message.
Address	getSource() Get the source address of the message.
java.lang.String	getType() Get the type of message.
void	putAttribute(java.lang.String name, java.lang.Object object) Convenience routing for adding to the Message's Attributes set.
java.lang.Object	removeAttribute(java.lang.String name) Convenience routing for removing an attribute from the Message's Attributes set.
void	setAttributes(Attributes attrs) Set the properties of this message.
abstract void	setBody(java.lang.Object body) Set the message body.
void	setCorrelationID(java.lang.Object id) Set the correlation object.
void	setDestination(Address dest) Set the destination address of the message.
void	setID(java.lang.String id) Set the reference ID for a sent message.
void	setSource(Address src) Set the source address of the message.
void	setType(java.lang.String type) Set the type of message.

Methods inherited from class java.lang.Object

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

Constructor Detail

Message

public Message()

Create a blank message with an empty attribute set.

Message

public Message(Address destination)

Create a new message with a destination address and an empty attribute set.

See Also:

Address

Message

public Message(Message m)

Create a new message from an existing one. All message data is copied EXCEPT the correlation ID and the message ID. The attribute set of the message is also cloned/copied (not referenced).

See Also:

Message(Message), Attributes.copy()

Method Detail

getBody

public abstract java.lang.Object getBody()

Get the message body. This abstract method (and the type of body e.g. String) is defined by the extending class.

setBody

public abstract void setBody(java.lang.Object body)

Set the message body. This abstract method (and the type of body e.g. String) is defined by the extending class.

getSource

public Address getSource()

Get the source address of the message. This may be null for a sent message.

See Also:

Address

setSource

public void setSource(Address src)

Set the source address of the message. This may be null for a sent message.

See Also:

Address

getDestination

public Address getDestination()

Get the destination address of the message. This may be null for a received message.

See Also:

Address

setDestination

public void setDestination(Address dest)

Set the destination address of the message. This may be null for a received message. TODO ??????????????? sounds werid/confusing

See Also:

Address

getCorrelationID

public java.lang.Object getCorrelationID()

Get the correlation object.

A correlation ID is used to associate application specific data with a message. Example usage would be when a message has been sent successfully on a connection, a callback is called to indicate success/failure and the application can examine the correlation ID to associate this message with its own system. In this case, the correlation ID might be a database index.

Some (but not all) systems may support delivery reports, whereby a 'receipt' message is sent back to the application also containing the correlation ID. An example of such a system is JMS (Java Messaging Service). This however is optional and is NOT guaranteed by the underlying transport.

Note the serialised (byte) length of a correlation object may be restrictive (e.g. if the message is persistent, their may be a limit on the size of the correlation ID).

Correlation IDs MUST be serializable.

The API does not use this field

See Also:

setCorrelationID(java.lang.Object)

setCorrelationID

public void setCorrelationID(java.lang.Object id)

Set the correlation object. See getCorrelationID for more details.

See Also:

getCorrelationID()

getID

public java.lang.String getID()

Get a reference number/text for the message. This is useful for performing further operations on the message without having the details of the message. If the message has not been sent, this will be empty (null), but may still be empty after the message has been sent if the underlying transport does not implement unique message ids.

If delivery reports are supported by the underlying transport, delivery reports must contain the same ID as those set in the corresponding sent message.

See Also:

setID(java.lang.String)

setID

public void setID(java.lang.String id)

Set the reference ID for a sent message. This is useful for performing further operations on the message without having the details of the message (e.g. cancelling the message). If the message has not been sent, this will be empty (null), but may still be empty after the message has been sent if the underlying transport does not implement unique message ids.

If delivery reports are supported by the underlying transport, delivery reports must contain the same ID as those set in the corresponding sent message. TODO should this be discouraged?

See Also:

getID()

setType

public void setType(java.lang.String type)

Set the type of message. The type is a string identifier used to select a set of messaging parameters particular to an underlying transport, rather than setting up an attribute list for each and every message, and for each and every transport.

The underlying transport particulars may include service specific parameters like coding schemes, routing information, message validity and so on.

See Also:

Connection.putTypeDefaults(java.lang.String, ie.ncl.msg.Attributes), getType()

getType

public java.lang.String getType()

Get the type of message. The type is a string identifier used to associate a name with a set of messaging parameters particular to an underlying transport, rather than setting up an attribute list for each and every message, and for each and every transport.
The underlying transport particulars may include service specific parameters like coding schemes, routing information, message validity and so on.

When a message is sent that has a type that matches one configured in the underlying transport, then that set of default attributes are used.

See Also:

Connection.putTypeDefaults(java.lang.String, ie.ncl.msg.Attributes), setType(java.lang.String)

getAttributes

public Attributes getAttributes()

Get the attributes of this message. Attributes are transport dependant. Example of transports are the mail transfer protocol SMTP (Simple Mail Transfer Protocol) and the SMS transfer protocol SMPP (Short Message Peer to Peer protocol).

See Also:

setAttributes(ie.ncl.msg.Attributes)

setAttributes

public void setAttributes(Attributes attrs)

Set the properties of this message. Attributes are transport dependant. Example of transports are the mail transfer protocol SMTP (Simple Mail Transfer Protocol) and the SMS transfer protocol SMPP (Short Message Peer to Peer protocol).

See Also:

getAttributes()

putAttribute

public void putAttribute(java.lang.String name,
                         java.lang.Object object)

Convenience routing for adding to the Message's Attributes set. If the attribute is already present it will be replaced with the object paramater. See the Attributes object for more details

See Also:

Attributes.put(java.lang.String, java.lang.String)

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Convenience routing for retrieving an attribute from the Message's Attributes set. See the Attributes object for more details

Returns:

The object that has been removed or null if it was not present.

See Also:

Attributes.get(java.lang.String)

removeAttribute

public java.lang.Object removeAttribute(java.lang.String name)

Convenience routing for removing an attribute from the Message's Attributes set. See the Attributes object for more details

See Also:

Attributes.remove(java.lang.String)