stella
Class MessageEvent

java.lang.Object
  java.util.EventObject
      util.rmi.RmiEvent
          stella.MessageEvent

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

CommandEvent, ErrorEvent, InfoEvent, MessageBin, ReplyEvent

public abstract class MessageEvent
extends RmiEvent

Base message class. Any command, acknowledge, done, error or status messages are subclasses of this class. This message combines all common properties of all messages and should never be instantiated directly. The common properties include:

• Type: A unique string. This string should use only capital letters, word should be separated with an underscore. For commands, the last word of the type should give a hint to the device it belonges to. Acknowledge, done, and status messages have a fixed type, independent of the issuer.
• Command line(s): The string-array representation of the command, used to transfer it over TCP-sockets and/or for logging purpose. Additional parameters (e.g. position commands) are included in the command lines.
• The number of command lines: This number follows from the dimension of the previous array, but is included in the message header.
• The date of generation: In ms since January 1, 1970, 00:00:00 GMT
• The source: Normally the IP address of the issuer. This goes in the localHost field of the RmiEvent, which Message is a subclass of.

Note that every Message is an Event, therefore Listeners register themselfs to the Message source. Accordingly, no destination is specified, this is done by registering the appropriate Listeners. This, however, implies that Commands must further be subclassed into TelescopeCommands, CCDcommands, etc. This has the drawback that at design of the specific commands the receiver must already be known. Changing the line of flow requires an update of the appropriate Command code.

Example:
MOVE_TELESCOPE 1 965054152000 SCS
314.745656 12.983457

See Also:

Serialized Form

Field Summary

private int	lineNr The number of command lines.
static char	SEPCHAR The separator char used in the header.
private long	time The time of creation.
private String	type The Message type.
private boolean	valid True if the message event is valid, i.e.

Fields inherited from class util.rmi.RmiEvent

localHost, sourceName

Fields inherited from class java.util.EventObject

source

Constructor Summary

protected	MessageEvent(Object src) An empty Message.
protected	MessageEvent(Object src, String type) An empty Message.
protected	MessageEvent(Object src, String ty, long ti) An empty Message.

Method Summary

protected boolean	checkType(String type) A method that checks if the stated type is in the allowed range.
boolean	equals(Object that) Tests for equality of two Messages.
boolean	equalTime(long ti) Test this Messages generation time against the specified time (in ms).
boolean	equalTime(MessageEvent that) Test whether two MessageEvents have the same generation time.
static MessageEvent	fromAscii(MessageBin ascii) Converts a MessageBin into a fully functional java object.
String	getAllCommandLines() A convenience method to return all command lines as a single String.
Object	getExecuteGroupKey() Returns a simple key for use in a hash table.
String	getHead() Returns the first line of this Message's String representation.
abstract String[]	getLine() Returns the command line(s).
int	getNr() Returns the number of command lines.
long	getTime() Returns the time this Message was generated.
String	getType() Returns the type of this Message.
int	hashCode() Computes a hash code for this message.
boolean	isValid() Returns the validity flag of this message event.
boolean	parseFromSingleString(String all) A convenience method to parse all command lines from a single string.
abstract boolean	parseLine(String[] cl) Parses the message event parameters.
static MessageBin	readFromBufferedStream(BufferedReader in) Reads a message event from a stream as a sequence of ascii-lines.
protected void	setNr(int nr) Sets the number of command lines in this message event.
void	setTime(long ti) Sets the time this Message was generated.
protected void	setType(String ty) Sets the type of this Message.
void	setValid(boolean val) Sets the value of the validity flag.
String	toString() Converts this message to a single String.

Methods inherited from class util.rmi.RmiEvent

getHost, getSourceName, setSourceName

Methods inherited from class java.util.EventObject

getSource

Methods inherited from class java.lang.Object

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

Field Detail

SEPCHAR

public static final char SEPCHAR

The separator char used in the header.

See Also:

Constant Field Values

type

private String type

The Message type. A null means invalid Message.

time

private long time

The time of creation. You should always specify this at construct, otherwise it will be set to zero.

lineNr

private int lineNr

The number of command lines.

valid

private boolean valid

True if the message event is valid, i.e. all parameters are set.

Constructor Detail

MessageEvent

protected MessageEvent(Object src)

An empty Message. Never use this constructor directly.

MessageEvent

protected MessageEvent(Object src,
                       String type)

An empty Message. Never use this constructor directly.

MessageEvent

protected MessageEvent(Object src,
                       String ty,
                       long ti)

An empty Message.

Method Detail

readFromBufferedStream

public static MessageBin readFromBufferedStream(BufferedReader in)
                                         throws IOException

Reads a message event from a stream as a sequence of ascii-lines. Note that receiving the correct type requires constructors from a message event in the target object.

