gdl
    title     = Java API
    subtitle  = Documentation
    product   = OpenAMQ Java
    author    = iMatix Corporation <amq@imatix.com>
    date      = 2005/03/31
    copyright = Copyright (c) 2004 JPMorgan
    version   = 0.5a3
end gdl

Cover
*****

State of this Document
======================

Distribution of this document is currently limited to iMatix and JPMorgan
 internal use.

This document describes a work in progress.

Copyright Notice
================

This document is copyright (c) 2004 JPMorgan Inc.

Authors
=======

This document was written by Gustavo Broos <gustavo@imatix.com>.

Abstract
========

Overview of the Java API for OpenAMQ.

Introduction
************

Package summary
=================

The com.imatix.openamq package provides an implementation of the AMQP/Fast API
for Java applications. The package provides classes for serializing and 
deserializing connection, channel and handle protocol commands. A factory class
provides object instantiation from the network. This utility class enforces 
negotiated protocol parameters. Message input and output is possible via 
filtered streams. The provided streams can read from and write to memory 
buffers available to the application, while simple message defragmentation and 
fragmentation is handled transparently. Out-of-band messages are possible by 
passing of additional dedicated input/output streams. The package supports 
field table encoding and decoding through a class which is similar in spirit
to the Java Properties class. Methods for reading and writing unsigned values
up to 4 bytes long are available. Since Java does not provide primitive 
unsigned types, then AMQP integer values must be stored in memory into types of
greater capacity than the protocol specifies; in Java spirit, moving those
values from memory to network is runtime-checked for overflows/underflows. Long
strings are stored as byte arrays.

The Java API is currently a low-level communications layer, it does not implement
client or server protocol dialogues. Specifically, the provided API can be used
to:
- Send messages as data streams
- Send and receive command frames  
- Read and write field tables
- Read and write primitive protocol types
- Dump to console the data traffic
- Build higher level (client/server) APIs

API Documentation
*****************

Definitions and References
==========================

1. AMQ_RFC006
2. The Java Language Specification
3. Java 2 Platform Standard Edition API Specification

Objectives
==========

The framing API has for objectives:
- Java 1.4.x compatibility
- Follow the existing Java design patterns closely but not strictly
- A clear object oriented structure
- Good balance between maintainable and optimized code
- Reliable socket timeouts for reading and writing

Architecture
============

Design elements
---------------

A framing factory:
    Hands instances of network-serialized objects. Enforces protocol parameters.
    Provides various utility methods.
Message input and output streams:    
    Allows traffic of big or out-of-band messages. Java will not directly
    allow 4GB memory arrays ((2) 15.10), but a server can use streams to 
    segment incoming/outgoing data. 
Underflow/Overflow and other runtime checks:
    Makes programming errors less probable.
Inner class command sub-types:
    Organization without resorting to fragmenting the package. Supports the
    framing factory's structure. You need a connection object before having
    any connection frames. 
Filling of command parameters via public variables:
    Forces to write (i.e. document) the name of the value being set.
    
Class overview diagram
----------------------

Interface level
...............
package com.imatix.openamq

    AMQFramingFactory                     /* Glue/utility for framable classes */
    
    Exception
      |  
      +---AMQException                    /* OpenAMQ Java API exception        */
    
    IOException  
      |
      +---AMQIOException                  /* Thrown from the message streams   */
    
