gumbo.net.msg.ascii
Class AsciiMessage

java.lang.Object
  |
  +--gumbo.net.msg.Message
        |
        +--gumbo.net.msg.ascii.AsciiMessage

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

MsgPingCommand, MsgPingStatus

public abstract class AsciiMessage

extends Message

Abstract subclass of Message containing all aspects of ASCII transport of a message. This class and its subclasses should only depend on the message data format, with only loose coupling to the message transport format, implemented via AsciiMessageIO subclasses.

Messages that will be written to a stream (using an AsciiMessageWriter) are constructed with a writer and an empty head. Messages that will be read are constructed by passing a head, initialized by a reader, to the message factory method createAsciiMessage(), or by simply calling readMessage().

Subclasses must implement message-specific abstract methods (e.g. getType()), and should provide message-specific accessors for the message body (parameters and data unit contents).

See the Destiny client-server message protocol documentation for details concerning the message types and their parameters and data.

Version:

$Revision: 1.1 $

, 1.3

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

See Also:

Serialized Form

Constructor Summary

AsciiMessage()
Constructs an empty message with a head matching the type and body version of this message.

AsciiMessage(AsciiMessageHead head)
Constructs a message with the specified head and an empty body.

Method Summary

protected static AsciiMessage	createAsciiMessage(AsciiMessageHead head) Creates a new message of a specific type as indicated by a message head.
protected void	defaultHead() Creates and sets the default head for this message.
abstract void	readAsciiBody() Reads the body of this message from an ASCII message reader.
static AsciiMessage	readAsciiMessage(AsciiMessageReader reader) Convenience method for reading a message in its entirety.
abstract void	writeAsciiBody() Writes the body of this message to an ASCII message writer.
void	writeAsciiMessage(AsciiMessageWriter writer) Convenience method for writing this message in its entirety.

Methods inherited from class gumbo.net.msg.Message

beforeBodyWrite, getBodyVersion, getHead, getMessageType, setHead, toBodyString, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AsciiMessage

public AsciiMessage()

Constructs an empty message with a head matching the type and body version of this message.

AsciiMessage

public AsciiMessage(AsciiMessageHead head)
             throws MessageDataException

Constructs a message with the specified head and an empty body. Typically, messages that are read are created indirectly using the factory method createAsciiMessage().

Parameters:

head - Initialized message head. Never null.

Throws:

MessageDataException - Mismatch between head and body message type or body version.

Method Detail

readAsciiBody

public abstract void readAsciiBody()
                            throws java.io.IOException,
                                   MessageIOException

Reads the body of this message from an ASCII message reader. Does not call afterBodyRead() or read the message end delimiter. Blocks until the body is read. Overriders should use the head's reader to read the body unit (i.e. entire message should be read from the same reader).

Throws:

MessageIOException - Reader not at message body, or message head format was bad.

java.io.IOException

writeAsciiBody

public abstract void writeAsciiBody()
                             throws java.io.IOException,
                                    MessageIOException

Writes the body of this message to an ASCII message writer. Does not call beforeBodyWrite() or write the message end delimiter. Blocks until the body is written. Overriders should use the head's writer to write the body unit (i.e. entire message should be written to the same writer).

Throws:

MessageIOException - Writer not at message body, or message head format was bad.

java.io.IOException

createAsciiMessage

protected static AsciiMessage createAsciiMessage(AsciiMessageHead head)
                                          throws MessageDataException

Creates a new message of a specific type as indicated by a message head. Typically used to instantiate a message after reading its head but before reading its body (which requires a specific message type).

Parameters:

head - Initialized message head. Never null.

Returns:

New message initialized with head. Never null.

Throws:

MessageDataException - Unknown message type (head may not be initialized) or mismatch between head data and implicit message type or body version.

readAsciiMessage

public static AsciiMessage readAsciiMessage(AsciiMessageReader reader)
                                     throws java.io.IOException,
                                            MessageIOException,
                                            MessageDataException

Convenience method for reading a message in its entirety. Uses createAsciiMessage() to create a new message, and readAsciiBody() to read the message body. Blocks until a message is read.

This method is not thread-safe. Use the method of the same name in AsciiMessageReader to avoid thread conflicts.

Throws:

MessageDataException - Unknown message type (head may not be initialized) or mismatch between head data and implicit message type or body version.

java.io.IOException

MessageIOException

writeAsciiMessage

public void writeAsciiMessage(AsciiMessageWriter writer)
                       throws java.io.IOException,
                              MessageIOException

Convenience method for writing this message in its entirety. Uses writeAsciiBody() to write the message body. Blocks until the message is written.

This method is not thread-safe. Use the method of the same name in AsciiMessageWriter to avoid thread conflicts.

java.io.IOException

MessageIOException

defaultHead

protected void defaultHead()

Creates and sets the default head for this message.

Overrides:

defaultHead in class Message