jarol.messages
Class MessageFactory

java.lang.Object
  extended by 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