Framing level
.............
package com.imatix.openamq.frames

    AMQConnection                         /* Glue/utility for connection comm. */
    
    AMQChannel                            /* Glue/utility for channel commands */
    
    AMQHandle                             /* Glue/utility for handle commands  */
    
    AMQMessage                            /* Utility for the message class     */
    
    AMQFramable                           /* Superclass of network objects     */
    |
    +---AMQMessage.Head                   /* Message head object               */
    |
    +---AMQFrame                          /* Superclass of command frames      */
            |        
            +---AMQConnection.Frame       /* Connection commands superclass    */
            |     |    
            |     +---AMQConnection.Challenge /* Connection challenge class    */
            |     |        
            |     +---AMQConnection.Response  /* Connection response class     */
            |     |        
            |     +---AMQConnection.Tune      /* Connection tune class         */
            |     |        
            |     +---AMQConnection.Open      /* Connection open class         */
            |     |         
            |     +---AMQConnection.Ping      /* Connection ping class         */
            |     |        
            |     +---AMQConnection.Reply     /* Connection reply class        */
            |     |        
            |     +---AMQConnection.Close     /* Connection close class        */
            |  
            +---AMQChannel.Frame          /* Channel commands superclass       */
            |     |        
            |     +---AMQChannel.Open         /* Channel open class            */
            |     |   
            |     +---AMQChannel.Ack          /* Channel ack class             */
            |     |   
            |     +---AMQChannel.Commit       /* Channel commit class          */
            |     |   
            |     +---AMQChannel.Rollback     /* Channel rollback class        */
            |     |   
            |     +---AMQChannel.Reply        /* Channel reply class           */
            |     |   
            |     +---AMQChannel.Close        /* Channel close class           */
            |        
            +---AMQHandle.Frame           /* Handle commands superclass        */
                |
                +---AMQHandle.Open            /* Handle open class             */
                |        
                +---AMQHandle.Send            /* Handle send class             */
                |        
                +---AMQHandle.Consume         /* Handle consume class          */
                |        
                +---AMQHandle.Cancel          /* Handle cancel class           */
                |        
                +---AMQHandle.Flow            /* Handle flow class             */
                |        
                +---AMQHandle.Unget           /* Handle unget class            */
                |        
                +---AMQHandle.Query           /* Handle query class            */
                |        
                +---AMQHandle.Browse          /* Handle browse class           */
                |        
                +---AMQHandle.Created         /* Handle created class          */
                |        
                +---AMQHandle.Notify          /* Handle notify class           */
                |        
                +---AMQHandle.Index           /* Handle index class            */
                |        
                +---AMQHandle.Prepare         /* Handle prepare class          */
                |         
                +---AMQHandle.Ready           /* Handle ready class            */
                |        
                +---AMQHandle.Reply           /* Handle reply class            */
                |        
                +---AMQHandle.Close           /* Handle close class            */
            
    HashTable        
      |
      +---AMQFieldTable                   /* Field table name/value pairs      */
    
Transport level
...............
package com.imatix.openamq

    AMQTransport                          /* Low-level connection handling     */

Demonstration
=============
Two test clients written using this API are available. These clients are not 
part of the framing API, and they will probably constantly change; for those
reasons, they will be documented only briefly.

Pattern testing client
----------------------
Currently, this client uses a very basic FSM which negotiates connection and 
handles closing. It writes a series of messages filled with pseudo random 
patterns which are then read back and tested for integrity.

Echo client
-----------
This client inherits the FSM from the pattern testing client. The echo client
is asynchronous, it has threads running for getting a message as it arrives, 
as well as for sending a message as soon as the user hits return. This client
allows for a human readable chat demonstration between Java and c components. 
The echo client can chat with another Java instance if the read-queue and 
write-queue parameters are twisted for the second instance.

Class summary
=============

AMQFramingFactory summary
-------------------------
This class concentrates the available methods for protocol functionality. A 
client or server layer will build on top of this class mainly. This class 
allows for construction, serialization and deserialization of protocol objects. 
This is the place where most AMQP negotiated parameters will be held and 
checked for correctness (frame sizes, coherence of the values on passed objects
(in a best-effort basis), etc.). 

AMQConnection summary
---------------------
This class packs connection-type commands as inner classes. The inner classes
are manipulated through factory-like methods which are meant to support the 
AMQFramingFactory's functionality. This class provides a common functional
layer for its inner types. You can use the AMQFramingFactory to ease the use of
AMQConnection objects. See the description for AMQFrame.

AMQChannel summary
------------------
This class packs channel-type commands as inner classes. The inner classes
are manipulated through factory-like methods which are meant to support the 
AMQFramingFactory's functionality. This class provides a common functional
layer for its inner types. You can use the AMQFramingFactory to ease the use of
AMQChannel objects. See the description for AMQFrame.

AMQHandle summary
-----------------
This class packs handle-type commands as inner classes. The inner classes
are manipulated through factory-like methods which are meant to support the 
AMQFramingFactory's functionality. This class provides a common functional
layer for its inner types. You can use the AMQFramingFactory to ease the use of
AMQHandle objects. See the description for AMQFrame.

AMQMessage summary
------------------
This class represents a message head frame. You can use the AMQFramingFactory
to ease the use of AMQMessage objects. See the description for AMQFramable.

AMQFramable summary
-------------------
This class is the superclass for serializable/deserializable protocol objects.
The message header is not a full command frame, but it is nonetheless framable.
Every command frame is a framable object.

AMQFrame summary
----------------
This class is the superclass for all protocol command frames. All the objects
of this class have a specific type which is read on deserialization. You can 
use the AMQFramingFactory to ease the use of AMQFrame objects.

