net.sf.eBus.messages.type

Class MessageType

java.lang.Object

net.sf.eBus.messages.type.DataType

net.sf.eBus.messages.type.MessageType

All Implemented Interfaces:

java.lang.Comparable<DataType>

public class MessageType
extends DataType

This class provides binary serialization/de-serialization for a unique EMessageObject sub-class. The serialized binary format is:

• EMessageObject class name (serialized as a String).
• 4-byte, signed integer field mask (note this restricts eBus EMessage and EField classes to 31 fields.
• Each field serialized in the order specified by EFieldInfo.fields(). Serialization is done based on the field class.

This eBus data type is able to serialize both its specified EMessageObject class or its sub-class. This allows a EMessage and EField to use an abstract class extending EField as a field and initializing that field with a concrete sub-class. This allows the message/field to support new information without changing the message/field class.

Note: as of eBus 4.4.0, messages are automatically compiled when first used for serialization or de-serialization. This increases the time it takes to send or receive a message the first time. When a message is frequently transmitted, it is recommended that the message class is "compiled" by calling DataType.findType(java.lang.Class) for that message class. So when a message is sent or received the first time, the message compilation is already done.

Author:

Charles Rapp

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MessageType.MessageField Stores a field index, field name, class field, eBus data type.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	_subject EMessage has a public subject field but this field is not serialized because it is include in the message key identifier.
protected static java.util.List<java.lang.Class<? extends EReplyMessage>>	NO_REPLY The default empty reply class array used for non-request message types.

Fields inherited from class net.sf.eBus.messages.type.DataType

_builtinFlag, _class, _classes, _compiledClasses, _defaultValue, ADDRESS_TYPE, ARRAY_SUFFIX, CHARSET, CLASS_TYPE, EMPTY_STRING, FIELD_MASK_SIZE, INDENT, INDENT1, KEY_TYPE, MAX_ARRAY_SIZE, MAX_FIELDS, MAX_FILE_NAME_LENGTH, MAX_STRING_LENGTH, STRING_TYPE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MessageType(java.lang.Class<?> clazz, java.util.List<MessageType.MessageField> fields, java.util.List<java.lang.Class<? extends EReplyMessage>> replies, java.lang.invoke.MethodHandle ctor) Creates a new message type instance for the given class, message fields, and constructor method handle.

Method Summary

Modifier and Type	Method and Description
protected void	createDeserializer(java.lang.String fieldName, java.lang.String indent, java.util.Formatter output) Generates the code to de-serialize the named field from a ByteBuffer.
protected void	createSerializer(java.lang.String fieldName, java.lang.String indent, java.util.Formatter output) Adds the Java code used to serialize the named field to a ByteBuffer.
java.lang.Object	deserialize(java.nio.ByteBuffer buffer) Returns a message object de-serialized from the given buffer.
protected java.lang.Object	deserializeFields(int fieldMask, java.nio.ByteBuffer buffer) Returns an EMessageObject de-serialized from the given buffer.
java.util.List<MessageType.MessageField>	fields() Returns the message object public fields.
boolean	isMessage() Returns true if this message type is for an EMessage and false if for an EField.
boolean	isValidReply(java.lang.Class<?> clazz) Returns true if clazz is listed in the allowed reply message class list and false if not.
java.lang.Object	newInstance(java.lang.Object[] args) Returns the EMessage or EField instance instantiated from the given arguments.
int	numberFields() Returns the number of fields in this EMessage type.
java.util.List<java.lang.Class<? extends EReplyMessage>>	replyTypes() Returns the reply classes associated with a request message class.
void	serialize(java.lang.Object o, java.nio.ByteBuffer buffer) Serializes the message fields to the given the buffer, setting the field mask.
protected int	serializeFields(java.lang.Object o, java.nio.ByteBuffer buffer) Writes the message object fields to the given buffer and returns the resulting field mask.
void	subject(java.lang.String subject) Sets the message subject to the given value.
java.util.List<java.lang.Object>	values(EMessageObject message) Returns the message object's field values as an Object list.

Methods inherited from class net.sf.eBus.messages.type.DataType

compareTo, dataClass, dataClassName, defaultValue, equals, fields, findType, hashCode, isArray, isBuiltin, isEnum, isInstance, isPrimitive, replyClasses, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

_subject

protected java.lang.String _subject

EMessage has a public subject field but this field is not serialized because it is include in the message key identifier. But it must be included in EMessage.EMessage(java.lang.String, long) constructor. This problem is resolved setting the subject via subject(String) before de-serializing the message.

NO_REPLY

protected static final java.util.List<java.lang.Class<? extends EReplyMessage>> NO_REPLY

The default empty reply class array used for non-request message types.

Constructor Detail

MessageType

protected MessageType(java.lang.Class<?> clazz,
                      java.util.List<MessageType.MessageField> fields,
                      java.util.List<java.lang.Class<? extends EReplyMessage>> replies,
                      java.lang.invoke.MethodHandle ctor)

Creates a new message type instance for the given class, message fields, and constructor method handle.

Parameters:

clazz - the message class instance.

fields - the message fields.

replies - reply classes associated with a request message class. Will be an empty array for non-request message types.

ctor - the message class de-serialization constructor.

Method Detail

serialize

public void serialize(java.lang.Object o,
                      java.nio.ByteBuffer buffer)
               throws java.nio.BufferOverflowException

Serializes the message fields to the given the buffer, setting the field mask.

Note: as of eBus 4.4.0, messages are automatically compiled when first used for serialization or de-serialization. This increases the time it takes to send or receive a message the first time. When a message is frequently transmitted, it is recommended that the message class is "compiled" by calling DataType.findType(java.lang.Class) for that message class. So when a message is sent or received the first time, the message compilation is already done.

Specified by:

serialize in class DataType

Parameters:

o - serialize this message object.

buffer - write to this buffer.

Throws:

java.nio.BufferOverflowException - if buffer does not contain sufficient space to store the message.

deserialize

public java.lang.Object deserialize(java.nio.ByteBuffer buffer)
                             throws java.lang.IllegalStateException,
                                    java.nio.BufferUnderflowException,
                                    UnknownMessageException,
                                    InvalidMessageException

Returns a message object de-serialized from the given buffer.

Note: as of eBus 4.4.0, messages are automatically compiled when first used for serialization or de-serialization. This increases the time it takes to send or receive a message the first time. When a message is frequently transmitted, it is recommended that the message class is "compiled" by calling DataType.findType(java.lang.Class) for that message class. So when a message is sent or received the first time, the message compilation is already done.

Specified by:

deserialize in class DataType

Parameters:

buffer - read in the message from this buffer.

Returns:

the de-serialized message.

Throws:

java.lang.IllegalStateException - if subject(String) was not called prior to de-serializing.

java.nio.BufferUnderflowException - if buffer contains an incomplete message.

UnknownMessageException - if the serialized message is unknown to this eBus.

InvalidMessageException - if the message is incorrectly serialized.

createSerializer

protected void createSerializer(java.lang.String fieldName,
                                java.lang.String indent,
                                java.util.Formatter output)

Adds the Java code used to serialize the named field to a ByteBuffer.

Specified by:

createSerializer in class DataType

Parameters:

fieldName - the message field name.

indent - indent the code by this amount.

output - write the code to this formatter.

createDeserializer

protected void createDeserializer(java.lang.String fieldName,
                                  java.lang.String indent,
                                  java.util.Formatter output)

Generates the code to de-serialize the named field from a ByteBuffer.

Specified by:

createDeserializer in class DataType

Parameters:

fieldName - store the de-serialized field in this name.

indent - indent the code by this amount.

output - append the code to this formatter.

isValidReply

public boolean isValidReply(java.lang.Class<?> clazz)

Returns true if clazz is listed in the allowed reply message class list and false if not. In short, returns true if clazz message may be sent in reply to this request message type.

Parameters:

clazz - the reply message class.

Returns:

true if clazz message may be sent in reply to this request message type.

replyTypes

public java.util.List<java.lang.Class<? extends EReplyMessage>> replyTypes()

Returns the reply classes associated with a request message class. Returns a copy of the reply class list. If this message type is not a request, then returns an empty list.

Returns:

reply class list.

isMessage

public boolean isMessage()

Returns true if this message type is for an EMessage and false if for an EField.

Returns:

true if the underlying type is an EMessage.

values

public java.util.List<java.lang.Object> values(EMessageObject message)
                                        throws java.lang.Throwable

Returns the message object's field values as an Object list. The returned list values are in the same order as fields().

Parameters:

message - extract the field values from this message object.

Returns:

message field values.

Throws:

java.lang.Throwable - if any sort of error occurs when extracting the values from message.

numberFields

public int numberFields()

Returns the number of fields in this EMessage type.

Returns:

number of message fields.

fields

public java.util.List<MessageType.MessageField> fields()

Returns the message object public fields.

Returns:

message object fields.

subject

public void subject(java.lang.String subject)
             throws java.lang.IllegalArgumentException

Sets the message subject to the given value. Must be called prior to deserializing the message.

Parameters:

subject - de-serialized message subject.

Throws:

java.lang.IllegalArgumentException - if subject is null or empty.

newInstance

public java.lang.Object newInstance(java.lang.Object[] args)
                             throws java.lang.IllegalArgumentException,
                                    InvalidMessageException

Returns the EMessage or EField instance instantiated from the given arguments. The arguments are expected to contain valid values and be in the correct order as specified by the EFieldInfo annotation.

Parameters:

args - constructor arguments.

Returns:

new message or field object.

Throws:

java.lang.IllegalArgumentException - if args is either null or does not contain the correct number of arguments.

InvalidMessageException - if the instantiation failed.

serializeFields

protected int serializeFields(java.lang.Object o,
                              java.nio.ByteBuffer buffer)
                       throws java.nio.BufferOverflowException

Writes the message object fields to the given buffer and returns the resulting field mask.

As of eBus v. 4.4.0, all EMessageObject classes are automatically "compiled" - meaning that an MessageType-subclass is generated for any given EMessageObject subclass. The MessageType subclass overrides this serializeFields method, meaning this method implementation is never called. Therefore, this method implementation has an empty body and always returns zero.

Parameters:

o - write this EMessageObject's fields to buffer. Note: o is not null.

buffer - serialize fields to this buffer.

Returns:

resulting field mask.

Throws:

java.nio.BufferOverflowException - if buffer does not contain sufficient space to store the message.

deserializeFields

protected java.lang.Object deserializeFields(int fieldMask,
                                             java.nio.ByteBuffer buffer)
                                      throws java.nio.BufferUnderflowException,
                                             UnknownMessageException,
                                             InvalidMessageException

Returns an EMessageObject de-serialized from the given buffer.

As of eBus v. 4.4.0, all EMessageObject classes are automatically "compiled" - meaning that an MessageType-subclass is generated for any given EMessageObject subclass. The MessageType subclass overrides this deserializeFields method, meaning this method implementation is never called. Therefore, this method implementation has an empty body and always returns null.

Parameters:

fieldMask - the message field mask specifying which fields are serialized and which are null.

buffer - read in the message from this buffer.

Returns:

the de-serialized message.

Throws:

java.nio.BufferUnderflowException - if buffer contains an incomplete message.

UnknownMessageException - if the serialized message is unknown to this eBus.

InvalidMessageException - if the message is incorrectly serialized.