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:

Comparable<DataType>

Direct Known Subclasses:

AbstractMessageType, ConcreteMessageType, LocalMessageType

public abstract 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 field size and field name. 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
static String	BUILD_INNER_CLASS EMessageObject subclasses must have an inner class names "Builder" if the subclass has any fields.
static String	BUILDER_METHOD EMessageObject concrete subclass must have a public static method named "builder" which takes no arguments and returns an object which extends EMessageObject.Builder.
protected List<MessageType.MessageField>	mFields The message field names and types.
protected List<Class<? extends EReplyMessage>>	mReplyClasses If this a request message type, then this array specifies the reply messages which may be sent in reply to the request class.
protected String	mSubject EMessage has a public subject field but this field is not serialized because it is include in the message key identifier.
static int	PUBLIC_FINAL Message fields must be public and final.
static int	PUBLIC_STATIC The "builder" method must be public and static.
static String	SUBJECT_FIELD Ignore the "subject" message field.

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

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, mBuiltinFlag, mClass, mDefaultValue, mSize, sClasses, sCompiledClasses, STRING_TYPE, VARIABLE_SIZE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MessageType(Class<?> clazz, List<MessageType.MessageField> fields, List<Class<? extends EReplyMessage>> replies) 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 Object	deserializeFields(int fieldMask, ByteBuffer buffer) Returns an EMessageObject de-serialized from the given buffer.
List<MessageType.MessageField>	fields() Returns the message object public fields.
protected static List<MessageType.MessageField>	findFields(Class<? extends EMessageObject> mc) Returns the public final, non-static fields (except EMessage.subject).
boolean	isValidReply(Class<?> clazz) Returns true if clazz is listed in the allowed reply message class list and false if not.
int	numberFields() Returns the number of fields in this EMessage type.
List<Class<? extends EReplyMessage>>	replyTypes() Returns the reply classes associated with a request message class.
protected int	serializeFields(Object o, ByteBuffer buffer) Writes the message object fields to the given buffer and returns the resulting field mask.
void	subject(String subject) Sets the message subject to the given value.
List<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, createDeserializer, createSerializer, dataClass, dataClassName, defaultValue, deserialize, equals, fields, findCharset, findType, hashCode, isArray, isBuiltin, isEnum, isInstance, isLocalOnly, isMessage, isPrimitive, replyClasses, serialize, size, toString

Methods inherited from class java.lang.Object

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

Field Detail

BUILDER_METHOD

public static final String BUILDER_METHOD

EMessageObject concrete subclass must have a public static method named "builder" which takes no arguments and returns an object which extends EMessageObject.Builder.

See Also:

Constant Field Values

BUILD_INNER_CLASS

public static final String BUILD_INNER_CLASS

EMessageObject subclasses must have an inner class names "Builder" if the subclass has any fields.

See Also:

Constant Field Values

PUBLIC_STATIC

public static final int PUBLIC_STATIC

The "builder" method must be public and static.

See Also:

Constant Field Values

PUBLIC_FINAL

public static final int PUBLIC_FINAL

Message fields must be public and final.

See Also:

Constant Field Values

SUBJECT_FIELD

public static final String SUBJECT_FIELD

Ignore the "subject" message field.

See Also:

Constant Field Values

mFields

protected final List<MessageType.MessageField> mFields

The message field names and types. The list ordering defines serialization order and, therefore, is significant. That is why a map cannot be used to match field names to field instances.

mReplyClasses

protected final List<Class<? extends EReplyMessage>> mReplyClasses

If this a request message type, then this array specifies the reply messages which may be sent in reply to the request class.

mSubject

protected String mSubject

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.

Constructor Detail

MessageType

protected MessageType(Class<?> clazz,
                      List<MessageType.MessageField> fields,
                      List<Class<? extends EReplyMessage>> replies)

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.

Method Detail

isValidReply

public boolean isValidReply(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 List<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.

values

public List<Object> values(EMessageObject message)
                    throws 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:

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 List<MessageType.MessageField> fields()

Returns the message object public fields.

Returns:

message object fields.

subject

public void subject(String subject)
             throws IllegalArgumentException

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

Parameters:

subject - de-serialized message subject.

Throws:

IllegalArgumentException - if subject is null or empty.

serializeFields

protected int serializeFields(Object o,
                              ByteBuffer buffer)
                       throws 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:

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

deserializeFields

protected Object deserializeFields(int fieldMask,
                                   ByteBuffer buffer)
                            throws BufferUnderflowException,
                                   UnknownMessageException,
                                   ValidationException

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:

BufferUnderflowException - if buffer contains an incomplete message.

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

ValidationException - if the message is incorrectly serialized.

findFields

protected static List<MessageType.MessageField> findFields(Class<? extends EMessageObject> mc)

Returns the public final, non-static fields (except EMessage.subject). The returned fields are sorted by field name and field length with longer fields preceding shorter fields. Two fields of the same length are further sorted lexicographically by field name.

Parameters:

mc - message object subclass.

Returns:

message fields.