AMQFieldTable summary
---------------------
This class is modeled closely after the Java Properties object; it contains 
name/value pairs which can be read from or written to network as AMQP field
tables. A set of get/put methods for the field table types specified in 
AMQ_RFC006 (1) are provided.

AMQTransport summary
--------------------
This class handles reading and writing of primitive protocol data types. The
class manages low-level network issues such as read retries, socket timeouts,
etc. We currently rely on SUN's documented behavior (3) for read and accept 
timeouts, write timeouts are enforced. Higher level layers should not attempt
to directly write to the socket, but instead use the methods provided by this 
class.

Exception summary
=================

AMQException summary
---------------------------
The OpenAMQ Java API throws this exception to signal failure. A failure 
description is provided.

AMQIOException summary
-----------------------------
This class extends IOException, so that it is possible to throw it from 
overloaded stream methods.

Class details
=============

AMQFramingFactory
-----------------
   
public boolean verbose
......................
Governs console output of execution information.
Should be refined to an integer value.

public AMQFramingFactory(Socket socket)
.......................................
This constructs an AMQFramingFactory object with the input streams provided
by the socket. 

    Parameters
        socket - Network connection to use.
    Throws
        IOException - If network streams wrapping (buffering, data input) fails.

public AMQFramingFactory(Socket socket, int readBuff, int writeBuff)
....................................................................
This constructs an AMQFramingFactory object with the input streams provided
by the socket wrapped around with buffers of custom capacity. 

    Parameters
        socket - Network connection to use.
        readBuff - Requested size for input buffer.
        writeBuff - Requested size for output buffer.
    Throws
        IOException - If network streams wrapping (buffering, data input) fails.

public AMQFramingFactory(InputStream is, OutputStream os) 
.........................................................
This constructs an AMQFramingFactory object with the provided input streams.

    Parameters
        is - Input stream to use.
        os - Output stream to use.
    Throws
        IOException - If network streams wrapping (buffering, data input) fails.

public AMQFramingFactory(is, os, readBuff, writeBuff)
..............................................................
This constructs an AMQFramingFactory object with the provided input streams 
wrapped around with buffers of custom capacity. 
    
    Parameters
        InputStream is - Input stream to use.
        OutputStream os - Output stream to use.
        int readBuff - Requested size for input buffer.
        int writeBuff - Requested size for output buffer.
    Throws
        IOException - If network streams wrapping (buffering, data input) fails.
        
public void setTuneParameters(AMQConnection.Tune tune)
......................................................
Sets connection tune parameters from a connection tune object. The parameters should
not be changed after the connection tune negotiation has been completed, or runtime
exceptions may be thrown.

    Parameters
        tune - Connection tune object, provides parameters on field tables.
    Throws
        IOException - If the proposed FRAME_MAX is too small.

public long getFrameMax()
......................... 
Gets the current FRAME_MAX value that was read from the tune parameters.

    Returns
        The FRAME_MAX value that is currently effective.
    
public InputStream receiveMessage(hnFirst, head, is, prepared) 
..............................................................
This returns an InputStream for receiving a message. The first handle notify
for this message and an empty head must be supplied If the message was NOT 
prepared, the passed head is filled from the network. If the passed input 
stream is null, in-band message consumption will take place Copies the 
destName variable in the last handle notify to the provided hnFirst.

    Parameters
        AMQHandle.Notify hnFirst - The handle notify that announced the message.
        AMQMessage.Head head - The message head (to be filled if not prepared).
        InputStream is - From where to read the data.
        boolean prepared - Was this message prepared with a handle prepare?
    Returns
        An InputStream for the message body.    
    Throws
        IOException - Reading the message head failed.    

public OutputStream sendMessage(hsFirst, head, os, prepared)
............................................................
This returns an OutputStream for sending a message. The first handle send 
and the head for this message must be supplied The constructor will NOT send 
the message head passed for messages that were prepared. If the passed output 
stream is null, in-band message production will take place. Uses the destName
variable from the provided hsFirst for the last handle send. Sends fragments of
the size specified in hsFirst.fragmentSize 
   
    Parameters
        AMQHandle.Send hsFirst - The handle send that announced the message.
        AMQMessage.Head head - The message head (to send if not prepared).
        OutputStream os - Where to write the data.
        boolean prepared - Was this message prepared with a handle prepare?
    Returns
        An OutputStream for the message body.
    Throws
        IOException - Writing the message head failed.    
        IOException - Trying to send and oversized fragment.    
        IOException - In hsFirst, partial is false but fragment is too big.

