pt.lsts.imc

Class IMCDefinition

java.lang.Object

pt.lsts.imc.IMCDefinition

All Implemented Interfaces:

IMessageProtocol<IMCMessage>

public class IMCDefinition
extends java.lang.Object
implements IMessageProtocol<IMCMessage>

This class loads and holds an IMC definition (XML) and allows creation of compatible messages (factory), parsing and serialization

Author:

zp

Constructor Summary

Constructors

Constructor and Description
IMCDefinition(java.io.File f) Create a new IMCDefinition, loading the definitions from f
IMCDefinition(java.io.InputStream is) Create a new IMCDefinition, loading the XML definitions from the given InputStream

Method Summary

Modifier and Type	Method and Description
<T extends IMCMessage> T	create(java.lang.Class<T> clazz, java.lang.Object... values)
IMCMessage	create(java.lang.String name, java.lang.Object... values) Create a new message and fills it with given values
Header	createHeader() Create a new header compatible with these definitions
java.lang.Object	deserialize(IMCFieldType type, java.io.DataInput in, java.lang.String context)
void	deserializeFields(IMCMessage message, java.io.DataInput in)
java.lang.String	dumpPayload(IMCMessage message, int numTabs)
java.util.Collection<java.lang.String>	getAbstractMessages()
java.lang.String	getAuthor() Retrieve the definitions' author names found on the XML
java.util.Collection<java.lang.String>	getConcreteMessages()
java.lang.String	getCreation() Retrieve the creation date found on these definitions' XML
IMCMessageType	getHeaderType()
static IMCDefinition	getInstance() Retrieve (possibly reusing) default definitions
static IMCDefinition	getInstance(java.io.InputStream isDefinitions) Load the XML on the given InputStream and changes the default instance to this
java.lang.String	getLongName() Retrieve the definitions' long name found on the XML
java.lang.String	getMd5String() Retrieve the generated MD5 hash for these definitions
int	getMessageCount()
int	getMessageId(java.lang.String name)
java.lang.String	getMessageName(int id)
java.util.Collection<java.lang.String>	getMessageNames()
java.lang.String	getName() Retrieve the definitions' name found on the XML
IMCAddressResolver	getResolver() Retrieve this definition's address resolver
long	getSwappedWord() Retrieve the swapped (little endian) synchronization word of this IMC definition
long	getSyncWord() Retrieve the Synchronization word of this IMC definition
IMCMessageType	getType(java.lang.Integer id) Retrieve the message type of given message id
IMCMessageType	getType(java.lang.String name) Retrieve the message type of given message abbreviated name
java.lang.String	getVersion() Retrieve the version found on these definitions' XML
int	headerLength() Retrieve the header length in this IMC version
static void	main(java.lang.String[] args)
boolean	messageExists(java.lang.String name) Verify if a message with given abbreviated name exists in these definitions
java.lang.String	name()
IMCMessage	newMessage(int id)
IMCMessage	newMessage(java.lang.String name)
IMCMessage	nextMessage(java.nio.ByteBuffer buff) Retrieve the next message from the buffer
IMCMessage	nextMessage(IMCInputStream input) Retrieve the next message from the given IMCInputStream
IMCMessage	nextMessage(java.io.InputStream in) Retrieve the next message in the given InputStream.
IMCMessage	nextMessageOfType(int type, java.nio.ByteBuffer buff) Retrieve the next message of given type from current position in the buffer
IMCMessage	parseMessage(byte[] data) Create and retrieve an IMCMessage that is serialized in an array of bytes
void	readHeader(IMCInputStream iis, IMCMessage header) Read a message header from the given IMCInputStream
IMCMessage	replicate(IMCMessage msg)
int	serializationSize(IMCMessage msg)
void	serialize(IMCMessage m, IMCOutputStream os) Serialize the given message to an IMCOutputStream
void	serialize(IMCMessage m, java.io.OutputStream os)
int	serializeFields(IMCMessage message, IMCOutputStream out)
java.util.Collection<java.lang.String>	subtypesOf(java.lang.String msgAbbrev)
IMCMessage	unserialize(java.io.InputStream is)
java.lang.String	version() Retrieve the version found on these definitions' XML
static java.lang.String	versionOfFile(java.io.File f) Utility method to retrieve the IMC version of a given file with XML defitions
static void	writeDefaultDefinitions(java.io.File destination)

Methods inherited from class java.lang.Object

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

Constructor Detail

