You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by bu...@apache.org on 2010/12/24 22:07:05 UTC
svn commit: r781512 - in
/websites/staging/river/trunk/content/river/doc/api/net/jini/jeri/connection/doc-files:
./ mux.html
Author: buildbot
Date: Fri Dec 24 21:07:04 2010
New Revision: 781512
Log:
Staging update by buildbot
Added:
websites/staging/river/trunk/content/river/doc/api/net/jini/jeri/connection/doc-files/
websites/staging/river/trunk/content/river/doc/api/net/jini/jeri/connection/doc-files/mux.html
Added: websites/staging/river/trunk/content/river/doc/api/net/jini/jeri/connection/doc-files/mux.html
==============================================================================
--- websites/staging/river/trunk/content/river/doc/api/net/jini/jeri/connection/doc-files/mux.html (added)
+++ websites/staging/river/trunk/content/river/doc/api/net/jini/jeri/connection/doc-files/mux.html Fri Dec 24 21:07:04 2010
@@ -0,0 +1,1304 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing, software
+ ! distributed under the License is distributed on an "AS IS" BASIS,
+ ! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ! See the License for the specific language governing permissions and
+ ! limitations under the License.
+ !-->
+
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+
+<title>Jini Extensible Remote Invocation (Jini ERI)
+ Multiplexing Protocol
+</title>
+
+<link rel="stylesheet" type="text/css"
+ href="../../../../../../../../stylesheet.css" title="Style">
+</head>
+
+<body bgcolor="white">
+
+<h2 align="center">Jini Extensible Remote Invocation
+ (Jini ERI) Multiplexing Protocol
+</h2>
+
+This page defines the Jini extensible remote invocation (Jini ERI)
+multiplexing protocol, which is used by the following Jini ERI
+transport layer implementation classes:
+
+<blockquote>
+ <a href="../ConnectionManager.html">
+ <code>net.jini.jeri.connection.ConnectionManager</code></a><br>
+ <a href="../ServerConnectionManager.html">
+ <code>net.jini.jeri.connection.ServerConnectionManager</code></a><br>
+
+ <a href="../../tcp/TcpEndpoint.html">
+ <code>net.jini.jeri.tcp.TcpEndpoint</code></a><br>
+ <a href="../../tcp/TcpServerEndpoint.html">
+ <code>net.jini.jeri.tcp.TcpServerEndpoint</code></a><br>
+
+ <a href="../../ssl/SslEndpoint.html">
+ <code>net.jini.jeri.ssl.SslEndpoint</code></a><br>
+ <a href="../../ssl/SslServerEndpoint.html">
+ <code>net.jini.jeri.ssl.SslServerEndpoint</code></a><br>
+
+ <a href="../../kerberos/KerberosEndpoint.html">
+ <code>net.jini.jeri.kerberos.KerberosEndpoint</code></a><br>
+ <a href="../../kerberos/KerberosServerEndpoint.html">
+ <code>net.jini.jeri.kerberos.KerberosServerEndpoint</code></a>
+</blockquote>
+
+The purpose of this protocol is to provide a wire format for
+implementing a binary request/response communication interface, such
+as that of the Jini ERI <a href="../../OutboundRequest.html">
+<code>OutboundRequest</code> </a> and <a
+href="../../InboundRequest.html"> <code>InboundRequest</code> </a>
+interfaces, on top of a bi-directional byte stream connection.
+
+The intended application of this protocol is to communicate Jini ERI
+remote method invocations over TCP and similar connection-oriented
+transport protocols, as well as over layered application-level
+protocols that can provide a connection-oriented byte stream
+interface.
+
+<h3>Requirements</h3>
+
+The design is intended to satisfy the following requirements:
+
+<ul>
+
+ <li>Be suitable for implementing the Jini ERI
+ <code>OutboundRequest</code> and <code>InboundRequest</code>
+ interfaces
+
+ <li>Support operating over a variety of connection types,
+ including TCP and SSL
+
+ <li>Provide connection robustness in the event of higher-level
+ failures, so that a connection does not need to be discarded after
+ incomplete marshalling or unmarshalling of data for a single
+ request or response being delivered on that connection
+
+ <li>Support communication of multiple concurrent remote method
+ invocations, with arbitrary execution dependencies among them,
+ over a single connection, with a flow control mechanism for
+ avoiding deadlock due to finite I/O buffer reservations
+
+</ul>
+
+Note that it is explicitly not a goal of the design at this time to
+support bi-directional request initiation over a single connection,
+such as for making remote "callbacks" over an incoming connection,
+because of the endpoint identification, security, and connection life
+cycle issues that are consequences of such a goal. Also not a
+requirement is flexibility of byte order for multi-byte data items
+directly defined by this protocol.
+
+<h3>Notation</h3>
+
+The following notation is used for the remainder of this page:
+
+<ul>
+
+ <li>A term with a specific meaning within the scope of this page
+ appears in <i>italics</i> upon first use with that meaning.
+
+ <li>The name of a type of message is presented in italics, mixed
+ case, and capitalized (for example: <i>ClientConnectionHeader</i>).
+
+ <li>The name of an item within a message is presented in bold,
+ mixed case, but not capitalized (for example: <b>initialRation</b>).
+
+</ul>
+
+<h3>Data Types and Encoding</h3>
+
+The term <i>byte</i> on this page means the same as "octet": an
+8-bit value.
+
+All integer values requiring more than one byte are represented in
+big-endian byte order. All integer values are unsigned.
+
+<p>Items in the protocol are of the following simple types:
+
+<dl>
+
+ <dt>flag:
+
+ <dd>1-bit value for which the value 0 indicates false, or that the
+ flag is not set, and the value 1 indicates true, or that the flag
+ is set.
+
+ <dt><i>n</i>-bit integer:
+
+ <dd><i>n</i>-bit value from 0 to (2^<i>n</i>)-1
+
+ <dt>sequence of <i>n</i> bytes:
+
+ <dd>sequence of <i>n</i> bytes of application data
+
+</dl>
+
+A sequence of bytes that is to be interpreted as a string of
+characters is encoded in UTF-8 (see <a
+href="http://ietf.org/rfc/rfc2279.txt">RFC 2279</a>).
+
+<h3>Connection Properties</h3>
+
+The <i>connection</i> underlying this protocol connects two
+<i>endpoints</i>, a <i>client</i> and a <i>server</i>, with the
+apparent behavior of two independent streams of bytes, one stream from
+client to server and the other from server to client. The connection
+must make reasonable attempts to guarantee reliable delivery, such
+that when a sequence of bytes is sent by one endpoint, it will either
+be received by the other endpoint at most once, in correct order with
+other sequences sent, or else a failure will be detected within a
+reasonable period of time (such as when delivery acknowledgment has
+not been received). The connection must not impose granularity
+restrictions on the size of sequences of bytes that can be flushed
+over the streams.
+
+<p>The client may use the connection to send requests to the server
+and receive responses in reply. The server may use the connection to
+receive requests and send responses in reply. (Note that the terms
+"client" and "server" in this page are only used as convenient labels
+to distinguish the two endpoints of the asymmetric connection over
+which this protocol operates; they do not necessarily correspond to
+higher-level application concepts of "client" and "server".)
+
+<p>How the connection is established is outside the scope of this
+protocol. A typical model, however, is for the server to passively
+listen on a network address for incoming connections and to publish
+that address to clients, and for the client to actively attempt to
+connect to the server at the published address; if the server accepts
+the connection, this protocol may then commence over the established
+connection.
+
+<h3>Message Structure</h3>
+
+The contents of each of the connection's streams is an 8-byte
+connection header followed by a sequence of variable length messages
+of the types described below. The initial byte of a message directly
+follows the final byte of the previous message (there is no padding to
+cause a particular alignment of message boundaries).
+
+<p>A message comprises a four-byte header optionally followed by
+more data, depending on the type of the message. The first byte of
+the message header defines the type of the message. Message types
+fall into two general categories: messages that pertain to the
+connection as a whole, which begin with a byte in the range 0-0xF,
+and messages that pertain to a particular session, which begin with a
+byte in the range 0x10-0xFF.
+
+<p>The following table lists the allowed ranges of values for the
+first byte of a message header, and what message type each range
+corresponds to. The value ranges are listed as both bit patterns, in
+which <tt>x</tt> represents a bit that may be either 0 or 1 for the
+given message type, and in hexadecimal, in which two hyphen-separated
+values indicate an inclusive range. Some of the hexadecimal ranges
+include more values than are legally allowed for the given message
+type, but the bit pattern range specifies the allowed values exactly.
+
+<blockquote>
+ <table summary="Describes allowable values and corresponding message types for the first byte of the message header"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">bit pattern</th>
+ <th align="center">hexadecimal range</th>
+ <th align="center">message type</th>
+ <tr>
+ <td align="center"><tt>00000000</tt>
+ <td align="center">00
+ <td><i>NoOperation</i>
+ <tr>
+ <td align="center"><tt>00000010</tt>
+ <td align="center">02
+ <td><i>Shutdown</i>
+ <tr>
+ <td align="center"><tt>00000100</tt>
+ <td align="center">04
+ <td><i>Ping</i>
+ <tr>
+ <td align="center"><tt>00000110</tt>
+ <td align="center">06
+ <td><i>PingAck</i>
+ <tr>
+ <td align="center"><tt>00001000</tt>
+ <td align="center">08
+ <td><i>Error</i>
+ <tr>
+ <td align="center"><tt>0001xxx0</tt>
+ <td align="center">10-1F
+ <td><i>IncrementRation</i>
+ <tr>
+ <td align="center"><tt>001000x0</tt>
+ <td align="center">20-23
+ <td><i>Abort</i>
+ <tr>
+ <td align="center"><tt>00110000</tt>
+ <td align="center">30
+ <td><i>Close</i>
+ <tr>
+ <td align="center"><tt>01000000</tt>
+ <td align="center">40
+ <td><i>Acknowledgment</i>
+ <tr>
+ <td align="center"><tt>100xxxx0</tt>
+ <td align="center">80-9F
+ <td><i>Data</i>
+ </table>
+</blockquote>
+
+It is a protocol violation to send a message with a first byte that
+does not match one of the above bit patterns.
+
+<h3>Sessions</h3>
+
+A request and its associated response are communicated over a
+<i>session</i>. An <i>established</i> session has an associated
+<i>session identifier</i> that is an integer between 0 and 127
+(inclusive). Thus, there can be at most 128 sessions concurrently
+established over one connection. The session identifier is included
+in the header of every message related to the associated session. In
+the structure of all message types, a session identifier is stored in
+a single byte with the most significant bit set to zero (and reserved
+for future use).
+
+<p>A session may be either established or <i>terminated</i> with
+respect to either endpoint. A session established with respect to an
+endpoint may also be <i>finished</i> with respect to that endpoint,
+meaning that the endpoint is finished sending data for that session.
+These and other session state changes occur as a result of messages
+sent for the associated session identifier.
+
+<p>For any transmitted message that affects the state of a session,
+the state change is clearly known first to the sender of the message
+(when the message is sent), and later to the receiver (when the
+message is received). All restrictions on what messages may be sent
+relating to the current state of a session require that there is some
+interleaved order of messages received and messages sent by a given
+endpoint for which the restrictions are satisfied.
+
+<h4>Session Establishment</h4>
+
+Only the client can establish new sessions (and thus only the client
+can initiate requests over the connection). To establish a new
+session, the client sends a <i>Data</i> message with the <b>open</b>
+flag set.
+
+<p>A session is established with respect to both endpoints when the
+client sends a <i>Data</i> message with the <b>open</b> flag set. The
+newly established session is associated with the session identifier
+contained in the message header. A session remains established with
+respect to a given endpoint until it becomes terminated with respect
+to that endpoint.
+
+<p>An established session is finished with respect to a given endpoint
+after the endpoint has sent a <i>Data</i> message with the <b>eof</b>
+flag set for the associated session identifier. A session finished
+with respect to a given endpoint still remains established with
+respect to that endpoint (and data still can be received) until it
+becomes terminated with respect to the endpoint. Note that a session
+can become both established and finished from a single <i>Data</i>
+message sent from the client, if both the <b>open</b> and the
+<b>eof</b> flags are set.
+
+<h4>Session Termination</h4>
+
+An established session is terminated with respect to the server after
+the server has sent a <i>Close</i> or an <i>Abort</i> message with the
+associated session identifier, after which the server can no longer
+use the session identifier to refer to that session. A session is
+terminated with respect to the client after the client has sent an
+<i>Abort</i> message with the associated session identifier.
+
+<p>The client may re-use a session identifier for establishing a new
+session after the previous session associated with that session
+identifier is terminated with respect to the client and the server, or
+after it is terminated with respect to the server and the client has
+sent a <i>Data</i> message with the <b>eof</b> flag set with the
+session identifier (after which the previous session associated with
+the session identifier becomes implicitly terminated with respect to
+the client).
+
+<h4>Flow Control</h4>
+
+Because sessions must be assumed to have arbitrary processing
+dependencies among them, it is a requirement of this protocol that the
+processing of any one session must not interfere with (and thus
+possibly be an inverse, deadlocking dependency for) any other session.
+Even without explicit processing dependencies among sessions, it would
+be undesirable for one session with blocked processing to starve the
+processing of other sessions. Therefore, the implementation must
+always be able to read more messages from the connection in a timely
+fashion, so that regardless of a state of any one session, a message
+waiting to be read for another session is not ignored indefinitely.
+For example, if the buffers allocated for holding data from one
+session become full and more data arrives for the session, this fact
+must not indefinitely postpone transmission and processing of data for
+any other session. Without a flow control mechanism (and without the
+burden of arbitrary buffering), the only way to avoid such deadlock or
+starvation conditions is to abort sessions that would otherwise
+interfere with timely message processing. This protocol does support
+a flow control mechanism to throttle incoming session data to support
+finite session buffer capacities without the need to abort sessions
+unnecessarily.
+
+<p>Each endpoint has two state values associated with each session:
+
+<dl>
+
+ <dt><i>inbound ration</i>
+
+ <dd>how many bytes of data may currently be received for the session
+
+ <dt><i>outbound ration</i>
+
+ <dd>how many bytes of data may currently be sent for the session
+
+</dl>
+
+Both ration values are integers in the range 0 to 0x7FFFFFFF,
+inclusive. The inbound ration is only meaningful while the session is
+established with respect to the endpoint and established but not
+finished with respect to the other endpoint. The outbound ration is
+only meaningful while the session is established but not finished with
+respect to the endpoint and established with respect to the other
+endpoint.
+
+<p>When a session is first established, the client's inbound ration is
+the value that the client sent in the <i>ClientConnectionHeader</i>
+for the connection, and the client's outbound ration is the value that
+the server sent in the <i>ServerConnectionHeader</i> for the
+connection (although it will likely be immediately decremented by the
+<b>length</b> value of the <i>Data</i> message used to establish the
+session). Also, the server's outbound ration is the value that the
+client sent in the <i>ClientConnectionHeader</i> for the connection,
+and the server's inbound ration is the value that the server sent in
+the <i>ServerConnectionHeader</i> for the connection (although it will
+likely be immediately decremented by the <b>length</b> value of the
+<i>Data</i> message used to establish the session).
+
+<p>An endpoint's outbound ration for a session is incremented when it
+receives an <i>IncrementRation</i> message for that session with a
+non-zero <b>increment</b>, and it is decremented when it sends a
+<i>Data</i> message for that session with a non-zero <b>length</b>.
+An endpoint's inbound ration for a session is incremented when it
+sends an <i>IncrementRation</i> message for that session with a
+non-zero <b>increment</b>, and it is decremented when it receives a
+<i>Data</i> message for that session with a non-zero <b>length</b>.
+It is a protocol violation for an endpoint to send a <i>Data</i>
+message with a <b>length</b> value greater than its current outbound
+ration.
+
+<h3>Connection Establishment</h3>
+
+When the protocol first commences over the connection, the client must
+first send a <i>ClientConnectionHeader</i> message to the server, and
+the server must wait to receive one. After receiving the
+<i>ClientConnectionHeader</i>, the server must then first send a
+<i>ServerConnectionHeader</i> message in response. After sending a
+<i>ServerConnectionHeader</i> message, the server can send other
+messages as otherwise permitted. After receiving a
+<i>ServerConnectionHeader</i> message, the client can send other
+messages as permitted, including a <i>Data</i> message with the
+<b>open</b> flag set in order to establish a session.
+
+<p>The sequence of messages sent by the server ends with a
+<i>Shutdown</i> message, an <i>Error</i> message, or closure of the
+connection's stream from the server. The sequence of messages sent by
+the client ends with an <i>Error</i> message or closure of the
+connection's stream from the client.
+
+<!--
+ !
+ ! ClientConnectionHeader Message
+ !
+ !-->
+
+<h3><i>ClientConnectionHeader</i> Message</h3>
+
+A <i>ClientConnectionHeader</i> message contains the following
+variable items:
+
+<blockquote>
+ <b>initialRation</b>: 16-bit integer<br>
+</blockquote>
+
+A <i>ClientConnectionHeader</i> message must and must only be sent by
+the client, as the first message of this protocol over the connection.
+
+<p>For all newly established sessions, the client's initial inbound
+ration and the server's initial outbound ration will be
+(<b>initialRation</b> * 256) if <b>initialRation</b> is non-zero, or
+infinity if <b>initialRation</b> is zero.
+
+<p>(If the server receives an invalid <i>ClientConnectionHeader</i>
+message, the server should respond with an <i>Error</i> message
+following the <i>ServerConnectionHeader</i> message.)
+
+<p>The structure of a <i>ClientConnectionHeader</i> message is 8
+bytes as follows:
+
+<blockquote>
+ <table summary="Describes the structure of a ClientConnectionHeader message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0 to 3
+ <td align="center"><tt>01001010<br>
+ 01101101<br>
+ 01110101<br>
+ 01111000<br></tt>
+ <td>magic number (ASCII "Jmux")
+ <tr>
+ <td align="center">4
+ <td align="center"><tt>00000001<br></tt>
+ <td>version
+ <tr>
+ <td align="center">5 to 6
+ <td align="center"><tt>xxxxxxxx<br>
+ xxxxxxxx<br></tt>
+ <td><b>initialRation</b>
+ <tr>
+ <td align="center">7
+ <td align="center"><tt>00000000<br></tt>
+ <td>reserved
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! ServerConnectionHeader Message
+ !
+ !-->
+
+<h3><i>ServerConnectionHeader</i> Message</h3>
+
+A <i>ServerConnectionHeader</i> message contains the following
+variable items:
+
+<blockquote>
+ <b>initialRation</b>: 16-bit integer<br>
+</blockquote>
+
+A <i>ServerConnectionHeader</i> message must and must only be sent by
+the server, as the first message of this protocol over the connection.
+
+<p>For all newly established sessions, the server's initial inbound
+ration and the client's initial outbound ration will be
+(<b>initialRation</b> * 256) if <b>initialRation</b> is non-zero, or
+infinity if <b>initialRation</b> is zero.
+
+<p>The structure of a <i>ServerConnectionHeader</i> message is 8 bytes as
+follows:
+
+<blockquote>
+ <table summary="Describes the structure of a ServerConnectionHeader message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0 to 3
+ <td align="center"><tt>01001010<br>
+ 01101101<br>
+ 01110101<br>
+ 01111000<br></tt>
+ <td>magic number (ASCII "Jmux")
+ <tr>
+ <td align="center">4
+ <td align="center"><tt>00000001<br></tt>
+ <td>version
+ <tr>
+ <td align="center">5 to 6
+ <td align="center"><tt>xxxxxxxx<br>
+ xxxxxxxx<br></tt>
+ <td><b>initialRation</b>
+ <tr>
+ <td align="center">7
+ <td align="center"><tt>00000000<br></tt>
+ <td>reserved
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! NoOperation Message
+ !
+ !-->
+
+<h3><i>NoOperation</i> Message</h3>
+
+A <i>NoOperation</i> message contains the following variable items:
+
+<blockquote>
+ <b>length</b>: 16-bit integer<br>
+ <b>data</b>: sequence of <b>length</b> bytes<br>
+</blockquote>
+
+A <i>NoOperation</i> message may be sent by the client or the server.
+A <i>NoOperation</i> message should be ignored by the receiver.
+
+<p>The structure of a <i>NoOperation</i> message is
+(4+<b>length</b>) bytes as follows:
+
+<blockquote>
+ <table summary="Describes the structure of a NoOperation message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>00000000<br></tt>
+ <td><i>NoOperation</i> message type identifier
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>00000000<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">2 to 3
+ <td align="center"><tt>xxxxxxxx<br>
+ xxxxxxxx<br></tt>
+ <td><b>length</b>
+ <tr>
+ <td align="center">4 to (4+<b>length</b>-1)
+ <td align="center">n/a
+ <td><b>data</b>
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! Shutdown Message
+ !
+ !-->
+
+<h3><i>Shutdown</i> Message</h3>
+
+<p>A <i>Shutdown</i> message contains the following variable items:
+
+<blockquote>
+ <b>length</b>: 16-bit integer<br>
+ <b>detail</b>: sequence of <b>length</b> bytes<br>
+</blockquote>
+
+The <i>Shutdown</i> message is used to indicate that the server is
+shutting down the connection in a graceful fashion.
+
+<p>A <i>Shutdown</i> message must only be sent by the server.
+
+<p>By definition, a <i>Shutdown</i> message is the last message of the
+protocol sent by the server over the connection; after sending a
+<i>Shutdown</i> message, the server will typically close the
+connection.
+
+<p>When the client receives a <i>Shutdown</i> message, it should
+discard the connection and consider all established sessions that were
+not finished with respect to the server as if they have been aborted
+(as with an <i>Abort</i> message) with no partial processing-- thus
+the client can safely retry such sessions on another connection
+without violating <i>at most once</i> execution semantics. Therefore,
+the server must only send a <i>Shutdown</i> message if it can
+guarantee that no currently established sessions have been processed
+with any possible side effects.
+
+<p>The server can use the <b>detail</b> item to provide the client
+with more information explaining the reason for the <i>Shutdown</i>
+message. The content of the <b>detail</b> item, if any, is a UTF-8
+encoded string of unspecified content.
+
+<p>The structure of a <i>Shutdown</i> message is (4+<b>length</b>)
+bytes as follows:
+
+<blockquote>
+ <table summary="Describes the structure of a Shutdown message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>00000010<br></tt>
+ <td><i>Shutdown</i> message type identifier
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>00000000<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">2 to 3
+ <td align="center"><tt>xxxxxxxx<br>
+ xxxxxxxx<br></tt>
+ <td><b>length</b>
+ <tr>
+ <td align="center">4 to (4+<b>length</b>-1)
+ <td align="center">n/a
+ <td><b>detail</b>
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! Ping Message
+ !
+ !-->
+
+<h3><i>Ping</i> Message</h3>
+
+<p>A <i>Ping</i> message contains the following variable items:
+
+<blockquote>
+ <b>cookie</b>: 16-bit integer
+</blockquote>
+
+The <i>Ping</i> message is used to test the liveness of the receiver.
+
+<p>A <i>Ping</i> message may be sent by the client or the server.
+
+<p>The sender may choose any arbitrary value for <b>cookie</b>. After
+sending a <i>Ping</i> message, the sender can expect the receiver to
+respond with exactly one corresponding <i>PingAck</i> message
+containing the same <b>cookie</b> value. The sender may expect the
+corresponding <i>PingAck</i> within a reasonable timeout, and if it is
+not received, the sender may consider the receiver to have gone down
+or become unreachable (such as due to a network partition), in which
+case it should discard the connection and consider all open sessions
+aborted (with partial processing, if the sender is the client).
+
+<p>The structure of a <i>Ping</i> message is 4 bytes as follows:
+
+<blockquote>
+ <table summary="Describes the structure of a Ping message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>00000100<br></tt>
+ <td><i>Ping</i> message type identifier
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>00000000<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">2 to 3
+ <td align="center"><tt>xxxxxxxx<br>
+ xxxxxxxx<br></tt>
+ <td><b>cookie</b>
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! PingAck Message
+ !
+ !-->
+
+<h3><i>PingAck</i> Message</h3>
+
+A <i>PingAck</i> message contains the following variable items:
+
+<blockquote>
+ <b>cookie</b>: 16-bit integer
+</blockquote>
+
+The <i>PingAck</i> message is used to respond to a <i>Ping</i>
+message.
+
+<p>A <i>PingAck</i> message may be sent by the client or the server,
+and must only be sent in response to exactly one previous <i>Ping</i>
+message received by the sender.
+
+<p>After receiving a <i>Ping</i> message with a given <b>cookie</b>
+value, an endpoint should immediately respond with a <i>PingAck</i>
+message with the same <b>cookie</b> value.
+
+<p>The structure of a <i>PingAck</i> message is 4 bytes as follows:
+
+<blockquote>
+ <table summary="Describes the structure of a PingAck message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>00000110<br></tt>
+ <td><i>PingAck</i> message type identifier
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>00000000<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">2 to 3
+ <td align="center"><tt>xxxxxxxx<br>
+ xxxxxxxx<br></tt>
+ <td><b>cookie</b>
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! Error Message
+ !
+ !-->
+
+<h3><i>Error</i> Message</h3>
+
+An <i>Error</i> message contains the following variable items:
+
+<blockquote>
+ <b>length</b>: 16-bit integer<br>
+ <b>detail</b>: sequence of <b>length</b> bytes<br>
+</blockquote>
+
+The <i>Error</i> message is used to indicate that the sender has
+detected a protocol violation somewhere in the messages that it has
+received.
+
+<p>An <i>Error</i> message may be sent by the client or the server.
+
+<p>By definition, an <i>Error</i> message is the last message of the
+protocol sent by the sender over the connection; after sending an
+<i>Error</i> message, the sender will typically close the connection.
+
+<p>When the client receives an <i>Error</i> message, it should discard
+the connection and consider all established sessions that were not
+finished with respect to the server as if they have been aborted (as
+with an <i>Abort</i> message) with possible partial processing-- thus
+the client cannot safely retry such sessions on another connection
+without violating <i>at most once</i> execution semantics.
+
+<p>When the server receives an <i>Error</i> message, it should discard
+the connection and consider all established sessions as if they have
+been aborted.
+
+<p>The sender can use the <b>detail</b> item to provide the receiver
+with more information explaining the reason for the <i>Error</i>
+message. The content of the <b>detail</b> item, if any, is a UTF-8
+encoded string of unspecified content.
+
+<p>The structure of an <i>Error</i> message is (4+<b>length</b>)
+bytes as follows:
+
+<blockquote>
+ <table summary="Describes the structure of an Error message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>00001000<br></tt>
+ <td><i>Error</i> message type identifier
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>00000000<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">2 to 3
+ <td align="center"><tt>xxxxxxxx<br>
+ xxxxxxxx<br></tt>
+ <td><b>length</b>
+ <tr>
+ <td align="center">4 to (4+<b>length</b>-1)
+ <td align="center">n/a
+ <td><b>detail</b>
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! IncrementRation Message
+ !
+ !-->
+
+<h3><i>IncrementRation</i> Message</h3>
+
+An <i>IncrementRation</i> message contains the following variable
+items:
+
+<blockquote>
+ <b>shift</b>: 3-bit integer<br>
+ <b>sessionID</b>: 7-bit integer<br>
+ <b>increment</b>: 16-bit integer<br>
+</blockquote>
+
+The <i>IncrementRation</i> message is used to indicate that more data
+can be received by the sender for a given session.
+
+<p>An <i>IncrementRation</i> message may be sent by the client or the
+server. The <b>sessionID</b> must identify a session established with
+respect to the sender. (In other words, the client must not send an
+<i>IncrementRation</i> message after sending an <i>Abort</i> message
+for the given session, and the server must not send an
+<i>IncrementMessage</i> after sending a <i>Close</i> or an
+<i>Abort</i> message for the given session.)
+
+<p>An <i>IncrementRation</i> message indicates that the sender is
+prepared to receive (<b>increment</b><<(<b>shift</b>*2)) more bytes
+for the session beyond its current inbound ration for the session
+identified by <b>sessionID</b>. After sending an
+<i>IncrementRation</i> message, the sender's inbound ration for the
+session is incremented by (<b>increment</b><<(<b>shift</b>*2)), and
+after receiving an <i>IncrementRation</i> message, the receiver's
+outbound ration is incremented by
+(<b>increment</b><<(<b>shift</b>*2)). It is a protocol violation for
+an <i>IncrementRation</i> message to cause the sender's inbound ration
+to exceed 0x7FFFFFFF. (Therefore, if the receiver's outbound ration
+is caused to exceed 0x7FFFFFFF, the receiver should respond with an
+<i>Error</i> message.)
+
+<p>If the session is finished (or terminated) with respect to the
+receiver, this message should be ignored.
+
+<p>For a given session, if an endpoint is expecting more data from the
+other endpoint but its inbound ration is zero, then it must send an
+<i>IncrementRation</i> message (with a non-zero increment) for that
+session.
+
+<p>The structure of an <i>IncrementRation</i> message is 4 bytes as
+follows:
+
+<blockquote>
+ <table summary="Describes the structure of an IncrementRation message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>0001----<br></tt>
+ <td><i>IncrementRation</i> message type identifier
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>----xxx-<br></tt>
+ <td><b>shift</b>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>-------0<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>0-------<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>-xxxxxxx<br></tt>
+ <td><b>sessionID</b>
+ <tr>
+ <td align="center">2 to 3
+ <td align="center"><tt>xxxxxxxx<br>
+ xxxxxxxx<br></tt>
+ <td><b>increment</b>
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! Abort Message
+ !
+ !-->
+
+<h3><i>Abort</i> Message</h3>
+
+An <i>Abort</i> message contains the following variable items:
+
+<blockquote>
+ <b>partial</b>: flag<br>
+ <b>sessionID</b>: 7-bit integer<br>
+ <b>length</b>: 16-bit integer<br>
+ <b>detail</b>: sequence of <b>length</b> bytes<br>
+</blockquote>
+
+The <i>Abort</i> message is used to terminate a session abruptly,
+usually before its expected exchange of data has completed.
+
+<p>An <i>Abort</i> message may be sent by the client or the server.
+The <b>partial</b> flag must only be set when the sender is the server.
+The <b>sessionID</b> must identify a session established with respect
+to the sender.
+
+<p>An <i>Abort</i> message causes the session to be terminated with
+respect to the sender; the sender must not send any further messages
+for the session.
+
+<p>If the session is not yet terminated with respect to the receiver,
+then the receiver should cease sending messages for the session,
+except to respond in a timely fashion with an <i>Abort</i> message for
+the session so that it will be terminated with respect to the
+receiver.
+
+<p>If the client receives an <i>Abort</i> message with the
+<b>partial</b> flag set, then it must assume that any data sent over
+the session has been at least partially processed with any possible
+side effects-- thus the client cannot safely retry the session again
+without violating <i>at most once</i> execution semantics. If the
+client receives an <i>Abort</i> message with the <b>partial</b> flag
+not set, then it may assume that no data sent over the session has
+been even partially executed with any possible side effects-- thus the
+client can safely retry the session again without violating <i>at most
+once</i> execution semantics. Therefore, the server must only send an
+<i>Abort</i> message with the <b>partial</b> flag not set if it can
+guarantee that no amount of the data received for the session has been
+processed with any possible side effects.
+
+<p>The sender can use the <b>detail</b> item to provide the receiver
+with more information explaining the reason for the <i>Abort</i>
+message. The content of the <b>detail</b> item, if any, is a UTF-8
+encoded string of unspecified content.
+
+<p>The structure of an <i>Abort</i> message is (4+<b>length</b>)
+bytes as follows:
+
+<blockquote>
+ <table summary="Describes the structure of an Abort message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>001000--<br></tt>
+ <td><i>Abort</i> message type identifier
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>------x-<br></tt>
+ <td><b>partial</b>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>-------0<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>0-------<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>-xxxxxxx<br></tt>
+ <td><b>sessionID</b>
+ <tr>
+ <td align="center">2 to 3
+ <td align="center"><tt>xxxxxxxx<br>
+ xxxxxxxx<br></tt>
+ <td><b>length</b>
+ <tr>
+ <td align="center">4 to (4+<b>length</b>-1)
+ <td align="center">n/a
+ <td><b>detail</b>
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! Close Message
+ !
+ !-->
+
+<h3><i>Close</i> Message</h3>
+
+A <i>Close</i> message contains the following variable items:
+
+<blockquote>
+ <b>sessionID</b>: 7-bit integer<br>
+</blockquote>
+
+The <i>Close</i> message is used to indicate that the server is done
+with a particular session in the normal fashion.
+
+<p>A <i>Close</i> message must only be sent by the server. The
+<b>sessionID</b> must identify a session finished (but established)
+with respect to the server.
+
+<p>A <i>Close</i> message causes the session to be terminated with
+respect to the server; the server must not send any further messages
+for the session.
+
+<p>The server should send a <i>Close</i> message in a timely fashion
+after the session is finished with respect to the server and either
+finished with respect to the client or the server is not interested in
+the remainder of the request data, so that the client may reuse the
+session identifier. When possible, the server should use the
+abbreviated form of the <i>Close</i> message: the <b>close</b> flag of
+the <i>Data</i> message.
+
+<p>If the session is finished (or terminated) with respect to the
+client, then after receipt of a <i>Close</i> message for the session,
+the client may reuse the session identifier.
+
+<p>If the session is not yet terminated with respect to the client,
+then the client should cease sending messages for the session, except
+to respond in a timely fashion with an <i>Abort</i> message for the
+session so that it will be terminated with respect to the client as
+well, and then the client may reuse the session identifier. Note that
+in this case, the client must not consider the session to have failed;
+instead, it must provide the data received as the complete response,
+and it should consider that the server is not interested in the
+remainder of the request data, so it should be silently discarded.
+
+<p>The structure of a <i>Close</i> message is 4 bytes as follows:
+
+<blockquote>
+ <table summary="Describes the structure of a Close message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>00110000<br></tt>
+ <td><i>Close</i> message type identifier
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>0-------<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>-xxxxxxx<br></tt>
+ <td><b>sessionID</b>
+ <tr>
+ <td align="center">2 to 3
+ <td align="center"><tt>00000000<br>
+ 00000000<br></tt>
+ <td>reserved
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! Acknowledgment Message
+ !
+ !-->
+
+<h3><i>Acknowledgment</i> Message</h3>
+
+An <i>Acknowledgment</i> message contains the following variable
+items:
+
+<blockquote>
+ <b>sessionID</b>: 7-bit integer<br>
+</blockquote>
+
+The <i>Acknowledgment</i> message is used to indicate that the client
+is done processing the complete response data for a particular
+session.
+
+<p>An <i>Acknowledgment</i> message must only be sent by the client.
+The <b>sessionID</b> must identify a session established with respect
+to the client. An <i>Acknowledgment</i> must only be sent after the
+server has sent a <i>Data</i> message with the <b>ackRequired</b> flag
+set for the session, and it must only be sent once for the session.
+
+<p>Upon receipt of an <i>Acknowledgment</i> message, the server may
+consider that the client has finished processing the response.
+
+<p>The structure of an <i>Acknowledgment</i> message is 4 bytes as
+follows:
+
+<blockquote>
+ <table summary="Describes the structure of an Acknowledgment message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>01000000<br></tt>
+ <td><i>Acknowledgment</i> message type identifier
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>0-------<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>-xxxxxxx<br></tt>
+ <td><b>sessionID</b>
+ <tr>
+ <td align="center">2 to 3
+ <td align="center"><tt>00000000<br>
+ 00000000<br></tt>
+ <td>reserved
+ </table>
+</blockquote>
+
+<!--
+ !
+ ! Data Message
+ !
+ !-->
+
+<h3><i>Data</i> Message</h3>
+
+A <i>Data</i> message contains the following variable items:
+
+<blockquote>
+ <b>open</b>: flag<br>
+ <b>eof</b>: flag<br>
+ <b>close</b>: flag<br>
+ <b>ackRequired</b>: flag<br>
+ <b>sessionID</b>: 7-bit integer<br>
+ <b>length</b>: 16-bit integer<br>
+ <b>data</b>: sequence of <b>length</b> bytes<br>
+</blockquote>
+
+The <i>Data</i> message is used by the client to establish a session,
+by the client or the server to transmit fragments of data for a
+session and to signal the end of data for a session, and by the server
+to terminate the session and to request an acknowledgment for complete
+processing of the data sent.
+
+<p>A <i>Data</i> message may be sent by the client or the server. The
+<b>open</b> flag must only be set when the sender is the client, and
+the <b>close</b> and <b>ackRequired</b> flags must only be set when
+the sender is the server. The <b>close</b> and the <b>ackRequired</b>
+flags must only be set if the <b>eof</b> flag is also set.
+
+<p>If the <b>open</b> flag is not set, then <b>sessionID</b> must
+identify a session established and not finished with respect to the
+sender. If the <b>open</b> flag is set, then <b>sessionID</b> must
+not identify an established session, and a new session is established
+associated with the session identifier <b>sessionID</b>.
+
+<p>The <b>data</b> of the message represents the next fragment of data
+that constitutes the request data (if sent by the client) or the
+response data (if sent by the server) of the session. It is a
+protocol violation for an endpoint to send a <i>Data</i> message with
+a <b>length</b> value greater than its current outbound ration for the
+session. (Therefore, if the receiver's inbound ration is less than
+<b>length</b>, the receiver should respond with an <i>Error</i>
+message.)
+
+After sending a <i>Data</i> message, the sender's outbound ration is
+decremented by <b>length</b>, and after receiving a <i>Data</i>
+message, the receiver's inbound ration is decremented by
+<b>length</b>.
+
+<p>The <b>eof</b> flag marks this message as containing the last
+fragment of data for the session, and thus the request or response
+data has been completely transmitted and the session is finished with
+respect to the sender.
+
+<p>The meaning of the <i>close</i> flag being set is equivalent to the
+meaning of the same <i>Data</i> message sent without the <b>close</b>
+flag being set immediately followed by a <i>Close</i> message with the
+same <b>sessionID</b>.
+
+<p>The <b>ackRequired</b> flag indicates that the server is interested
+in being notified with a positive acknowledgment when the client is
+done processing the response data for the session. Such a positive
+acknowledgment takes the form of an <i>Acknowledgment</i> message
+received from the client with the same <b>sessionID</b>. If instead
+the server receives an <i>Abort</i> message with the same
+<b>sessionID</b>, or the server receives a <i>Data</i> message with
+the <b>open</b> flag set and the same <b>sessionID</b>, or the
+connection is closed, then that constitutes a negative acknowledgment
+(as a positive acknowledgment could never be received).
+
+<p>After the client has received a <i>Data</i> message with the
+<b>ackRequired</b> flag set, it should send an <i>Acknowledgment</i>
+message with the same <b>sessionID</b> in a timely fashion after it is
+done processing the response data.
+
+
+<p>The structure of a <i>Data</i> message is (4+<b>length</b>) bytes
+as follows:
+
+<blockquote>
+ <table summary="Describes the structure of a Data message"
+cellspacing="0" cellpadding="2" border="1">
+ <tr>
+ <th align="center">offset</th>
+ <th align="center">bit pattern</th>
+ <th align="center">content</th>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>100-----<br></tt>
+ <td><i>Data</i> message type identifier
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>---x----<br></tt>
+ <td><b>open</b>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>----x---<br></tt>
+ <td><b>close</b>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>-----x--<br></tt>
+ <td><b>eof</b>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>------x-<br></tt>
+ <td><b>ackRequired</b>
+ <tr>
+ <td align="center">0
+ <td align="center"><tt>-------0<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>0-------<br></tt>
+ <td>reserved
+ <tr>
+ <td align="center">1
+ <td align="center"><tt>-xxxxxxx<br></tt>
+ <td><b>sessionID</b>
+ <tr>
+ <td align="center">2 to 3
+ <td align="center"><tt>xxxxxxxx<br>
+ xxxxxxxx<br></tt>
+ <td><b>length</b>
+ <tr>
+ <td align="center">4 to (4+<b>length</b>-1)
+ <td align="center">n/a
+ <td><b>data</b>
+ </table>
+</blockquote>
+
+<hr>
+
+<hr>
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+</body>
+</html>