public AMQFrame constructFrame(short type)
.......................................
Constructs an empty object for a given frame type. The object variables should 
be configured, and then the sendFrame method can be used to send the object
through the network.

    Parameters
        type - Requested frame type.
    Returns
        An empty command frame object of the requested type.
    Throws 
        AMQException - Unknown frame type.

public AMQFrame receiveFrame()
..............................
Get a command frame object from the network.

    Throws 
        AMQException - Cannot decode the frame.
        AMQException - Frame of incorrect size was rejected.
        IOException - Exceptions from the underlying input streams.

public void sendFrame(AMQFrame frame)
........................................
Send a command frame object through the network.

    Parameters
        frame - Frame object to send.
    Throws 
        AMQException - Frame of incorrect size was rejected.
        IOException - Exceptions from the underlying output streams.

public AMQMessage.Head constructMessageHead()
..........................................
Construct a new message head object. The object variables should be configured,
and then the sendMessageHead method can be used to send the object through the
network.

    Returns
        An empty message head object.

public AMQMessage.Head receiveMessageHead() 
...........................................
Get a message header object from the network.

    Throws 
        AMQException - Cannot decode the frame.
    
public AMQMessage.Head receiveMessageHead(DataInputStream dis)
.............................................................
Get a message header object from the specified stream.

    Parameters
        dis - Message head deserialization source.
    Throws 
        AMQException - Cannot decode the frame.

public void sendMessageHead(AMQMessage.Head head) 
.................................................
Send a message head object through the network.

    Parameters
        head - Message head object to send.
    Throws  
        IOException - Exceptions from the underlying output streams.
    
public void sendMessageHead(AMQMessage.Head head, DataOutputStream dos) 
.......................................................................
Send a message head object through the specified stream.

    Parameters
        head - Message head object to send.
        dos - Message head serialization target.
    Throws  
        IOException - Exceptions from the underlying output streams.

AMQConnection
-------------

Connection command-type constants    
.................................
These are used for requesting new connection-type objects.

    public final static short CHALLENGE
    public final static short RESPONSE
    public final static short TUNE
    public final static short OPEN
    public final static short PING
    public final static short REPLY
    public final static short CLOSE

public class Challenge extends Frame 
....................................
AMQConnection inner class for challenge frames. Extends the AMQConnection.Frame
abstract class.

    public short    version                 /*  Negotiated protocol version      */
    public String   mechanisms              /*  Available security mechanisms    */
    public byte[]   challenges              /*  Challenge fields                 */

public class Response extends Frame 
...................................
AMQConnection inner class for response frames. Extends the AMQConnection.Frame
abstract class.

    public String   mechanism               /*  Selected security mechanism      */
    public byte[]   responses               /*  Response fields                  */

public class Tune extends Frame 
...............................
AMQConnection inner class for tune frames. Extends the AMQConnection.Frame
abstract class.

    public byte[]   options                 /*  Tuning options                   */
    public byte[]   dictionary              /*  Client-supplied dictionary       */

public class Open extends Frame 
...............................
AMQConnection inner class for open frames. Extends the AMQConnection.Frame
abstract class.

    public int      confirmTag              /*  Confirmation tag                 */
    public String   virtualPath             /*  Virtual server path              */
    public String   clientName              /*  Client identifier                */
    public byte[]   options                 /*  Connection options               */

public class Ping extends Frame 
...............................
AMQConnection inner class for ping frames. Extends the AMQConnection.Frame
abstract class.

    public boolean  respond                 /*  Please respond                   */

public class Reply extends Frame 
................................
AMQConnection inner class for reply frames. Extends the AMQConnection.Frame
abstract class.

    public int      confirmTag              /*  Confirmation tag                 */
    public int      replyCode               /*  Reply code                       */
    public String   replyText               /*  Reply text                       */

public class Close extends Frame 
................................
AMQConnection inner class for close frames. Extends the AMQConnection.Frame
abstract class.

    public int      replyCode               /*  Reply code                       */
    public String   replyText               /*  Reply text                       */

AMQChannel
----------

Channel command-type constants    
..............................
These are used for requesting new channel-type objects.

    public final static short OPEN
    public final static short ACK
    public final static short COMMIT
    public final static short ROLLBACK
    public final static short REPLY
    public final static short CLOSE