IMCDefinition

public IMCDefinition(java.io.File f)
              throws java.lang.Exception

Create a new IMCDefinition, loading the definitions from f

Parameters:

f - The file from where to read the definitions.

Throws:

java.lang.Exception - In case there are problems reading the file.

IMCDefinition

public IMCDefinition(java.io.InputStream is)
              throws java.lang.Exception

Create a new IMCDefinition, loading the XML definitions from the given InputStream

Parameters:

is -

Throws:

java.lang.Exception

Method Detail

writeDefaultDefinitions

public static void writeDefaultDefinitions(java.io.File destination)
                                    throws java.io.IOException

Throws:

java.io.IOException

getInstance

public static IMCDefinition getInstance()

Retrieve (possibly reusing) default definitions

Returns:

Default IMC definitions

getInstance

public static IMCDefinition getInstance(java.io.InputStream isDefinitions)

Load the XML on the given InputStream and changes the default instance to this

Parameters:

isDefinitions - InputStream holding the XML definitions

Returns:

new IMCDefinition, loading the XML definitions from the given InputStream

headerLength

public int headerLength()

Retrieve the header length in this IMC version

Returns:

the header length in this IMC version

createHeader

public Header createHeader()

Create a new header compatible with these definitions

Returns:

a new header compatible with these definitions

getHeaderType

public final IMCMessageType getHeaderType()

getType

public final IMCMessageType getType(java.lang.Integer id)

Retrieve the message type of given message id

Parameters:

id - a (numeric) message id

Returns:

The corresponding IMCMessageType or null if that type was not found

getType

public final IMCMessageType getType(java.lang.String name)

Retrieve the message type of given message abbreviated name

Parameters:

name - the abbreviated name of the wanted message type

Returns:

The corresponding IMCMessageType or null if that type was not found

getSyncWord

public long getSyncWord()

Retrieve the Synchronization word of this IMC definition

Returns:

Synchronization word of this IMC definition

getSwappedWord

public long getSwappedWord()

Retrieve the swapped (little endian) synchronization word of this IMC definition

Returns:

Swapped synchronization word of this IMC definition

version

public java.lang.String version()

Retrieve the version found on these definitions' XML

Specified by:

version in interface IMessageProtocol<IMCMessage>

getVersion

public java.lang.String getVersion()

Retrieve the version found on these definitions' XML

getCreation

public java.lang.String getCreation()

Retrieve the creation date found on these definitions' XML

name

public java.lang.String name()

Specified by:

name in interface IMessageProtocol<IMCMessage>

getName

public java.lang.String getName()

Retrieve the definitions' name found on the XML

Returns:

the definitions' name found on the XML

getLongName

public java.lang.String getLongName()

Retrieve the definitions' long name found on the XML

getAuthor

public java.lang.String getAuthor()

Retrieve the definitions' author names found on the XML

getMd5String

public java.lang.String getMd5String()

Retrieve the generated MD5 hash for these definitions

parseMessage

public IMCMessage parseMessage(byte[] data)
                        throws java.io.IOException

Create and retrieve an IMCMessage that is serialized in an array of bytes

Parameters:

data - Where to read the message from

Returns:

The deserialized IMCMessage

Throws:

java.io.IOException - In case of a buffer underflow

nextMessageOfType

public IMCMessage nextMessageOfType(int type,
                                    java.nio.ByteBuffer buff)
                             throws java.lang.Exception

Retrieve the next message of given type from current position in the buffer

Parameters:

type - The type of the message to be retrieved

buff - The buffer where to read the message from

Returns:

The next IMCMessage of given type

Throws:

java.lang.Exception - if end of the buffer is reached

nextMessage

public IMCMessage nextMessage(java.nio.ByteBuffer buff)
                       throws java.lang.Exception

Retrieve the next message from the buffer

Parameters:

buff - The buffer where to read the message from

Returns:

The next message in the buffer

Throws:

java.lang.Exception - if end of the buffer is reached

readHeader

public void readHeader(IMCInputStream iis,
                       IMCMessage header)
                throws java.io.IOException

Read a message header from the given IMCInputStream

Parameters:

header - Where to store the read data

iis - Where to read the header from

Throws:

java.io.IOException

nextMessage

public IMCMessage nextMessage(IMCInputStream input)
                       throws java.io.IOException

Retrieve the next message from the given IMCInputStream

Parameters:

input - where to read the message from

Returns:

The next message in the input

Throws:

java.io.IOException - In case of any IO error (like end of input)

nextMessage

public IMCMessage nextMessage(java.io.InputStream in)
                       throws java.io.IOException

Retrieve the next message in the given InputStream. This is done by converting the InputStream in an IMCInputStream.

Parameters:

in - Where to read the message from

Returns:

The next message in the input

Throws:

java.io.IOException - IO errors

deserialize

public java.lang.Object deserialize(IMCFieldType type,
                                    java.io.DataInput in,
                                    java.lang.String context)
                             throws java.io.IOException

Throws:

java.io.IOException

deserializeFields

public void deserializeFields(IMCMessage message,
                              java.io.DataInput in)
                       throws java.io.IOException

Throws:

java.io.IOException

dumpPayload

public java.lang.String dumpPayload(IMCMessage message,
                                    int numTabs)
                             throws java.io.IOException

Throws:

java.io.IOException

serializeFields

public int serializeFields(IMCMessage message,
                           IMCOutputStream out)
                    throws java.io.IOException

Throws:

java.io.IOException

getMessageCount

public int getMessageCount()

Specified by:

getMessageCount in interface IMessageProtocol<IMCMessage>

messageExists

public boolean messageExists(java.lang.String name)

Verify if a message with given abbreviated name exists in these definitions

Parameters:

name - The name to be searched for

Returns:

Whether that message exists in this definition or not

getMessageId

public int getMessageId(java.lang.String name)

Specified by:

getMessageId in interface IMessageProtocol<IMCMessage>

getMessageName

public java.lang.String getMessageName(int id)

Specified by:

getMessageName in interface IMessageProtocol<IMCMessage>

getMessageNames

public java.util.Collection<java.lang.String> getMessageNames()

Specified by:

getMessageNames in interface IMessageProtocol<IMCMessage>

getConcreteMessages

public java.util.Collection<java.lang.String> getConcreteMessages()

getAbstractMessages

public java.util.Collection<java.lang.String> getAbstractMessages()

newMessage

public IMCMessage newMessage(int id)
                      throws java.lang.Exception

Specified by:

newMessage in interface IMessageProtocol<IMCMessage>

Throws:

java.lang.Exception

newMessage

public IMCMessage newMessage(java.lang.String name)
                      throws java.lang.Exception

Specified by:

newMessage in interface IMessageProtocol<IMCMessage>

Throws:

java.lang.Exception

serializationSize

public int serializationSize(IMCMessage msg)

Specified by:

serializationSize in interface IMessageProtocol<IMCMessage>

replicate

public IMCMessage replicate(IMCMessage msg)
                     throws java.lang.Exception

Throws:

java.lang.Exception

create

public IMCMessage create(java.lang.String name,
                         java.lang.Object... values)

Create a new message and fills it with given values

Parameters:

name - The abbreviated name of the message to be created

values - A list of pairs <field,value> for initializing the message. Example:

 IMCMessage estimatedState = new IMCMessage("EstimatedState", "x", 10.0, "lat",
                0.71, "ref", "NED");
 

Returns:

The created message or null if the given name is not valid

create

public <T extends IMCMessage> T create(java.lang.Class<T> clazz,
                                       java.lang.Object... values)

serialize

public void serialize(IMCMessage m,
                      IMCOutputStream os)
               throws java.lang.Exception

Serialize the given message to an IMCOutputStream

Parameters:

m - The message to be serialized

os - Where to serialize the message

Throws:

java.lang.Exception - IO errors

serialize

public void serialize(IMCMessage m,
                      java.io.OutputStream os)
               throws java.lang.Exception

Specified by:

serialize in interface IMessageProtocol<IMCMessage>

Throws:

java.lang.Exception

unserialize

public IMCMessage unserialize(java.io.InputStream is)
                       throws java.lang.Exception

Specified by:

unserialize in interface IMessageProtocol<IMCMessage>

Throws:

java.lang.Exception

getResolver

public final IMCAddressResolver getResolver()

Retrieve this definition's address resolver

Returns:

This definition's address resolver

subtypesOf

public java.util.Collection<java.lang.String> subtypesOf(java.lang.String msgAbbrev)

versionOfFile

public static java.lang.String versionOfFile(java.io.File f)

Utility method to retrieve the IMC version of a given file with XML defitions

Parameters:

f - The XML file of the IMC definitions (IMC.xml)

Returns:

The version found on the file

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Throws:

java.lang.Exception