jarol.messages
Class MessageFactory

java.lang.Object
  jarol.messages.MessageFactory

public abstract class MessageFactory
extends java.lang.Object

Message factory interface.

Each application message should define its own. It defines factory methods to instantiate messages, message headers and footer.

Version:

0.1

Author:

Eduardo Marques

Field Summary

java.nio.ByteOrder	BYTE_ORDER Byte order used by this factory.
int	FOOTER_SIZE Footer size for messages of this factory (0 if a message factory uses no footers)
int	HEADER_SIZE Header size for messages of this factory (0 if a message factory uses no headers)
SerializationHandle	slzHandle Checksum procedure If null, no checksum is performed and considered for message footers.

Constructor Summary

protected

MessageFactory(int headerSize, int footerSize, java.nio.ByteOrder byteOrder, SerializationHandle slzHandle) Constructor

Method Summary

abstract void	checkMessageType(Message msg) Abstract method that tests if this message is handled by this factory or not.
Message	fromDataArray(byte[] data)
abstract MessageFooter	newFooter() Footer instance factory method.
abstract MessageHeader	newHeader() Header instance factory method.
abstract Message	newMessage(int id) Message creation by serial id.
abstract Message	newMessage(java.lang.String name) Message creation by name.
void	serialize(Message msg, byte[] buf) Equivalent to 'factory.serialize(msg,buf,0,buf.length)'.
void	serialize(Message msg, byte[] buf, int off, int len) Method to serialize a message onto an array of bytes.
byte[]	toByteArray(Message msg) Convert message to byte array.
Message	unserialize(byte[] buf) Convenience deserialization method for when buffer offset is 0 and usable length equals the buffer's length.
Message	unserialize(byte[] buf, int off, int len) Method to deserialize messages from an array of bytes.

Methods inherited from class java.lang.Object

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

Field Detail

HEADER_SIZE

public final int HEADER_SIZE

Header size for messages of this factory (0 if a message factory uses no headers)

FOOTER_SIZE

public final int FOOTER_SIZE

Footer size for messages of this factory (0 if a message factory uses no footers)

BYTE_ORDER

public final java.nio.ByteOrder BYTE_ORDER

Byte order used by this factory.

slzHandle

public final SerializationHandle slzHandle

Checksum procedure If null, no checksum is performed and considered for message footers.

Constructor Detail

MessageFactory

protected MessageFactory(int headerSize,
                         int footerSize,
                         java.nio.ByteOrder byteOrder,
                         SerializationHandle slzHandle)

Constructor

Parameters:

headerSize - header size

footerSize - footer size

byteOrder - byte order to use (BIG_ENDIAN or LITTLE_ENDIAN)

slzHandle - SerializationHandle instance

Method Detail

newMessage

public abstract Message newMessage(int id)
                            throws InvalidMessageException

Message creation by serial id.

Parameters:

id - Message serial id

Returns:

new message instance

Throws:

InvalidMessageException - when the id supplied is invalid

newMessage

public abstract Message newMessage(java.lang.String name)
                            throws InvalidMessageException

Message creation by name.

Parameters:

name - Message name

Returns:

new message instance

Throws:

InvalidMessageException - when the name supplied is invalid

checkMessageType

public abstract void checkMessageType(Message msg)
                               throws InvalidMessageException

Abstract method that tests if this message is handled by this factory or not. This could be implemented by reflection but is not so that can be deployed more generically. Overrides of this method are typically expressed for each message set using 'instanceof' for the specific message set.

Parameters:

msg - Message

Throws:

InvalidMessageException - if the message is not handled by this factory.

serialize

public void serialize(Message msg,
                      byte[] buf)
               throws InvalidMessageException

Equivalent to 'factory.serialize(msg,buf,0,buf.length)'. See serialize variant with offset and length parameters.

Throws:

InvalidMessageException

serialize

public void serialize(Message msg,
                      byte[] buf,
                      int off,
                      int len)
               throws InvalidMessageException

Method to serialize a message onto an array of bytes.

Parameters:

msg - the message

buf - the output buffer

off - the output buffer offset

len - the usable length of the output buffer (with at least HEADER_SIZE+msg.serialSize()+FOOTER_SIZE capacity)

Throws:

InvalidMessageException - if the message is not handled by this message factory, or is invalid according to the Message.validate() method

BufferException - if the given buffer has less than the required space (this is an instance of RuntimeException)

unserialize

public Message unserialize(byte[] buf)
                    throws InvalidMessageException

Convenience deserialization method for when buffer offset is 0 and usable length equals the buffer's length. 'Message msg = fact.unserialize(buf)' is equivalent to 'Message msg=fact.unserialize(buf,0,buf.length);

Throws:

InvalidMessageException

unserialize

public Message unserialize(byte[] buf,
                           int off,
                           int len)
                    throws InvalidMessageException

Method to deserialize messages from an array of bytes.

Parameters:

buf - the source buffer

off - the source buffer offset

len - the source buffer usable length

Returns:

unserialized message

Throws:

InvalidMessageException - if a message was found invalid (according to validate() method or if checksum fails)

newHeader

public abstract MessageHeader newHeader()

Header instance factory method. It should return null if the message set defines no headers.

Returns:

new MessageHeader instance

newFooter

public abstract MessageFooter newFooter()

Footer instance factory method. It should return null if the message set defines no headers.

Returns:

new MessageFooter instance

toByteArray

public byte[] toByteArray(Message msg)
                   throws InvalidMessageException

Convert message to byte array.

Parameters:

msg - message to convert

Returns:

byte array containing serialized message

Throws:

InvalidMessageException

fromDataArray

public Message fromDataArray(byte[] data)
                      throws InvalidMessageException

Throws:

InvalidMessageException