public class Open extends Frame 
...............................
AMQChannel inner class for open frames. Extends the AMQChannel.Frame
abstract class.

    public int      channelId               /*  Channel number                   */
    public int      confirmTag              /*  Confirmation tag                 */
    public boolean  transacted              /*  Transaction mode                 */
    public boolean  restartable             /*  Restartable mode                 */
    public byte[]   options                 /*  Channel options                  */
    public String   outOfBand               /*  Out of band options              */

public class Ack extends Frame 
..............................
AMQChannel inner class for ack frames. Extends the AMQChannel.Frame
abstract class.

    public int      channelId               /*  Channel number                   */
    public int      confirmTag              /*  Confirmation tag                 */
    public long     messageNbr              /*  Message reference                */

public class Commit extends Frame 
.................................
AMQChannel inner class for commit frames. Extends the AMQChannel.Frame
abstract class.

    public int      channelId               /*  Channel number                   */
    public int      confirmTag              /*  Confirmation tag                 */
    public byte[]   options                 /*  Transaction options              */

public class Rollback extends Frame 
...................................
AMQChannel inner class for rollback frames. Extends the AMQChannel.Frame
abstract class.

    public int      channelId               /*  Channel number                   */
    public int      confirmTag              /*  Confirmation tag                 */
    public byte[]   options                 /*  Transaction options              */

public class Reply extends Frame 
................................
AMQChannel inner class for reply frames. Extends the AMQChannel.Frame
abstract class.

    public int      channelId               /*  Channel number                   */
    public int      confirmTag              /*  Confirmation tag                 */
    public int      replyCode               /*  Reply code                       */
    public String   replyText               /*  Reply text                       */

public class Close extends Frame 
................................
AMQChannel inner class for close frames. Extends the AMQChannel.Frame
abstract class.

    public int      channelId               /*  Channel number                   */
    public int      replyCode               /*  Reply code                       */
    public String   replyText               /*  Reply text                       */

AMQHandle
---------

Handle command-type constants    
..............................
These are used for requesting new handle-type objects.

    public final static short OPEN
    public final static short SEND
    public final static short CONSUME
    public final static short CANCEL
    public final static short FLOW
    public final static short UNGET
    public final static short QUERY
    public final static short BROWSE
    public final static short CREATED
    public final static short NOTIFY
    public final static short INDEX
    public final static short PREPARE
    public final static short READY
    public final static short REPLY
    public final static short CLOSE

public class Open extends Frame
...............................
AMQHandle inner class for open frames. Extends the AMQHandle.Frame
abstract class.

    public int      channelId               /*  Channel number                   */
    public int      handleId                /*  Handle number                    */
    public int      serviceType             /*  Service type                     */
    public int      confirmTag              /*  Confirmation tag                 */
    public boolean  producer                /*  Request producer access          */
    public boolean  consumer                /*  Request consumer access          */
    public boolean  browser                 /*  Request browser access           */
    public boolean  temporary               /*  Request a temporary destination  */
    public String   destName                /*  Default destination name         */
    public String   mimeType                /*  Default MIME type                */
    public String   encoding                /*  Default content encoding         */
    public byte[]   options                 /*  Destination options              */

public class Send extends Frame 
...............................
AMQHandle inner class for send frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public int      confirmTag              /*  Confirmation tag                 */
    public long     fragmentSize            /*  Size of following fragment       */
    public boolean  partial                 /*  Partial message?                 */
    public boolean  outOfBand               /*  Out of band data?                */
    public boolean  recovery                /*  Restarting large message?        */
    public boolean  streaming               /*  Working in streaming mode?       */
    public String   destName                /*  Destination name suffix          */

public class Consume extends Frame 
..................................
AMQHandle inner class for consume frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public int      confirmTag              /*  Confirmation tag                 */
    public int      prefetch                /*  Max pending messages             */
    public boolean  noLocal                 /*  Don't deliver to self?           */
    public boolean  unreliable              /*  Unreliable mode                  */
    public String   destName                /*  Destination name                 */
    public String   identifier              /*  Subscription identifier          */
    public byte[]   selector                /*  Destination selector             */
    public String   mimeType                /*  Selector MIME type               */

public class Cancel extends Frame 
.................................
AMQHandle inner class for cancel frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public int      confirmTag              /*  Confirmation tag                 */
    public String   destName                /*  Destination name suffix          */
    public String   identifier              /*  Subscription identifier          */

public class Flow extends Frame 
...............................
AMQHandle inner class for flow frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public int      confirmTag              /*  Confirmation tag                 */
    public boolean  flowPause               /*  Pause the flow of messages?      */

