raccoon.api.eai.message
Interface IMessage

All Known Subinterfaces:

IBusMessage

All Known Implementing Classes:

RvMessage

public interface IMessage

The common interface for all messages supported by the Raccoon Framework.

Since:

Raccoon v1.0

Version:

$Id: IMessage.java,v 1.1 2004/08/08 20:25:56 crouvrais Exp $

Author:

Cedric ROUVRAIS

Method Summary

void	addMsgField(IField pField) Adds a new field instance to the list of fields.
void	append(java.lang.String pFieldName, boolean pFieldData) Adds to this message a new field that represents a boolean.
void	append(java.lang.String pFieldName, int pFieldData) Adds to this message a new field that represents an int.
void	append(java.lang.String pFieldName, long pFieldData) Adds to this message a new field that represents an long.
void	append(java.lang.String pFieldName, java.lang.Object pFieldData) Adds to this message a new field.
void	append(java.lang.String pFieldName, java.lang.Object pFieldData, int pFieldType, int pFieldId) Adds to this message a new field.
void	append(java.lang.String pFieldName, short pFieldData) Adds to this message a new field that represents a short.
IField	getMsgField(int pFieldId) Retrieves the field according to it's id.
IField	getMsgField(java.lang.String pFieldName) Retrieves the field according to it's name.
IField	getMsgFieldAt(int pIndex) Retrieves the field located at the specified index.
java.util.Collection	getMsgFields() Retrieves the fields attached to this instance.
long	getMsgSize() Retrieves the size of the message in bytes.
java.lang.String	getName() Retrieves the name of this instance.
java.lang.Object	getNativeMsg() Retrieve the native representation of this instance.
long	getSequence() The sequence number of this given message.
java.util.Map	hashMsgFields() Retrieves a Map instance containing the messages fields.
int	nbMsgFields() Retrieves the number of fields attached to this instance.
boolean	removeMsgField(int pFieldID) Removes the field located at the specified index.
boolean	removeMsgField(java.lang.String pFieldName) Removes the first instance of the field by it's name.
boolean	removeMsgFieldAt(int pIndex) Removes the field located at the specified index.
void	setMsgFields(java.util.Collection pFields) Defines the fields attached to this instance.
void	setName(java.lang.String pName) Defines the name of this instance.
void	updateField(java.lang.String pFieldPath, java.lang.Object pNewValue) Updates the content of the given field.

Method Detail

setName

void setName(java.lang.String pName)

Defines the name of this instance.

Parameters:

pName - the name of this instance

getName

java.lang.String getName()

Retrieves the name of this instance.

Returns:

the name.

setMsgFields

void setMsgFields(java.util.Collection pFields)

Defines the fields attached to this instance.

Parameters:

pFields - a collection of IField's

getMsgFields

java.util.Collection getMsgFields()

Retrieves the fields attached to this instance.

Returns:

a collection of IField's

addMsgField

void addMsgField(IField pField)
                 throws java.lang.IllegalArgumentException

Adds a new field instance to the list of fields.

Parameters:

pField - the field instance to append to the list of current fields

Throws:

java.lang.IllegalArgumentException - if the field id is already used by another field and is different from zero.

java.lang.IllegalArgumentException - if the data type is invalid or doesn't correspond to the data.

getMsgField

IField getMsgField(java.lang.String pFieldName)

Retrieves the field according to it's name.

Parameters:

pFieldName - the name of the field

Returns:

the field, null if the field doesn't exist.

getMsgField

IField getMsgField(int pFieldId)
                   throws java.lang.IllegalArgumentException

Retrieves the field according to it's id.

Parameters:

pFieldId - the field ID of the desired field

Returns:

the field or null if the field ID doesn't exist.

Throws:

java.lang.IllegalArgumentException - if the field ID is less than 1.

getMsgFieldAt

IField getMsgFieldAt(int pIndex)
                     throws java.lang.IndexOutOfBoundsException,
                            java.lang.InternalError

Retrieves the field located at the specified index.

Parameters:

pIndex - the position of the field within the message

Returns:

the IField corresponding to the index

Throws:

java.lang.IndexOutOfBoundsException - if the index is greater than the number of fields.

java.lang.InternalError - if the contents of this message are corrupted

See Also:

nbMsgFields()

removeMsgField

boolean removeMsgField(java.lang.String pFieldName)
                       throws java.lang.IllegalArgumentException

Removes the first instance of the field by it's name.

Parameters:

pFieldName - the name of the field that is to be removed.

Returns:

true if the removal was a success, false otherwise (field not found or can't remove).

Throws:

java.lang.IllegalArgumentException - the name of the fieldName is null.

removeMsgFieldAt

boolean removeMsgFieldAt(int pIndex)
                         throws java.lang.IllegalArgumentException

Removes the field located at the specified index.

Parameters:

pIndex - the name of the field that is to be removed.

Returns:

true if the removal was a success, false otherwise.

Throws:

java.lang.IllegalArgumentException - the name of the fiels is null.

removeMsgField

boolean removeMsgField(int pFieldID)
                       throws java.lang.IndexOutOfBoundsException,
                              java.lang.IllegalArgumentException

Removes the field located at the specified index.

By convention a field ID uniquely identifies any given IField element, unless the field ID is equal to zero, in which case the field doesn't have a field ID.

Parameters:

pFieldID - the ID of the field to be removed.

Returns:

true if the removal was a success, false otherwise.

Throws:

java.lang.IndexOutOfBoundsException - if the provided ID is out of range

java.lang.IllegalArgumentException - if the field ID is equal to zero.

hashMsgFields

java.util.Map hashMsgFields()

Retrieves a Map instance containing the messages fields.

Returns:

a Map of IFields where the key is the field name.

append

void append(java.lang.String pFieldName,
            java.lang.Object pFieldData)
            throws java.lang.IllegalArgumentException

Adds to this message a new field.

Parameters:

pFieldName - the name of the field

pFieldData - the data associated to the field

Throws:

java.lang.IllegalArgumentException - if one of the given arguments are invalid.

See Also:

IField.setName(String), IField.setData(Object)

append

void append(java.lang.String pFieldName,
            boolean pFieldData)
            throws java.lang.IllegalArgumentException

Adds to this message a new field that represents a boolean.

Parameters:

pFieldName - the name of the field

pFieldData - the data associated to the field

Throws:

java.lang.IllegalArgumentException - if one of the parameters is invalid

See Also:

IField.setName(String), IField.setData(Object)

append

void append(java.lang.String pFieldName,
            short pFieldData)
            throws java.lang.IllegalArgumentException

Adds to this message a new field that represents a short.

Parameters:

pFieldName - the name of the field

pFieldData - the data associated to the field

Throws:

java.lang.IllegalArgumentException - if one of the parameters is invalid

See Also:

IField.setName(String), IField.setData(Object)

append

void append(java.lang.String pFieldName,
            int pFieldData)
            throws java.lang.IllegalArgumentException

Adds to this message a new field that represents an int.

Parameters:

pFieldName - the name of the field

pFieldData - the data associated to the field

Throws:

java.lang.IllegalArgumentException - if one of the parameters is invalid

See Also:

IField.setName(String), IField.setData(Object)

append

void append(java.lang.String pFieldName,
            long pFieldData)
            throws java.lang.IllegalArgumentException

Adds to this message a new field that represents an long.

Parameters:

pFieldName - the name of the field

pFieldData - the data associated to the field

Throws:

java.lang.IllegalArgumentException - if one of the parameters is invalid

See Also:

IField.setName(String), IField.setData(Object)

append

void append(java.lang.String pFieldName,
            java.lang.Object pFieldData,
            int pFieldType,
            int pFieldId)
            throws java.lang.IllegalArgumentException

Adds to this message a new field.

Parameters:

pFieldName - the name of the field

pFieldData - the data associated to the field

pFieldType - the type of the data associated to the field

pFieldId - the id of the new field to add

Throws:

java.lang.IllegalArgumentException - if one of the given arguments are invalid.

See Also:

IField.setName(String), IField.setData(Object), IField.setType(int), IField.setId(int)

nbMsgFields

int nbMsgFields()

Retrieves the number of fields attached to this instance.

Returns:

the number of IField elements contained by this message

getMsgSize

long getMsgSize()

Retrieves the size of the message in bytes.

Returns:

the size of the native message.

getNativeMsg

java.lang.Object getNativeMsg()

Retrieve the native representation of this instance.

Returns:

the native object that is identical to this instance.

updateField

void updateField(java.lang.String pFieldPath,
                 java.lang.Object pNewValue)

Updates the content of the given field.

Parameters:

pFieldPath - the path to the field.

pNewValue - the new value, must be same type as previous value.

getSequence

long getSequence()

The sequence number of this given message.

Returns:

the sequence number.