This method reconstructs the message event correctly by reading the required number of command lines from the stream. Nevertheless, follow these guidlines.

• The first line read is the message header.
• The message header fuels a string tokenizer which must have four retrievable tokens.
• The first token is the message type. It is a simple string.
• The second token is the number of command lines. It is a parsable int.
• The third token is the message's creation time. It is a parsable long.
• The fourth token is the IP-identifier of the issuing host. This can either be an IP-address like 206.26.48.100 or a resolvable host name.
• The number of command lines found in the header is now used for retrieving the command lines. To this purpose, x lines are read from the stream and directly copied into the message's command line array.

Parameters:

in - The buffered reader to read this message from.

Throws:

IOException

See Also:

MessageBin

fromAscii

public static MessageEvent fromAscii(MessageBin ascii)

Converts a MessageBin into a fully functional java object. This is necessary if you read an ASCII-version of a message event from a stream. This ascii-version can only represent a message bin. After the bin has fully been read, this method tries to instantiate the correct command, as dervied from the type of the message.
Note that the returned object can savely be cast to the appropriate type.

checkType

protected boolean checkType(String type)

A method that checks if the stated type is in the allowed range. Subclasses may interfere here to allow fail-fast syntax errors. The default implementation returns always true.

Parameters:

type - The message type under question.

Returns:

True.

getType

public String getType()

Returns the type of this Message. The corresponding setType method is protected.

setType

protected void setType(String ty)

Sets the type of this Message.

getTime

public long getTime()

Returns the time this Message was generated. The corresponding setTime method is protected.

setTime

public void setTime(long ti)

Sets the time this Message was generated.

getNr

public int getNr()

Returns the number of command lines.

setNr

protected void setNr(int nr)

Sets the number of command lines in this message event. Protected access only.

isValid

public boolean isValid()

Returns the validity flag of this message event. This method should only retrun true if all parameters in this message are correctly assigned.

setValid

public void setValid(boolean val)

Sets the value of the validity flag. Should only be accesed by daugther classes that know what they are doing. In most cases, this method will be called by daugther classes after a successful call to parseLine(java.lang.String[]).

getAllCommandLines

public String getAllCommandLines()

A convenience method to return all command lines as a single String. Individual command lines are separated by the os-sepcific newline character.

getLine

public abstract String[] getLine()

Returns the command line(s). The return type is always an array of Strings.

Returns:

An array containing all command lines.

parseFromSingleString

public boolean parseFromSingleString(String all)

A convenience method to parse all command lines from a single string. The individual command lines must be separaetd with os-sepcific newline chars.

parseLine

public abstract boolean parseLine(String[] cl)

Parses the message event parameters. The command lines are handed over to the method as an array of strings.

Returns:

True, if parsing was successful.

toString

public String toString()

Converts this message to a single String. This method is used, if this message is passed as an ascii-String to non-java programms. It contains all the information necessarry to rebuild it on other systems. The following syntax is prescribed:

• The first line is the header. It consists of the
  • Typeof the Message
  • number of command lines
  • Time (in ms) of the Message generation
  • the String representation of the source, in most cases the IP number of the issuer
  • IP number of the receiver (the registered listener). This item is only included for convenience and follows directly from the type of subclass. E.g. TelescopeEvent add the IP number of the telescope control computer here.
  All this items are separated by a single space SEPCHAR.
• The following lines are the command lines, if any, separated by the (system specific) newline char(s).

Overrides:

toString in class RmiEvent

Returns:

A multiline representation of this Message.

getHead

public String getHead()

Returns the first line of this Message's String representation. In the default version, the receiver is omitted.

Returns:

The header of the message without a receiver.

getExecuteGroupKey

public Object getExecuteGroupKey()

Returns a simple key for use in a hash table. This method wrapps the type and time-tag into a single String. The intended use of this method is the matching of a command/acknowledge/done sequence into a single key.

hashCode

public int hashCode()

Computes a hash code for this message. This is the hash code of the message type.

Overrides:

hashCode in class Object

equals

public boolean equals(Object that)

Tests for equality of two Messages. This is true and only if:

• The argument is an instance of MessageEvent.
• None of the Messages is invalid (null type).
• The Type of both Messages are equal.
• The time of generation is identically (also applies for zero time).
• The number of command lines are equal.

The command lines are not checked for equality in this basic version.

Overrides:

equals in class Object

Parameters:

that - The Object to compare to.

Returns:

True, if both MessageEvents are equal.

See Also:

equalTime(long)

equalTime

public boolean equalTime(MessageEvent that)

Test whether two MessageEvents have the same generation time. May be useful to trace the command flow in specific applications.

Returns:

equalTime(that.Time)

equalTime

public boolean equalTime(long ti)

Test this Messages generation time against the specified time (in ms). Useful for determining dependencies between command/acknowledge/done Messages.