public class Unget extends Frame 
................................
AMQHandle inner class for unget frames. Extends the AMQHandle.Frame
abstract class.

    public int  handleId                    /*  Handle number                    */
    public int  confirmTag                  /*  Confirmation tag                 */
    public long messageNbr                  /*  Message reference                */

public class Query extends Frame 
................................
AMQHandle inner class for query frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public long     messageNbr              /*  Message base                     */
    public String   destName                /*  Destination name suffix          */
    public byte[]   selector                /*  Destination selector             */
    public String   mimeType                /*  Selector MIME type               */

public class Browse extends Frame 
.................................
AMQHandle inner class for browse frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public int      confirmTag              /*  Confirmation tag                 */
    public long     messageNbr              /*  Message reference                */

public class Created extends Frame 
..................................
AMQHandle inner class for created frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public String   destName                /*  Created destination name         */

public class Notify extends Frame 
.................................
AMQHandle inner class for notify frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public long     messageNbr              /*  Message reference                */
    public long     fragmentSize            /*  Size of response fragment        */
    public boolean  partial                 /*  Partial message?                 */
    public boolean  outOfBand               /*  Out of band data?                */
    public boolean  recovery                /*  Restarting large message?        */
    public boolean  delivered               /*  Message must be acknowledged?    */
    public boolean  redelivered             /*  Message is being redelivered?    */
    public boolean  streaming               /*  Working in streaming mode?       */
    public String   destName                /*  Originating destination          */

public class Index extends Frame 
................................
AMQHandle inner class for index frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public long     messageNbr              /*  Message base                     */
    public byte[]   messageList             /*  List of message references       */

public class Prepare extends Frame 
..................................
AMQHandle inner class for prepare frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public long     fragmentSize            /*  Size of message header           */
    public String   contentHash             /*  SHA1 signature for content       */

public class Ready extends Frame 
................................
AMQHandle inner class for ready frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public long     messageSize             /*  Size of existing data, or zero   */

public class Reply extends Frame 
................................
AMQHandle inner class for reply frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public int      confirmTag              /*  Confirmation tag                 */
    public int      replyCode               /*  Reply code                       */
    public String   replyText               /*  Reply text                       */

public class Close extends Frame 
................................
AMQHandle inner class for close frames. Extends the AMQHandle.Frame
abstract class.

    public int      handleId                /*  Handle number                    */
    public int      replyCode               /*  Reply code                       */
    public String   replyText               /*  Reply text                       */

AMQMessage
----------

public class Head extends AMQFramable
.....................................
AMQMessage inner class for message header. Extends the AMQFramable abstract 
class.
 
    public long     bodySize                /*  Message body size                */
    public boolean  persistent              /*  Persistent data?                 */
    public short    priority                /*  Priority 0 (low) to 9 (high)     */
    public long     expiration              /*  Expiration time in UTC seconds   */
    public String   mimeType                /*  Content MIME type                */
    public String   encoding                /*  Content encoding                 */
    public String   identifier              /*  Message identifier               */
    public byte[]   headers                 /*  Message headers                  */

AMQFramable
-----------

public AMQFramable() 
....................
Empty object constructor.
    
public AMQFramable(DataInputStream dis) 
.......................................
Decoder constructor, calls the decoding method.

    Parameters
        dis - Deserialization source.
    Throws
        AMQException - The frame could not be decoded.

abstract public long encode(DataOutputStream dos)
.................................................
Used to serialize the object to the specified stream. 

    Parameters
        dos - Serialization target.
    Returns
        The size of the object in serialized form.

abstract public void decode(DataInputStream dis)
................................................
Used to deserialize a frame from the specified stream.

    Parameters
        dis - Deserialization source.
    Throws
        AMQException - The frame could not be decoded.

abstract public long size()
...........................

    Returns
        The size of the object in serialized form.

abstract public void dump()
...........................
Prints to console, in human readable format, the contents of the framable 
object.

AMQFrame
--------

public AMQFrame()
.................
Default constructor. Sets the command type.

public AMQFrame(DataInputStream dis)
..............................
Decoder constructor, calls the decoding method.

    Throws
        AMQException - The frame could not be decoded.
        AMQException - Command end is missing.

AMQFieldTable
-------------

public AMQFieldTable() 
......................
Default constructor. The resulting object should be filled via the get/put
methods. 

public AMQFieldTable(byte[] bucket)
...................................
Loading constructor. Loads into the underlying hashtable the name/value pairs
encoded in the passed bucket.

    Parameters
        bucket - Field table encoded as a byte array.
    Throws
        AMQException - Unrecognized field type while loading from bucket.
        AMQException - A field was redefined while loading from bucket.    

public void loadFromBucket(byte[] bucket)
.........................................
Loads into the underlying hashtable the name/value pairs encoded in the passed
bucket.

    Parameters
        bucket - Field table encoded as a byte array.
    Throws
        AMQException - Unrecognized field type while loading from bucket.
        AMQException - A field was redefined while loading from bucket.    

public byte[] storeToBucket() 
.............................
Encodes the name/value pairs from the underlying hashtable into a byte array
to be written to the network. Allocates the memory necessary for the byte array
representation.

    Returns
        Name/value pairs encoded as a byte array.
        
public byte[] storeToBucket(byte[] bucket)
.......................................... 
Encodes the name/value pairs from the underlying hashtable into a byte array
to be written to the network. Requires a buffer big enough to hold the fields
to be passed. A field table is 2^16 bytes long, maximum.
    
    Parameters
        bucket - Allocated memory for writing the table.
    Returns
        Name/value pairs encoded as a byte array.

public byte[] getString(String name)
.................................... 
Get a string value by name. If the given name does not correspond to a string
field, a ClassCastException will be thrown.

    Parameters
        name - Name of the field to look for.
    Returns
        A byte array representation of a long string. Null if the name was not
        found.

public Object putString(String name, byte[] value) 
..................................................
Put a string field into the underlying hashtable. Returns the previous value if
any, otherwise null.

    Parameters
        name - Name for the field.
        value - Long string value.
    Returns
        Previous value for that name.

public long getInteger(String name)
................................... 
Get an integer value by name. If the given name does not correspond to an 
integer field, a ClassCastException will be thrown.

    Parameters
        name - Name of the field to look for.
    Returns
        The value of the integer field. Null if the name was not found.

public Object putInteger(String name, long value) 
.................................................
Put a integer field into the underlying hashtable. Returns the previous value if
any, otherwise null.

    Parameters
        name - Name for the field.
        value - Integer value.
    Returns
        Previous value for that name.

public long[] getDecimal(String name)
..................................... 
Get a decimal value by name. If the given name does not correspond to a decimal
field, a ClassCastException will be thrown.

    Parameters
        name - Name of the field to look for.
    Returns
        The decimal part in the first element of the array. The integer part in
        the second element of the array. Null if the name was not found.

public Object putDecimal(String name, long[] value) 
...................................................
Put a decimal field into the underlying hashtable. Returns the previous value if
any, otherwise null.

    Parameters
        name - Name for the field.
        value - Decimal part in the first element, integer part on the second
        element.
    Returns
        Previous value for that name.

public long getDateTime(String name)
.................................... 
Get a date/time value by name. If the given name does not correspond to a 
date/time field, a ClassCastException will be thrown.

    Parameters
        name - Name of the field to look for.
    Returns
        An integer representing a time_t value with seconds accuracy. Null if
        the name was not found.

public Object putDateTime(String name, long value) 
..................................................
Put a date/time field into the underlying hashtable. Returns the previous value 
if any, otherwise null.

    Parameters
        name - Name for the field.
        value - A time_t value with seconds accuracy.
    Returns
        Previous value for that name.

AMQTransport
------------ 

public void flush() 
...................
Flushes the data written by the transport methods.
    
    Throws
        IOException - Exceptions from the underlying output stream.

public void flush(OutputStream os)
..................................
Flushes the data written by the transport methods on the specified stream.

    Parameters
        os - Target output stream to be flushed.
    Throws
        IOException - Exceptions from the underlying output stream.

public void receiveData(byte[] bytes)
.....................................
This function reads data from the socket's input stream. The bytes array is
entirely filled with data from the network.

    Parameters
        bytes - Allocated memory for storing the data read.
    Throws
        IOException - Exceptions from the underlying input streams.
    
public void receiveData(byte[] bytes, int off, int len)
.......................................................
This function reads data from the socket's input stream. The bytes array is
filled as requested.

    Parameters
        bytes - Allocated memory for storing the data read.
        off - Where to start writing data into the bytes array.
        len - How much data to read.
    Throws
        IOException - Exceptions from the underlying input streams.
    
public void receiveData(InputStream is, byte[] bytes, int off, int len)
.......................................................................
This function handles data reading from a stream, low-level details are 
abstracted at this point and will only show up if exceptions take place from
below.

    Parameters
        is - Data source.
        bytes - Allocated memory for storing the data read.
        off - Where to start writing data into the bytes array.
        len - How much data to read.
    Throws
        IOException - Exceptions from the underlying input streams.
    
public void sendData(byte[] bytes)
..................................
This function writes data to the socket's output stream. The bytes array will
be fully written to the network.

    Parameters
        bytes - Data to be written to the network.
    Throws
        IOException - Exceptions from the underlying output streams.
    
public void sendData(byte[] bytes, int off, int len)
.......................................................
This function writes data to the socket's output stream. The bytes array will
be written as requested.

    Parameters
        bytes - Data to be written to the network.
        off - Where to start reading data from the bytes array.
        len - How much data to write.
    Throws
        IOException - Exceptions from the underlying output streams.
    
public void sendData(OutputStream os, byte[] bytes, int off, int len)
........................................................................
This function handles data writing to the network, low-level details are
abstracted at this point and will only show up if exceptions take place from 
below.
    
    Parameters
        os - Data writing target.
        bytes - Data to be written to the network.
        off - Where to start reading data from the bytes array.
        len - How much data to write.
    Throws
        IOException - Exceptions from the underlying output streams.

public long readUnsignedInt()
.............................
Reads four bytes from the network and promotes to long discarding the sign.
The returned value is a long equal to the unsigned value represented by
the four bytes read.

    Returns
        The unsigned value represented by the four bytes read from the network.
    Throws
        IOException - Exceptions from the underlying input streams.

public void writeUnsignedInt(long value)
........................................
Checks that the long value passed holds a four-bytes unsigned integer, then
writes the bytes to the network. A runtime exception is thrown if the check
fails.

    Parameters
        value - A long containing the unsigned value represented by four bytes.
    Throws
        IOException - Exceptions from the underlying output streams.

public int readUnsignedShort()
..............................
Reads two bytes from the network and promotes to int discarding the sign.
The returned value is an int equal to the unsigned value represented by
the two bytes read.

    Returns
        The unsigned value represented by the two bytes read from the network.
    Throws
        IOException - Exceptions from the underlying input streams.

public void writeUnsignedShort(int value)
.........................................
Checks that the int value passed holds a two-bytes unsigned integer, then
writes the bytes to the network. A runtime exception is thrown if the check
fails.

    Parameters
        value - An int containing the unsigned value represented by two bytes.
    Throws
        IOException - Exceptions from the underlying output streams.

public short readUnsignedByte()
...............................
Reads one byte from the network and promotes to short discarding the sign.
The returned value is a short equal to the unsigned value represented by
the byte read.

    Returns
        The unsigned value represented by the byte read from the network.
    Throws
        IOException - Exceptions from the underlying input streams.

public void writeUnsignedByte(short value)
..........................................
Checks that the short value passed holds a one byte unsigned integer, then
writes one byte to the network. A runtime exception is thrown if the check
fails.

    Parameters
        value - A short containing the unsigned value represented by one byte.
    Throws
        IOException - Exceptions from the underlying output streams.
        
public static String bytes2String(byte[] bytes) 
...............................................
Encodes a byte array as a short string. The current encoding method is UTF-8.

    Parameters
        bytes - The byte array to encode as a short string.
    Returns
        The resulting string.
     
public static byte[] string2Bytes(String string)
................................................ 
Encodes a short string as a byte array. The current encoding method is UTF-8.

    Parameters
        string - The short string to encode as a byte array.
    Returns
        The resulting byte array.

public static void warning(String _class, String method, String message) 
........................................................................
Standard way for printing warning messages to console.

    Parameters
        _class - Originating class.
        method - Originating method.
        message - Descriptive message for the warning.

public static void exception(Exception e, String _class, String method, String message)
.......................................................................................
Standard way for throwing checked exceptions from the framing code.

    Parameters
        e - Java exception information.
        _class - Originating class.
        method - Originating method.
        message - Descriptive message for the warning.
    Throws 
        AMQException - The framing exception we are willing to throw.

public static void runtimeException(e, _class, method, message)
..............................................................................................
Standard way for throwing runtime exceptions from the framing code.

    Parameters
        Exception e - Java exception information.
        String class - Originating class.
        String method - Originating method.
        String message - Descriptive message for the warning.
    Throws 
        RuntimeException  - The runtime exception we are willing to throw.
        
Security Considerations
=======================

This proposal does not have any specific security considerations.

Comments on this Document
*************************

Comments by readers; these comments may be edited, incorporated, or removed
by the author(s) of the document at any time.

Date, name
==========

No comments at present.
